Errores comunes al conectar Veri*Factu con la AEAT y cómo solucionarlos

El reto técnico de integrar la API de la AEAT

Cualquier programador o empresa de software que se haya enfrentado a la integración de servicios web de la Administración Pública conoce la regla de oro: asume que el sistema fallará en el peor momento posible.

Al desarrollar un sistema informático de facturación (SIF) compatible con Veri*Factu, las conexiones con la Agencia Tributaria no son una excepción. Los tiempos de espera agotados (timeouts), los mantenimientos de red no programados y los errores HTTP 500 o respuestas SOAP incompletas son frecuentes, tanto en el entorno de preproducción como en producción.

El peligro de las integraciones síncronas

El error de diseño más común es utilizar una arquitectura síncrona.

Imagina que tu usuario hace clic en "Emitir Factura". Tu servidor (backend) genera el XML, aplica el certificado mTLS y abre una conexión HTTPS con www1.agenciatributaria.gob.es. Si el servidor de Hacienda tarda 30 segundos en responder, el navegador de tu cliente se quedará bloqueado y posiblemente mostrará un error. Si el usuario, frustrado, vuelve a pulsar el botón, corres el riesgo de duplicar la factura o romper el encadenamiento de huellas SHA-256.

La solución: Arquitectura Asíncrona basada en Jobs (Colas)

Para construir un software Veri*Factu robusto, la comunicación con la AEAT debe desacoplarse de la interfaz de usuario. En Simple*Factu, resolvemos esto utilizando un sistema de trabajos en segundo plano (Background Workers):

1. Idempotencia y respuesta rápida: Cuando el usuario emite la factura, nuestro sistema calcula la huella digital y guarda el registro localmente. Devolvemos un código de éxito al usuario inmediatamente (HTTP 202 Accepted).
2. Cola de tareas (Jobs): La factura entra en una cola en estado PENDING.
3. Workers en segundo plano: Un proceso independiente toma la tarea y se encarga de enviarla a la API de la AEAT.
4. Estrategia de Backoff Exponencial: Si la conexión falla (ej. error 503 Service Unavailable), el worker no satura la red. Reintenta a los 2 segundos, luego a los 4, 8, 16... garantizando que el mensaje se entrega cuando el servicio se restablece.

Beneficios de delegar la integración

Cumplir con la normativa técnica del RD 1007/2023 va más allá de validar un XML contra un archivo XSD. Implica construir infraestructura resiliente capaz de gestionar certificados, gestionar series de facturación y recuperarse de fallos externos sin afectar a la experiencia de tus usuarios finales.