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

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",
  "tax_base": 1000.00,
  "tax_amount": 210.00,
  "irpf_amount": 150.00,
  "total": 1060.00,
  "confidence": 0.98,
  "line_items": [
    { "description": "Material de oficina", "quantity": 10, "unit_price": 100.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: cada campo trae su confidence. Define un umbral por debajo del cual envías la factura a revisión humana en lugar de contabilizarla directamente.
• Prueba sin gastar cuota: durante el desarrollo usa POST /api/v1/invoices/scan-test, que no consume cuota.
• 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 comprueba que tax_base + tax_amount cuadra con total antes de dar el dato por bueno.

5. De la prueba a producción

Cuando el flujo funcione con scan-test, cambia al endpoint real, 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.