API de Nokfi

Autenticación

Crea una clave en Desarrolladores → Claves y envíala en cada petición:

Authorization: Bearer nk_live_…

Cada análisis o extracción gasta 1 de tu cuota diaria (la misma que en la web); las herramientas fiscales no gastan cuota. Máximo 30 peticiones por minuto y clave. Si tu plan baja a Mini, las claves reales dejan de funcionar (401 api_plan_required) pero no se borran.

Endpoints

• GET/api/v1/usageTu cuota de hoy
• POST/api/v1/invoices/extractExtraer facturas con validaciones
• POST/api/v1/analyzeLanzar un análisis
• GET/api/v1/analysesListar análisis
• GET/api/v1/analyses/{id}Obtener un informe
• GET/api/v1/jobs/{id}Estado y resultado de un trabajo
• POST/api/v1/invoicesEmitir una factura (Idempotency-Key obligatoria)
• GET/api/v1/invoices/{id}Factura con líneas, eventos y VERI*FACTU
• POST/api/v1/invoices/{id}/rectifyEmitir una rectificativa
• POST/api/v1/invoices/{id}/cancelAnular una factura emitida por error
• POST/api/v1/invoices/{id}/statusRechazada, aceptada, cobrada o no cobrada
• GET/api/v1/invoices/{id}/pdf · /xmlPDF y factura electrónica (UBL, Facturae, Factur-X)
• GET · POST/api/v1/customersLibreta de clientes
• GET · POST/api/v1/webhooksTus webhooks (crear, listar, borrar, probar)
• GET/api/v1/tax/nifValidar NIF, NIE o CIF
• POST/api/v1/tax/vatIVA y recargo de equivalencia
• POST/api/v1/tax/withholdingRetención de IRPF
• POST/api/v1/tax/model-130Estimar el modelo 130
• GET/api/v1/tax/quarterResumen del trimestre desde tu libro
• GET/api/v1/tax/calendarPróximos plazos fiscales
• GET/api/v1/openapi.jsonEspecificación OpenAPI

Tipos de análisis: excel (módulos stock, ventas, servicios, entradas, caja, total), compare (dos periodos), folder (varios documentos con una petición) y cuestionario (30 respuestas sí/no).

Facturas: del PDF al JSON validado

Envía hasta 5 facturas por petición (PDF, JPG, PNG o WebP en base64, o el texto ya extraído) y recibe siempre el mismo JSON. Cada petición gasta 1 análisis de tu cuota. No guardamos el archivo ni los datos (en modo asíncrono, el resultado se guarda 24 h para que lo recojas). Las facturas electrónicas (Facturae, UBL, CII o Factur-X/ZUGFeRD con el XML dentro del PDF) se leen tal cual, sin IA: el resultado es exacto y no gastan cuota.

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 comprueba cada factura por su cuenta, sin fiarse de la IA: que base + IVA − retención cuadre con el total, el dígito de control del NIF/CIF/NIE, que la fecha sea válida y no futura y que el tipo de IVA sea habitual. Lo que no cuadra llega en warnings. Los PDF escaneados vuelven en errors (pdf_scanned): envíalos como imagen.

{
  "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": []
}

Emitir facturas

Emite facturas en nombre de tu cuenta con la misma lógica que la app: numeración correlativa sin huecos, IVA por tipo, retención, recargo de equivalencia, apunte en el libro, PDF, factura electrónica y registro VERI*FACTU con huella encadenada. No usa IA ni gasta cuota.

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 es obligatoria al emitir y al rectificar: si reintentas con la misma clave recibes la misma factura y nunca una duplicada. Una factura emitida no se edita ni se borra: se rectifica o se anula. Con una clave nk_test_ las facturas son de prueba (TEST-…), con su propia numeración, y no entran en el libro ni van a la AEAT. Tus datos de emisor se completan en la app.

Herramientas fiscales sin IA

Cálculos de la fiscalidad española hechos por Nokfi, no por un modelo: validar NIF/NIE/CIF con su dígito de control, IVA con o sin IVA incluido y recargo de equivalencia, retenciones de IRPF, el pago del modelo 130 y el calendario fiscal. Respuesta al momento y sin gastar cuota. Son orientativos (régimen general).

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, … }

Asíncrono, webhooks e idempotencia

Para lotes o flujos que no pueden esperar, añade ?async=true (o la cabecera Prefer: respond-async) a analyze o invoices/extract: respondemos 202 con un trabajo al momento y el resultado queda 24 h en /api/v1/jobs/{id}. Los errores de formato y de cuota se devuelven al momento, sin crear el trabajo.

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": [ … ] } }

Envía una cabecera Idempotency-Key (por ejemplo, el id de la factura) en cada POST: si tu flujo reintenta, devolvemos la misma respuesta (o el mismo trabajo) sin ejecutarlo ni cobrarlo dos veces. Guardamos la clave 24 h.

Con un webhook no hace falta preguntar: Nokfi avisa a tu URL cuando termina un análisis (analysis.completed) o un trabajo (job.completed, job.failed), al llegar al 80 % y al 100 % de la cuota (quota.threshold) y 7 días y 1 día antes de cada plazo fiscal (fiscal.deadline). Cada aviso va firmado con HMAC-SHA256 y se reintenta durante unas 20 h si tu servidor no responde. Para facturas: invoice.issued, invoice.cancelled, invoice.rejected, invoice.accepted, invoice.paid e invoice.unpaid (también las emitidas desde la web), y verifactu.accepted / verifactu.rejected con la respuesta de la AEAT a cada registro.

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": [ … ] } } }

Claves de prueba (nk_test_)

Disponibles en todos los planes, también en Mini. Validan la entrada igual que las reales y devuelven datos de ejemplo con la misma forma, sin gastar cuota ni guardar nada. Los trabajos y webhooks funcionan igual, con livemode: false. Úsalas para montar y probar tus flujos antes de pasar a nk_live_.

Servidor MCP para agentes de IA

Conecta Nokfi como herramienta de Claude, ChatGPT, Cursor o el AI Agent de n8n. Usa la misma clave de API, la misma cuota y las mismas reglas que la API.

Herramientas: 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 y 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

Ejemplo

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 }
      ]}]
    }
  }'

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

Ejemplo con n8n

1. Crea una credencial «Header Auth / Bearer» con tu clave nk_live_…
2. Añade un nodo HTTP Request: POST https://nokfi.app/api/v1/analyze con cuerpo JSON
3. Usa $json.report.summary o $json.report.priorities en los nodos siguientes (email, Slack, hoja…)

{
  "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 }}" } }
  ]
}

Plantillas de n8n

• Facturas de Gmail a Google Sheets · JSON
• Carpeta de Drive a resumen mensual por email · JSON
• Informe semanal de caja a Telegram · JSON