API, seguridad y errores
Errores y respuestas de la AEAT en Verifactu
Cómo interpretar Correcto, AceptadoConErrores e Incorrecto, separar transporte y validación y decidir cuándo subsanar o revisar un registro.
Contenido de la guía
Respuesta rápida
La respuesta de un envío Verifactu tiene que leerse por registro, no solo por la respuesta HTTP. En la descripción técnica de la AEAT, Correcto significa que el registro es totalmente correcto y se registra; AceptadoConErrores significa que tiene errores que no provocan su rechazo y se registra; Incorrecto significa que los errores provocan rechazo y no se registra. Un timeout, un fallo TLS o un HTTP 500 no es ninguno de esos tres estados: es una entrega cuyo resultado todavía hay que reconciliar.
La descripción oficial del servicio web contiene los nombres exactos y la página de validaciones y errores es la fuente para códigos concretos.
Cuatro capas de resultado
| Capa | Ejemplo | Acción inicial |
|---|---|---|
| Transporte | No hay respuesta, DNS o conexión TLS fallida | No generar otra factura automáticamente; guardar la solicitud y reconciliar. |
| HTTP | Respuesta 4xx/5xx del servicio | Registrar cuerpo y cabeceras permitidas; seguir el procedimiento de reintento de la integración. |
| Respuesta del servicio | Correcto, AceptadoConErrores, Incorrecto | Persistir el estado y el código de cada registro. |
| Duplicado | Alta rechazada por existir previamente | Leer EstadoRegistroDuplicado antes de decidir si es un reintento seguro. |
Mezclar estas capas es una fuente habitual de facturas duplicadas. “No he recibido 200” no demuestra que la AEAT no haya recibido el registro; “he recibido 200” tampoco prueba que cada registro del lote sea correcto.
Qué significa cada estado
Correcto
El registro pasa las validaciones aplicables y queda registrado. Conserva la respuesta con el identificador, estado y cualquier dato de consulta que devuelva el servicio. El estado describe el registro remitido; no convierte por sí solo el PDF en una factura “validada” por la AEAT.
AceptadoConErrores
El registro se registra pese a contener errores que no provocan rechazo. No borres el original ni lo reemplaces silenciosamente. Guarda el código y el mensaje, evalúa si procede generar una subsanación y deja visible la incidencia para la persona responsable.
Incorrecto
El registro es rechazado y no se registra. La corrección no consiste en editar el payload que ya se intentó emitir y perder el rastro: hay que identificar el motivo, corregir el origen y seguir el procedimiento que corresponda. Si la factura ya fue materialmente expedida, consulta también la vía de anulación o rectificación.
Duplicados y reintentos
Un webhook puede llegar dos veces y un cliente HTTP puede reintentar después de un timeout. Si la segunda petición representa el mismo registro, la respuesta puede indicar que se trata de un duplicado y aportar el estado del registro que ya estaba almacenado. La especificación técnica distingue estados como Correcta, AceptadaConErrores o Anulada para ese registro previo.
La estrategia segura es:
- asignar una clave estable al evento externo;
- guardar la solicitud antes de enviarla;
- si se pierde la respuesta, consultar o repetir de forma controlada;
- tratar el duplicado como reconciliación, no como una nueva numeración;
- escalar si el estado previo no coincide con lo que esperaba el sistema.
La guía de API existente desarrolla idempotencia; aquí la cuestión específica es interpretar la respuesta AEAT.
Un ejemplo de cola operativa
evento pedido pagado | registro guardado localmente | envío AEAT –– timeout ––> estado “pendiente de reconciliar” | consulta/reintento controlado | Correcto | AceptadoConErrores | Incorrecto | duplicado con estado previo
No uses el estado “pendiente” como si fuera una respuesta de la AEAT. Es un estado interno de la cola que indica que falta evidencia.
Qué debe ver una persona usuaria
Un panel útil muestra, como mínimo:
- número y serie de la factura;
- fecha y entorno;
- estado del registro;
- código y texto de error, si existe;
- momento del último intento;
- acción siguiente: revisar, subsanar, anular o esperar reconciliación;
- relación con pedido, cobro o devolución de la plataforma.
No escondas un AceptadoConErrores detrás de un “enviado” genérico. Tampoco muestres “rechazada” cuando solo falló la red y aún no sabes qué ocurrió.
Qué no automatizar sin revisión
- convertir cada error de transporte en una factura nueva;
- modificar el alta original después de haberla generado;
- tratar cualquier reembolso como anulación;
- descartar códigos porque el lote completo devolvió una respuesta HTTP válida;
- publicar un “aceptado” como garantía de la corrección fiscal global.
La documentación técnica puede cambiar con nuevas versiones de esquemas y validaciones. Fija en tu registro la versión usada y revisa el índice de información técnica de la AEAT.
Estado de VeriFactu Fácil
VeriFactu Fácil está en prelanzamiento. La arquitectura pública prevista contempla estados por registro y reintentos controlados, pero todavía no hay un panel público ni un SLA que este artículo pueda presentar como disponible.
Siguiente paso
Cuéntanos qué sistema necesitas conectar
El servicio está en prelanzamiento. Revisamos el canal, el volumen y los datos fiscales antes de abrir una integración.
Hablar sobre tu integración →