Documentación

Errores y reintentos

La emisión es síncrona, pero la remisión a la AEAT es asíncrona. Esta página describe el ciclo de vida de un registro, cómo enterarte del resultado AEAT (consulta o webhook) y qué pasa cuando algo falla — a tu lado o al de la Agencia Tributaria.

Estados de un registro

Estado	Significado
`PENDIENTE`	Registrado en FactuBridge, huella y QR emitidos, en cola de remisión.
`ENVIADO`	Remitido a la AEAT, esperando su respuesta.
`ACEPTADO`	La AEAT lo ha aceptado (resultado `Correcto` o `AceptadoConErrores`).
`RECHAZADO`	La AEAT lo ha rechazado (`Incorrecto`). Requiere corrección: ver subsanaciones.
`ERROR`	Error técnico persistente en la remisión. Nuestro equipo lo ve en monitorización antes que tú; si te afecta, te contactamos.

«Aceptado con errores» no es un rechazo. La factura está registrada, pero la AEAT señala algún dato mejorable (típicamente el destinatario). Conviene subsanarlo, sin urgencia bloqueante. Puedes reducirlos a casi cero con lavalidación del destinatario.

Consultar el estado

GET/v1/status

GET /v1/status?serie=A&numero=2026-0001
Authorization: Bearer $FACTUBRIDGE_API_KEY

# → {
#     "uuid": "9b2e7c1a-...",
#     "serie": "A",
#     "numero": "2026-0001",
#     "tipo": "A",
#     "estado": "ACEPTADO",
#     "huella": "3AD5CA54A0DE383B...",
#     ...
#   }

Y para listados (conciliación, panel de control en tu ERP):

GET/v1/registros

GET /v1/registros
Authorization: Bearer $FACTUBRIDGE_API_KEY

Webhooks: el resultado te busca a ti

En lugar de sondear /v1/status, registra un webhook y recibirás un POST en tu endpoint con el resultado AEAT de cada registro (Correcto, AceptadoConErrores oIncorrecto) en cuanto se procese.

POST/v1/client-webhooks

POST /v1/client-webhooks
Authorization: Bearer $FACTUBRIDGE_API_KEY

{ "url": "https://erp.ejemplo.com/factubridge/callback" }

# → { "id": "...", "url": "...", "activo": true,
#     "secret": "whsec_..." }   ← visible solo en esta respuesta

Cada entrega va firmada con HMAC usando el secret devuelto en el alta (visible solo esa vez): verifica la firma antes de procesar.
Gestión completa: GET/PUT/DELETE /v1/client-webhooks/{id}, incluida la rotación del secret.
Responde 2xx rápido y procesa en segundo plano; las entregas fallidas se reintentan.

¿Y si la AEAT se cae?

No es tu problema, y tampoco urgente para el nuestro: el reglamento hace responsable al sistema de remitir, no de que la AEAT esté disponible. FactuBridge usa un patrón outbox con garantías estrictas:

El registro y su evento de envío se crean en la misma transacción: no existen registros «huérfanos» sin remisión programada.
Los envíos son FIFO estrictos por obligado: la cadena de huellas nunca se remite desordenada.
Ante caída o error de la AEAT, los reintentos son automáticos, con el control de flujo (tiempo de espera) que la propia AEAT dicta en cada respuesta.
Tu SIF sigue facturando con normalidad durante todo el incidente: la respuesta síncrona (huella, QR) no depende de la AEAT.

Errores de la API

Las validaciones de la API bloquean los fallos más habituales del registro de facturación antes de crearlo: ahorran el rechazo de la AEAT y la subsanación posterior, aunque ningún control previo cubre todos los casos. Lo que la API no valida deliberadamente son cuestiones normativas o fiscales que la propia AEAT tolera —numeración no secuencial, fecha de expedición anterior a la creación del registro…—: imponer controles más estrictos que la administración bloquearía facturas que Hacienda admite a sabiendas.

Código	Cuándo	Qué hacer
`400`	Validación: importes que no cuadran (±10 €), destinatario obligatorio ausente, tipo de factura incoherente, NIF no censado con `validar_destinatario=true`… También `Idempotency-Key` con formato inválido (`invalid_idempotency_key`).	El campo `detail` explica el motivo exacto. Corrige y reenvía.
`401`	API key ausente o revocada.	Revisa la cabecera `Authorization`.
`409`	Factura duplicada (misma serie, número y fecha).	La respuesta incluye el registro existente. Si no enviaste `Idempotency-Key`, es seguro tratarla como éxito (reintento). Si la enviaste, es una colisión real de numeración: dos facturas distintas con la misma serie y número — merece alerta, no tratarla como éxito.
`422`	La `Idempotency-Key` ya se usó con un cuerpo distinto (`idempotency_key_reused_with_different_payload`).	No se ha creado ni modificado nada. Revisa cómo derivas la clave: cada intento lógico debe llevar clave propia y los reintentos deben reenviar el cuerpo idéntico.
`5xx`	Error interno.	Reintenta con backoff. El diseño de duplicados hace el reintento idempotente.

Reintentos seguros. /create es idempotente siempre por la clave natural de la factura (el 409 devuelve el registro existente), y /create, /modify y/cancel admiten además la cabecera opcionalIdempotency-Key, que convierte el reintento en un200 con el estado actual del registro. Por qué no caduca y cómo elegir la clave:guía de idempotencia.