Qué campos fiscales devuelve una API de facturas española (y cuáles le faltan a las genéricas)

Casi todas las APIs de extracción de documentos devuelven lo mismo: emisor, número, fecha y total. Con eso se monta una demo bonita y no se contabiliza nada. En cuanto la factura lleva dos tipos de IVA, una retención de IRPF o recargo de equivalencia, un campo tax_amount con un único número deja de servir, porque no puedes repartirlo.

Este artículo va de eso: qué campos necesita de verdad una factura española para llegar a la contabilidad sin que nadie la abra, y cómo se ven en el JSON. Si lo que buscas es cómo autenticarte y hacer tu primera llamada, eso está en la guía para developers; aquí nos centramos en los datos.

El problema de un solo campo de IVA

Imagina una factura de un proveedor de hostelería: bebidas al 21 %, comida al 10 %, y un par de líneas de producto de primera necesidad al 4 %. El total de IVA es un número, sí, pero el libro de facturas recibidas y el modelo 303 no quieren ese número: quieren la base imponible y la cuota de cada tipo por separado.

Si tu API devuelve solo el agregado, alguien tiene que abrir el PDF y repartirlo a mano. Has automatizado la parte fácil y has dejado intacta la que cuesta tiempo.

El desglose por tipo: tax_breakdown

La respuesta incluye un array con una entrada por cada tipo de IVA presente en el documento:

"tax_breakdown": [
  { "rate": 21, "base": 340.00, "amount": 71.40,
    "surcharge_rate": null, "surcharge_amount": null },
  { "rate": 10, "base": 120.00, "amount": 12.00,
    "surcharge_rate": null, "surcharge_amount": null },
  { "rate": 4,  "base": 25.00,  "amount": 1.00,
    "surcharge_rate": null, "surcharge_amount": null }
]

Cada entrada trae el tipo aplicado (rate), la base sobre la que se aplica (base) y la cuota resultante (amount). Con eso, cada línea del libro sale sola, y las casillas del 303 se rellenan sumando por tipo en lugar de recalculando. Si te interesa el detalle de a qué casilla va cada cosa, lo desarrollamos en la guía de las casillas del modelo 303.

Los tres campos que las APIs internacionales suelen ignorar

Retención de IRPF: withholding_amount

Una factura de un profesional —un abogado, un diseñador, un asesor— lleva retención. El importe a pagar es menor que base más IVA, porque una parte se retiene e ingresa a Hacienda por su cuenta.

Una API que no contemple este campo hace una de dos cosas, y ambas están mal: o da el total sin retención y te descuadra el pago, o se traga la retención dentro de otro importe y pierdes el dato que necesitas para el modelo 111. Aquí viaja en su propio campo, y sobre cómo cuadrarlo escribimos en la retención de IRPF en facturas recibidas.

Con el importe viajan los otros dos datos que pide el 111, porque el modelo se declara con base y retención, no solo con la retención:

• withholding_rate — el tipo aplicado (15 = 15 %). Los habituales son el 15 %, el 7 % de los profesionales que empiezan, el 2 % y el 1 % de módulos, y el 19 % de los alquileres.
• withholding_base — la base sobre la que se practica, cuando la factura la detalla aparte. Suele coincidir con subtotal, pero no siempre: si hay líneas no sujetas o suplidos, la base de la retención es menor.

Los dos llegan solo si están escritos en el documento. Ni el tipo se calcula dividiendo el importe entre la base ni la base se copia del subtotal, y la razón es la de siempre: un número calculado sale bien en las facturas fáciles y mal justo en las que hay que mirar. Si la retención ni siquiera está escrita y la deducimos del descuadre del total, el importe llega igual pero el tipo y la base van a null.

Recargo de equivalencia: surcharge_amount

Un régimen que prácticamente no existe fuera de España y que ninguna API internacional modela. Si tu proveedor te lo repercute y tú lo sumas a la cuota de IVA, tu libro queda mal desde la primera factura.

Va en campo aparte, y también por tipo dentro de tax_breakdown (surcharge_rate y surcharge_amount), porque el recargo se aplica sobre la misma base que su tipo de IVA correspondiente. Lo tratamos en detalle en cómo detectar el recargo de equivalencia.

Validación del NIF: vendor_tax_id_valid

Este no es un campo que el documento traiga: es una comprobación que hacemos sobre lo leído. El NIF, NIE o CIF del emisor se valida contra su carácter de control con el algoritmo oficial, y el resultado viene como booleano:

• true — el carácter de control cuadra.
• false — tiene formato de identificador español pero el control no cuadra. Típicamente un dígito mal leído, o un NIF mal impreso en origen.
• null — no es un identificador español reconocible, por ejemplo un VAT intracomunitario. No lo damos por malo: simplemente no sabemos juzgarlo.

Esa distinción entre false y null importa más de lo que parece. Un false es una alarma que hay que mirar antes de que ese NIF acabe en un modelo 347. Un null en un proveedor alemán es lo normal y no debe generar ruido.

Los campos de control: confianza y cuadre

Dos datos más que no describen la factura, sino la fiabilidad de lo extraído. Son los que permiten decidir qué se revisa a mano y qué pasa de largo:

