API VeriFactu: emite desde tu propio backend

Qué resuelve la API

Tu backend ya sabe cuándo hay una venta, cuánto vale y quién es el cliente. Lo que no debería tener que saber es cómo se construye un registro de facturación, cómo se encadena o qué clave de régimen corresponde a un envío a Canarias. Tú envías el hecho de negocio; Factulit toma la decisión fiscal y responde de ella:

• Genera la factura completa (F1) o simplificada (F2), con la serie y el número que corresponden a tu conexión.
• Construye el registro VeriFactu de alta, anulación o rectificativa, lo encadena con la huella del registro anterior y lo remite a la Agencia Tributaria.
• Decide en el servidor, no en tu código. Si un pedido se cancela, se reembolsa o se modifica, es Factulit quien decide si eso es una anulación, una rectificativa o nada. Tu integración no replica esa lógica ni la mantiene cuando cambie la normativa.
• Bloquea lo que la norma no permite. Una factura simplificada en una venta a distancia intracomunitaria no se emite mal: se envía a revisión.
• Incluye el QR de verificación en la factura desde su expedición, no solo cuando la AEAT la acepta.

Autenticación

La API pública de Factulit vive en https://api.factulit.es/api/v1 y se autentica con una cabecera X-API-KEY. No hay OAuth, ni tokens de corta vida, ni flujos de redirección: es una integración server-side y la clave se guarda en tu servidor.

X-API-KEY: factulit_test_key
Accept: application/json
Content-Type: application/json

La documentación técnica completa del contrato v1 —guías por recurso, referencia de endpoints y ciclo fiscal— está publicada en developers.factulit.es, en español e inglés.

Los recursos del contrato v1 son cuatro:

La clave nunca debe viajar a un navegador, a una app móvil ni a un repositorio público. Si sospechas que se ha expuesto, se rota desde el recurso key sin cortar el servicio.

Un ejemplo, a título ilustrativo

Un envío de pedido con el payload mínimo del contrato v1. Es un ejemplo ilustrativo con datos ficticios: la forma exacta de cada campo, los opcionales y las validaciones están en la documentación pública de la API, que es la referencia del contrato.

POST /api/v1/order

{
  "id_external": "order-1001",
  "reference": "1001",
  "order_date": "2026-07-07 10:30:00",
  "total": 121,
  "total_tax": 21,
  "currency": "EUR",
  "status": "paid",
  "id_order_status": "paid",
  "source_platform": "custom",
  "fiscal_event": "invoice_candidate",
  "invoice_action": "create_invoice",
  "client": {
    "id_external": "customer-1001",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.test",
    "country": "ES"
  },
  "breakdown": [
    {
      "id_external_product": "sku-001",
      "name": "Producto",
      "quantity": 1,
      "base_amount": 100,
      "tax_rate": 21,
      "tax_amount": 21
    }
  ]
}

Las respuestas usan un envelope JSON consistente: success más el recurso resultante en data y, en caso de error, un objeto errors con el detalle por campo. Los códigos son los que esperarías: 201 al aceptar o crear, 200 cuando el recurso ya existía, 401 y 403 para problemas de credencial o de contexto de negocio, 422 para fallos de validación o de cuota de facturas y 503 como respuesta temporal de protección del servicio. Trata los 422 como errores de negocio: hay que cambiar el payload o el plan antes de reintentar, no reintentar en bucle.

Idempotencia y facturas inmutables

La emisión es atómica e idempotente por identificador externo: eliges un identificador estable en tu sistema y lo envías con la operación.

• La primera petición emite y responde 201.
• La misma petición con el mismo identificador y el mismo payload normalizado no emite dos veces: devuelve el resultado existente con 200 y replayed: true.
• El mismo identificador con un payload distinto responde 409 con idempotency_conflict. No se emite nada.

Y la consecuencia lógica de todo esto: una factura emitida es inmutable. No se puede actualizar, ni corregir con un PUT, ni reescribir. Si hay que cambiar algo, el camino es el que marca la normativa: una anulación o una factura rectificativa, cada una con su propio registro. Un reintento por timeout de tu lado nunca duplicará una factura.

Qué pasa cuando la AEAT devuelve un error

Que te llega traducido. La respuesta de la Agencia Tributaria es un código numérico y un texto técnico; Factulit lo convierte en causa, acción concreta, de quién es el problema y si es subsanable, y lo clasifica por rango:

Dos matices que ahorran horas de soporte y que casi nadie publica: los códigos 2004 y 2009 están expresamente exceptuados de la obligación de subsanación, así que no hay nada que corregir; y un 3000 (duplicado) no deja la factura sin registrar, porque el registro original sigue vigente. Ante un 3000, Factulit reconcilia el estado real en lugar de reintentar el envío en bucle. Ver el catálogo completo de códigos en errores de la AEAT en VeriFactu.

Ante una caída de la Agencia Tributaria, tu facturación no se detiene: los registros se encolan, se reenvían con espera progresiva y el reenvío se marca como incidencia, tal y como exige la norma.

Una serie propia por conexión

Cada conexión de API recibe su serie de facturación reservada, y sucesivas si abres más conexiones. No la compartes con tu tienda de WooCommerce ni con el TPV de la tienda física: cada canal numera por su cuenta y ninguno pisa al otro.

Esto resuelve la convivencia: la cadena de huellas es por sistema informático de facturación, no por NIF, así que la API puede emitir el canal online mientras otro programa sigue facturando bajo el mismo NIF, siempre que las series sean distintas. Y el cambio de serie no renombra ni renumera nada: crea una serie nueva con una frontera inequívoca y deja evidencia inmutable de quién la cambió y cuándo.

Para agencias y desarrolladores con varios clientes

Si llevas la facturación de varios negocios, dos cosas importan más que el resto.

La primera es la separación: cada cliente es una conexión con su propia clave, su propia serie y su propia cadena de registros. No hay mezcla posible entre cadenas de clientes distintos.

La segunda es la representación ante la Agencia Tributaria. Factulit Digital, S.L. tiene suscrito un acuerdo de colaboración social con la Agencia Estatal de Administración Tributaria para la remisión de registros de facturación en representación de terceros. Es decir, tus clientes tienen una vía de remisión que no depende de que cada uno instale y mantenga su propio certificado. El modo de representación se revisa cliente a cliente durante el alta.

Empieza a integrar

Solicita el alta y te damos de alta la conexión de API con su clave y su serie, junto con la documentación pública del contrato v1. El plan Free incluye 50 facturas al mes a 0 euros, sin IVA y sin tarjeta, suficiente para montar la integración completa antes de mover volumen real.

Enlaces relacionados: preguntas frecuentes sobre VeriFactu · VeriFactu para tiendas online · plataformas compatibles · precios y planes · declaración responsable

Los ejemplos de esta página son ilustrativos y usan datos ficticios. La referencia del contrato es la documentación pública de la API v1. Esta página no constituye asesoramiento fiscal ni jurídico individual.