Nokfi API

Authentication

Create a key in Developers → Keys and send it with every request:

Authorization: Bearer nk_live_…

Each analysis or extraction uses 1 of your daily quota (the same as on the web); the tax tools use no quota. Up to 30 requests per minute per key. If your plan drops to Mini, live keys stop working (401 api_plan_required) but are not deleted.

Endpoints

• GET/api/v1/usageYour quota today
• POST/api/v1/invoices/extractExtract invoices with validation
• POST/api/v1/analyzeRun an analysis
• GET/api/v1/analysesList analyses
• GET/api/v1/analyses/{id}Get a report
• GET/api/v1/jobs/{id}Status and result of a job
• POST/api/v1/invoicesIssue an invoice (Idempotency-Key required)
• GET/api/v1/invoices/{id}Invoice with lines, events and VERI*FACTU
• POST/api/v1/invoices/{id}/rectifyIssue a corrective invoice
• POST/api/v1/invoices/{id}/cancelCancel an invoice issued by mistake
• POST/api/v1/invoices/{id}/statusRejected, accepted, paid or unpaid
• GET/api/v1/invoices/{id}/pdf · /xmlPDF and e-invoice (UBL, Facturae, Factur-X)
• GET · POST/api/v1/customersCustomer address book
• GET · POST/api/v1/webhooksYour webhooks (create, list, delete, test)
• GET/api/v1/tax/nifValidate NIF, NIE or CIF
• POST/api/v1/tax/vatVAT and equivalence surcharge
• POST/api/v1/tax/withholdingIRPF withholding
• POST/api/v1/tax/model-130Estimate Modelo 130
• GET/api/v1/tax/quarterQuarter summary from your ledger
• GET/api/v1/tax/calendarUpcoming tax deadlines
• GET/api/v1/openapi.jsonOpenAPI specification

Analysis types: excel (modules stock, ventas, servicios, entradas, caja, total), compare (two periods), folder (several documents with one request) and cuestionario (30 yes/no answers).

Invoices: from PDF to validated JSON

Send up to 5 invoices per request (PDF, JPG, PNG or WebP in base64, or text you already extracted) and always get the same JSON back. Each request uses 1 analysis from your quota. We store neither the file nor the data (in async mode, the result is kept for 24 h so you can collect it). E-invoices (Facturae, UBL, CII or Factur-X/ZUGFeRD with the XML inside the PDF) are read as they are, without AI: the result is exact and they don't use quota.

curl -X POST https://nokfi.app/api/v1/invoices/extract \
  -H "Authorization: Bearer nk_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d "{\"files\": [{\"name\": \"factura.pdf\", \"mime\": \"application/pdf\",
        \"data\": \"$(base64 -w0 factura.pdf)\"}]}"

Nokfi checks every invoice itself, without trusting the AI: base + VAT − withholding must match the total, the NIF/CIF/NIE check digit, a valid, non-future date and a usual VAT rate. Anything that doesn’t add up comes back in warnings. Scanned PDFs come back in errors (pdf_scanned): send them as images.

{
  "invoices": [{
    "file_name": "factura.pdf",
    "issuer_name": "Talleres Ruiz SL", "issuer_nif": "B12345674",
    "invoice_number": "F-2026-017", "invoice_date": "2026-09-14",
    "base": 1000, "vat_rate": 21, "vat_amount": 210, "irpf_amount": 0, "total": 1210,
    "checks": { "totals_ok": true, "nif_valid": true, "recipient_nif_valid": null,
                "date_valid": true, "vat_rate_valid": true },
    "warnings": []
  }],
  "errors": []
}

Issue invoices

Issue invoices in your account’s name with the same logic as the app: gap-free numbering, VAT per rate, withholding, equivalence surcharge, an entry in your books, PDF, e-invoice and a VERI*FACTU record with a chained fingerprint. No AI and no quota.

curl -X POST https://nokfi.app/api/v1/invoices \
  -H "Authorization: Bearer nk_live_TU_CLAVE" \
  -H "Idempotency-Key: pedido-1001" \
  -H "Content-Type: application/json" \
  -d '{ "customer": { "name": "Bodegas Sur SA", "tax_id": "A58818501",
        "address": "Ctra. Jerez 4", "postal_code": "11401", "city": "Jerez" },
        "irpf_rate": 15,
        "lines": [{ "description": "Diseño de etiqueta", "quantity": 1, "unit_price": 800, "vat_rate": 21 }] }'
