API de extracción de facturas: guía para developers (con código)

Una guía práctica para integrar la extracción de facturas en tu software: autenticación con API Key, la primera llamada con curl, Python y Node, el formato de la respuesta JSON y buenas prácticas con la confianza por campo y los webhooks.

En este artículo
  1. 1. Autenticación
  2. 2. Tu primera llamada
  3. 3. La respuesta
  4. 4. Buenas prácticas
  5. 5. De la prueba a producción

Si tu producto recibe facturas y necesitas convertirlas en datos, una API de extracción te ahorra construir todo el pipeline de OCR y parsing. Esta guía muestra, con código, lo que cuesta integrarla: en la práctica, una sola llamada HTTP.

Tienes la referencia completa de endpoints y campos en la página de la API; aquí vamos al grano con ejemplos.

1. Autenticación

Genera una API Key desde tu panel (tienen el prefijo ik_) y envíala en la cabecera X-Api-Key de cada petición. El secreto se almacena hasheado con SHA-256 y puedes revocarlo cuando quieras.

2. Tu primera llamada

El endpoint principal es POST /api/v1/invoices/scan. Le envías el fichero y te devuelve el JSON con los campos extraídos.

curl

curl https://invoicedata.es/api/v1/invoices/scan \
  -H "X-Api-Key: ik_tu_clave_secreta" \
  -F "file=@factura.pdf"

Python (con requests)

import requests

resp = requests.post(
    "https://invoicedata.es/api/v1/invoices/scan",
    headers={"X-Api-Key": "ik_tu_clave_secreta"},
    files={"file": open("factura.pdf", "rb")},
)
data = resp.json()
print(data["vendor_tax_id"], data["total"])

Node.js (con fetch y FormData)

import { readFileSync } from "node:fs";

const form = new FormData();
form.append("file", new Blob([readFileSync("factura.pdf")]), "factura.pdf");

const resp = await fetch("https://invoicedata.es/api/v1/invoices/scan", {
  method: "POST",
  headers: { "X-Api-Key": "ik_tu_clave_secreta" },
  body: form,
});
const data = await resp.json();
console.log(data.vendor_tax_id, data.total);

3. La respuesta

Recibes un JSON con los campos fiscales ya estructurados:

{
  "vendor_name": "Suministros García S.L.",
  "vendor_tax_id": "B12345678",
  "invoice_number": "2026-0042",
  "invoice_date": "2026-03-14",
  "subtotal": 1000.00,
  "tax_amount": 210.00,
  "withholding_amount": 150.00,
  "total": 1060.00,
  "payment_method": "Transferencia",
  "payment_terms": "30 días fecha factura",
  "confidence": 0.98,
  "field_confidence": { "vendor_tax_id": 0.99, "total": 0.98 },
  "line_items": [
    { "description": "Material de oficina", "product_code": "REF-4410",
      "quantity": 10, "unit": "caja", "unit_price": 100.00,
      "discount": null, "base": 1000.00,
      "tax_rate": 21.0, "tax_amount": 210.00, "amount": 1210.00 }
  ]
}

Los nombres y tipos de campo son estables entre versiones menores, para que tu integración no se rompa. Si quieres entender la diferencia con un OCR genérico, lo vemos en OCR de facturas con API.

4. Buenas prácticas

  • Usa la confianza: confidence es la del documento y field_confidence la de cada campo por separado. Pon el umbral campo a campo —sé exigente con el NIF y con los importes, generoso con la dirección— y manda a revisión humana solo lo que lo necesite, en vez de la factura entera.
  • Empieza con pocas facturas: durante el desarrollo trabaja con un puñado de documentos reales y variados —una con dos tipos de IVA, otra con retención, alguna escaneada— en vez de con cien iguales. Los casos raros salen antes así.
  • Evita el polling: configura un webhook para recibir un aviso cuando cada factura termina de procesarse.
  • Valida en tu lado lo crítico: el NIF/CIF llega validado con dígito de control, pero mira totals_consistent, que ya comprueba que base + IVA + recargo − retención dan el total, antes de dar el dato por bueno.

5. De la prueba a producción

Cuando el flujo funcione de punta a punta, mueve la API Key a tu gestor de secretos y monta el webhook. Si automatizas para terceros (por ejemplo una asesoría), la misma API alimenta un flujo sin código.

¿Quieres una clave de prueba? Solicítala aquí y la generamos contigo.