• confidence — puntuación global de la extracción, de 0 a 1.
• field_confidence — la misma puntuación, pero campo a campo: { "vendor_tax_id": 0.99, "invoice_number": 0.62, ... }. Es la diferencia entre saber que una factura va al 85 % y saber qué campo es el que baja la media. Con ella el umbral se pone por campo —exigente con el NIF y los importes, generoso con la dirección— y a revisión humana va el dato dudoso, no el documento entero. Un campo que no aparece en el mapa es un campo que el documento no traía, no un campo leído con un 0.
• Cuadre de importes — se comprueba que base, IVA, IRPF y recargo den efectivamente el total. Cuando no cuadra, lo sabes sin abrir el PDF. Es la señal que más documentos raros atrapa: albaranes y proformas coladas entre las facturas suelen caer aquí.

Lo que no es fiscal pero decide cuándo y cuánto se paga

Una factura no solo dice cuánto IVA lleva. Dice también qué descuento se aplicó, qué portes se añadieron, cómo y cuándo se paga y a qué pedido responde. Son los campos que convierten el JSON en algo que un ERP puede conciliar solo:

• discount_amount y discount_percent — el descuento del documento, siempre en positivo aunque la factura lo escriba restando. El porcentaje solo viene si está escrito: no lo calculamos nosotros.
• other_charges_amount y other_charges_concept — portes, gastos de gestión, recargo financiero o por demora, con el nombre que les da la factura. Ojo: esto no es el recargo de equivalencia, que es un impuesto y viaja en surcharge_amount.
• payment_method, payment_iban y payment_terms — la forma de pago tal y como la nombra el documento, el IBAN de cobro sin espacios y las condiciones literales («30 días fecha factura»). Son los tres datos que hacen falta para conciliar el banco y para saber cuándo vence una factura que no trae fecha de vencimiento.
• purchase_order — el pedido, albarán o contrato del cliente al que responde la factura. Es con lo que se casa contra lo que se encargó, y hasta ahora había que leerlo a mano en el PDF.
• rectifies_invoice_number — en una rectificativa o un abono, el número de la factura que corrige. Sin él sabes que el documento es un abono, pero no de qué.

Ni el descuento ni los otros recargos entran en la comprobación de cuadre: el descuento ya está aplicado en la base imponible, y los portes pueden ir dentro o fuera de ella según cómo los facture cada proveedor. Meterlos en la fórmula daría por descuadradas facturas correctas.

Qué clase de documento es: document_type

Antes de extraer importes, el motor decide qué tiene delante y lo declara: factura, factura simplificada, rectificativa, proforma, albarán, presupuesto, recibo u otro. Es el campo que evita el error más caro y más silencioso de todos, que es contabilizar como factura algo que no lo es y deducirse un IVA inexistente.

La respuesta completa, de un vistazo

{
  "id": 4821,
  "status": "completed",
  "document_type": "factura",

  "vendor_name": "Suministros Ejemplo S.L.",
  "vendor_tax_id": "B12345674",
  "vendor_tax_id_valid": true,
  "customer_name": "Tu Empresa S.L.",
  "customer_tax_id": "B87654321",

  "invoice_number": "F2026-1043",
  "invoice_date": "2026-09-15",
  "due_date": "2026-10-15",

  "purchase_order": "PED-4412",
  "rectifies_invoice_number": null,

  "subtotal": 485.00,
  "tax_amount": 84.40,
  "withholding_amount": null,
  "withholding_rate": null,
  "withholding_base": null,
  "surcharge_amount": null,
  "discount_amount": 15.00,
  "discount_percent": null,
  "other_charges_amount": null,
  "other_charges_concept": null,
  "total": 569.40,
  "currency": "EUR",

  "payment_method": "Transferencia",
  "payment_iban": "ES9121000418450200051332",
  "payment_terms": "30 días fecha factura",

  "tax_breakdown": [ ... ],
  "line_items": [ ... ],

  "confidence": 0.97,
  "field_confidence": {
    "vendor_name": 0.99, "vendor_tax_id": 0.99,
    "invoice_number": 0.97, "total": 0.99,
    "payment_iban": 0.82
  }
}

A eso se añade raw_fields si tu cuenta tiene campos a medida: lo que le hayas pedido, cada uno con su valor y su confianza, sin tocar la estructura de los campos estándar.

Cómo llega esto a tu sistema

Hay tres formas, y la que encaje depende de tu volumen más que de tu stack:

• Llamada directa. Envías el documento y recibes el JSON. Simple y suficiente cuando procesas bajo demanda.
• Webhooks. Cada factura procesada avisa a tu sistema en cuanto está lista, con los datos dentro. Es lo que quieres si el volumen es continuo y no te apetece hacer polling; lo explicamos en integrar facturas con tu ERP en tiempo real.
• Sin escribir código. Un orquestador tipo Make, Zapier o n8n recoge la salida y la escribe donde toque.

La pregunta que conviene hacerle a cualquier proveedor

Cuando estés comparando APIs de extracción, hay una prueba que separa muy rápido a las que sirven en España de las que no. Mándales una factura real con dos tipos de IVA y una retención de IRPF, y mira la respuesta:

• ¿Viene la base y la cuota separadas por cada tipo, o un único importe de IVA?
• ¿Existe un campo propio para la retención, o el total no cuadra con lo que vas a pagar?
• ¿Hay algo para el recargo de equivalencia?
• ¿Te dicen si el NIF es válido, o te devuelven la cadena tal cual la leyeron?

Si las cuatro respuestas no son buenas, el trabajo que creías haber automatizado sigue sobre la mesa de alguien. Lo comparamos criterio a criterio en la alternativa española a las plataformas internacionales, con una prueba de cinco facturas que puedes hacer con cualquier herramienta.

Puedes ver los endpoints y la autenticación en la página de la API, o pedirnos una demo y la probamos con tus propias facturas.