# → 201 { "id": 42, "number": "F2026-0001", "kind": "F1", "base": 800, "vat_amount": 168,
#         "irpf_amount": 120, "total": 848, "livemode": true, … }

curl https://nokfi.app/api/v1/invoices/42/pdf -H "Authorization: Bearer nk_live_TU_CLAVE" -o F2026-0001.pdf

Idempotency-Key is required to issue and to correct: retrying with the same key returns the same invoice, never a duplicate. An issued invoice is never edited or deleted: it is corrected or cancelled. With an nk_test_ key invoices are test documents (TEST-…) with their own numbering that never reach your books or the AEAT. Your issuer details are filled in in the app.

Tax tools without AI

Spanish tax calculations done by Nokfi, not by a model: validate NIF/NIE/CIF with its check digit, VAT with or without VAT included and the equivalence surcharge, IRPF withholding, the Modelo 130 payment and the tax calendar. Instant answers with no quota used. They are estimates (general regime).

curl "https://nokfi.app/api/v1/tax/nif?value=B12345674" \
  -H "Authorization: Bearer nk_live_TU_CLAVE"

curl -X POST https://nokfi.app/api/v1/tax/withholding \
  -H "Authorization: Bearer nk_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "base": 1000, "type": "professional" }'
# → { "withholding_rate": 15, "withholding_amount": 150, "vat_amount": 210, "total_invoice": 1060, … }

Async, webhooks and idempotency

For batches or workflows that can’t wait, add ?async=true (or the Prefer: respond-async header) to analyze or invoices/extract: we answer 202 with a job straight away and the result stays for 24 h at /api/v1/jobs/{id}. Format and quota errors come back immediately, without creating the job.

curl -X POST "https://nokfi.app/api/v1/invoices/extract?async=true" \
  -H "Authorization: Bearer nk_live_TU_CLAVE" \
  -H "Idempotency-Key: factura-2026-017" \
  -H "Content-Type: application/json" \
  -d '{ "files": [{ "name": "f.pdf", "mime": "application/pdf", "data": "JVBERi0x…" }] }'
# → 202 { "id": "job_3f9c…", "status": "queued", … }

curl https://nokfi.app/api/v1/jobs/job_3f9c… -H "Authorization: Bearer nk_live_TU_CLAVE"
# → { "status": "succeeded", "result": { "invoices": [ … ] } }

Send an Idempotency-Key header (for example, the invoice id) with every POST: if your workflow retries, we return the same response (or the same job) without running or charging it twice. We keep the key for 24 h.

With a webhook you don’t need to poll: Nokfi notifies your URL when an analysis finishes (analysis.completed) or a job does (job.completed, job.failed), at 80 % and 100 % of your quota (quota.threshold) and 7 days and 1 day before each tax deadline (fiscal.deadline). Every notification is signed with HMAC-SHA256 and retried for about 20 h if your server doesn’t answer. For invoices: invoice.issued, invoice.cancelled, invoice.rejected, invoice.accepted, invoice.paid and invoice.unpaid (also for invoices issued on the web), plus verifactu.accepted / verifactu.rejected with the AEAT’s answer for each record.

POST https://tu-servidor/webhook
Nokfi-Signature: t=1790000000,v1=5f2b…   (HMAC-SHA256 de "t.cuerpo" con tu whsec_…)
Nokfi-Event: job.completed
Nokfi-Event-Id: evt_91c0…

