API Verifactu: eventos, facturas y webhooks

Respuesta rápida

Una API Verifactu no debería limitarse a “enviar una factura”. La integración necesita convertir un evento de negocio en una factura, generar el registro fiscal asociado, conservar el encadenamiento y devolver un estado que el sistema de origen pueda reconciliar.

La web de VeriFactu Fácil está en prelanzamiento. Esta página describe el contrato previsto; las altas se abrirán próximamente y el contacto comercial ya está disponible.

El evento de negocio es el punto de partida

Cada canal tiene un momento distinto que confirma la operación:

Sistema	Evento habitual	Riesgo que hay que controlar
WooCommerce	Pedido pagado o completado	Cambios de estado repetidos
Shopify	Pedido pagado	Reintentos y reembolsos parciales
PrestaShop	Estado de pedido configurado	Facturar antes del cobro
Stripe	Checkout, PaymentIntent o Billing	Identificadores diferentes entre cobro y devolución
SaaS o ERP	Evento propio del dominio	Contratos y tipos fiscales incompletos

La integración debe declarar qué evento crea la factura, cuál la rectifica y qué identificador permanece estable durante todo el ciclo.

Idempotencia: una venta, una factura

Los proveedores reintentan webhooks. Por eso el backend necesita una clave idempotente formada, como mínimo, por el canal y el identificador externo.

Si llega dos veces el mismo evento, la API debe devolver la factura ya creada. No debe consumir otra numeración ni generar un segundo registro.

Los impuestos deben llegar desglosados

Un total de 121 € no revela si la operación contiene una base de 100 € al 21 %, varios tipos de IVA o conceptos exentos. Para crear una factura y una rectificativa exactas, el contrato debe transportar los buckets fiscales:

• base imponible;
• tipo impositivo;
• cuota;
• clasificación o régimen cuando corresponda;
• importe rectificado por cada bucket en una devolución parcial.

Prorratear a posteriori un reembolso multi-tipo puede producir céntimos incorrectos y perder la relación con el documento original.

Flujo de estados recomendado

1. el sistema de origen firma o autentica la solicitud;
2. la API valida tenant, entorno y límites antes de numerar;
3. crea la factura de forma idempotente;
4. genera huella, QR y XML del registro;
5. remite el registro a la AEAT;
6. conserva la respuesta por registro;
7. publica un webhook de estado para el sistema de origen.

Un estado “recibido” no sustituye una revisión fiscal completa. Debe conservarse la respuesta exacta y distinguir aceptado, aceptado con incidencias, rechazado y pendiente de revisión.

API directa o plugin

El plugin reduce trabajo cuando la plataforma ya tiene un modelo de pedidos conocido. La API directa encaja mejor si el sistema de origen es un SaaS, un ERP, un marketplace o un flujo automatizado propio.

En ambos casos, la capa fiscal puede ser la misma; cambia el adaptador que traduce pedidos, cobros y devoluciones.

Ver el flujo técnico previsto →