La API de la AEAT: qué publica realmente
No hay REST. Hay un servicio SOAP autenticado con certificado en el propio TLS, tres hosts que no son intercambiables y una respuesta con más matices de los que parece.
¿Cómo es la API de la AEAT para VeriFactu?
La AEAT no publica una API REST: publica un servicio web SOAP que se autentica con un certificado electrónico en el propio handshake TLS, más los esquemas XSD y las especificaciones de generación de la huella.
La remisión vive en www1.agenciatributaria.gob.es (prewww1.aeat.es en pruebas), los certificados de sello de entidad usan www10 y el validador del QR vive en www2. Son servicios distintos y no son intercambiables.
Fuente: Orden HAC/1177/2024, de 17 de octubre · Agencia Tributaria — Sistemas informáticos de facturación y VERI*FACTU
Conviene decirlo claro porque mucha gente lo busca esperando otra cosa: la AEAT no publica una API REST de VeriFactu. Lo que publica es un servicio web SOAP, autenticado con certificado electrónico en el propio TLS, más los esquemas XSD y las especificaciones de huella.
<!-- La AEAT no expone REST. Es SOAP con mTLS. --> POST /wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP HTTP/1.1 Host: www1.agenciatributaria.gob.es Content-Type: text/xml; charset=utf-8 <!-- El certificado va en el handshake TLS, no en una cabecera --> <soapenv:Envelope> <soapenv:Body> <sfLR:RegFactuSistemaFacturacion> <sfLR:Cabecera>...</sfLR:Cabecera> <sfLR:RegistroFactura>...</sfLR:RegistroFactura> </sfLR:RegFactuSistemaFacturacion> </soapenv:Body> </soapenv:Envelope>
| Servicio | Dónde vive |
|---|---|
| Remisión de registros (SOAP) | www1.agenciatributaria.gob.es · pruebas prewww1.aeat.es |
| Remisión con certificado de sello | www10.agenciatributaria.gob.es · pruebas prewww10.aeat.es |
| Validador del QR | www2.agenciatributaria.gob.es · pruebas prewww2.aeat.es |
<RespuestaRegFactuSistemaFacturacion> <EstadoEnvio>Correcto</EstadoEnvio> <!-- Correcto | AceptadoConErrores | Incorrecto --> <CSV>A1B2C3D4E5F6</CSV> <!-- Control de flujo del artículo 16: --> <!-- segundos que hay que esperar al siguiente envío --> <TiempoEsperaEnvio>60</TiempoEsperaEnvio> <RespuestaLinea> <EstadoRegistro>Incorrecto</EstadoRegistro> <CodigoErrorRegistro>4104</CodigoErrorRegistro> <DescripcionErrorRegistro>...</DescripcionErrorRegistro> </RespuestaLinea> </RespuestaRegFactuSistemaFacturacion>
El envío puede ir bien y el registro mal
EstadoEnvio y EstadoRegistro son cosas distintas. Un envío «Correcto» puede contener líneas rechazadas.
«AceptadoConErrores» no bloquea, y por eso es peligroso
Suele significar que la AEAT recalculó la huella desde tu XML y no le cuadró. Nadie te avisa: se acumula factura a factura hasta que alguien mira.
TiempoEsperaEnvio es una orden, no una sugerencia
Ignorarlo es quedarse sin servicio en hora punta. Hay que persistirlo y respetarlo entre procesos, no solo dentro del que hizo la llamada.
Y un rechazo de contenido no se reintenta
Un NIF que no cuadra con el censo fallará las veces que lo mandes. Hay que distinguir transitorio de definitivo o acabas con una cola que gira en vacío.
El SOAP es la parte fácil. Se resuelve en una tarde.
La huella tiene un formato exacto y es irreversible
Ocho campos, un orden, tres formatos que clavar. Si empiezas con el formato equivocado, el histórico queda con ese defecto para siempre. Cómo se calcula.
La concurrencia bifurca la cadena, y la AEAT lo acepta
Dos facturas simultáneas del mismo emisor pueden encadenarse al mismo registro anterior. Nadie te avisa, y no se arregla después.
El catálogo de rechazos se aprende chocando
El 1110, el 1177, el 4104, el 4105. Cada uno cuesta días la primera vez porque el mensaje de la AEAT no dice qué campo falla. El diccionario.
Y los certificados hay que custodiarlos
Si remites por tus clientes, guardas ficheros que ante la AEAT sirven para casi todo. Qué implica.
¿La AEAT tiene una API REST para VeriFactu?
No. Publica un servicio web SOAP, autenticado con certificado electrónico en el propio handshake TLS, junto con los esquemas XSD y las especificaciones técnicas de generación de la huella.
¿Se puede integrar directamente contra la AEAT sin intermediarios?
Sí, perfectamente. Es lo que hemos hecho nosotros. Lo que consume el tiempo no es el SOAP, que se resuelve en una tarde, sino el formato exacto de la huella, la serialización de la cadena, el control de flujo y el catálogo de rechazos.
¿Qué es TiempoEsperaEnvio?
Los segundos que la AEAT indica que debes esperar antes del siguiente envío, como parte del control de flujo del artículo 16. Hay que persistirlo y respetarlo entre procesos: ignorarlo deja sin servicio justo en hora punta.
¿Qué diferencia hay entre EstadoEnvio y EstadoRegistro?
EstadoEnvio se refiere al mensaje completo y EstadoRegistro a cada línea. Un envío «Correcto» puede contener registros rechazados, así que hay que revisar los dos niveles.
¿Hay algún entorno de pruebas de la AEAT?
Sí, la preproducción: prewww1.aeat.es para la remisión y prewww2.aeat.es para el validador del QR. Nuestro sandbox pega contra ese entorno, no contra un simulador propio.
Última revisión normativa: Especificaciones de huella AEAT v0.1.2 Revisado por el equipo técnico de verifactu.co