{ "id": "evt_91c0…", "type": "job.completed", "created_at": "2026-10-01T09:12:03Z",
  "livemode": true, "data": { "job_id": "job_3f9c…", "kind": "invoices.extract",
  "status": "succeeded", "result": { "invoices": [ … ] } } }

Test keys (nk_test_)

Available on every plan, Mini included. They validate input just like live keys and return sample data with the same shape, without using quota or storing anything. Jobs and webhooks work the same, with livemode: false. Use them to build and test your workflows before moving to nk_live_.

MCP server for AI agents

Connect Nokfi as a tool for Claude, ChatGPT, Cursor or n8n’s AI Agent. It uses the same API key, the same quota and the same rules as the API.

Tools: extract_invoices, analyze, validate_tax_id, calculate_vat, calculate_withholding, estimate_model_130, fiscal_calendar, get_usage, list_analyses, get_analysis, issue_invoice, list_invoices, get_invoice, cancel_invoice and set_invoice_status.

claude mcp add --transport http nokfi https://nokfi.app/api/mcp \
  --header "Authorization: Bearer nk_live_TU_CLAVE"

{
  "mcpServers": {
    "nokfi": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://nokfi.app/api/mcp",
               "--header", "Authorization: Bearer nk_live_TU_CLAVE"]
    }
  }
}

{
  "mcpServers": {
    "nokfi": {
      "url": "https://nokfi.app/api/mcp",
      "headers": { "Authorization": "Bearer nk_live_TU_CLAVE" }
    }
  }
}

Endpoint: https://nokfi.app/api/mcp
Server Transport: HTTP Streamable
Authentication: Bearer Auth → nk_live_TU_CLAVE

Example

curl -X POST https://nokfi.app/api/v1/analyze \
  -H "Authorization: Bearer nk_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "excel",
    "lang": "es",
    "title": "Ventas de septiembre",
    "data": {
      "module": "ventas",
      "files": [{ "name": "ventas.csv", "rows": [
        { "producto": "Camiseta", "unidades": 12, "importe": 240 },
        { "producto": "Gorra", "unidades": 3, "importe": 45 }
      ]}]
    }
  }'

Response: { id, type, title, report: { summary, key_figures, strengths, priorities, action_plan, glossary }, actions }.

Example with n8n

1. Create a “Header Auth / Bearer” credential with your nk_live_… key
2. Add an HTTP Request node: POST https://nokfi.app/api/v1/analyze with a JSON body
3. Use $json.report.summary or $json.report.priorities in the following nodes (email, Slack, sheet…)

{
  "nodes": [
    { "name": "Cada lunes", "type": "n8n-nodes-base.scheduleTrigger",
      "parameters": { "rule": { "interval": [{ "field": "weeks", "triggerAtDay": [1], "triggerAtHour": 8 }] } } },
    { "name": "Leer hoja de ventas", "type": "n8n-nodes-base.googleSheets",
      "parameters": { "operation": "read" } },
    { "name": "Analizar con Nokfi", "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "method": "POST", "url": "https://nokfi.app/api/v1/analyze",
        "authentication": "genericCredentialType", "genericAuthType": "httpBearerAuth",
        "sendBody": true, "specifyBody": "json",
        "jsonBody": "={{ { type: 'excel', lang: 'es', data: { module: 'ventas', files: [{ name: 'ventas', rows: $input.all().map(i => i.json).slice(0, 5000), total_rows: $input.all().length }] } } }}"
      } },
    { "name": "Enviar resumen", "type": "n8n-nodes-base.emailSend",
      "parameters": { "subject": "Informe Nokfi", "text": "={{ $json.report.summary }}" } }
  ]
}

n8n templates

• Invoices from Gmail to Google Sheets · JSON
• Drive folder to monthly email summary · JSON
• Weekly cash report to Telegram · JSON