API Verifactu: el servicio web de la AEAT, explicado
Todo el mundo lo llama «la API de Verifactu». La AEAT no publica ninguna API en el sentido que le damos hoy a esa palabra: publica un servicio web SOAP, con certificado electrónico obligatorio y sin nada parecido a una clave de acceso. Esto es lo que hay, con las cifras de la documentación oficial.
Para quién es esta página
Para quien va a integrar: desarrolladores, ERPs a medida, plataformas que facturan por cuenta de terceros. Si lo que quieres es cumplir sin programar nada, no necesitas nada de esto: tu programa de facturación ya lo hace por dentro.
Lo primero: no es una API REST
Si esperas un extremo con JSON, una clave en una cabecera y un POST /facturas, ajusta expectativas antes de presupuestar la integración:
- El protocolo es SOAP sobre HTTPS, con los mensajes definidos en un WSDL y los datos en XML validado contra esquemas XSD.
- No hay claves de API ni OAuth. La autenticación es mutua TLS con certificado electrónico cualificado reconocido.
- Los errores de formato XML no vuelven como un código de estado HTTP: vuelven como un
SoapFault. - No hay webhooks. Si quieres saber qué registró la AEAT, preguntas tú con el servicio de consulta.
Nada de esto es un defecto: es la misma familia de servicios que la AEAT lleva usando años para el SII, y buena parte del ecosistema de facturación española ya sabe hablarla.
Los dos sistemas, y no comparten nada
Hay dos vías de remisión y, aunque el esquema XSD es común, son sistemas distintos dentro de la AEAT que no comparten los registros entre sí. Es la trampa que más caro sale descubrir tarde:
| Vía | Cuándo se usa | Servicio de consulta |
|---|---|---|
| Remisión voluntaria «VERI*FACTU» | El sistema envía cada registro conforme lo crea | Sí, disponible |
| Remisión ante requerimiento | Un sistema «no verificable» entrega sus registros porque la AEAT se los pide | No |
Mismo formato de mensaje, direcciones distintas. Lo que envías por una vía no aparece consultando por la otra.
Qué necesitas para empezar
La remisión puede hacerla el propio obligado tributario, un apoderado suyo para este trámite o un colaborador social, y en los tres casos hace falta un certificado electrónico cualificado reconocido. Todos los NIF que viajan en el mensaje se validan contra la base de datos centralizada de la AEAT, así que un NIF mal formado o inexistente tumba el registro.
Si tu caso es el habitual de una plataforma en la nube —hay un obligado, que tiene un asesor fiscal, que usa tu plataforma, que envía con su propio certificado—, el esquema contempla un campo Representante en la cabecera para dejar constancia de la relación obligado-asesor. Sin él solo queda registrada la relación obligado-plataforma, que no es la real.
WSDL y esquemas
La definición de los servicios de remisión voluntaria y ante requerimiento está en un único WSDL:
- Producción, bajo
www2.agenciatributaria.gob.es, en la ruta/static_files/common/internet/dep/aplicaciones/es/aeat/tikeV1.0/cont/ws/, archivoSistemaFacturacion.wsdl. - Pruebas: el mismo camino y el mismo archivo, bajo
prewww2.aeat.es.
Los esquemas van aparte y son tres: SuministroInformacion.xsd con los tipos comunes, SuministroLR.xsd con las operaciones de alta y anulación, y ConsultaLR.xsd para el servicio de consulta. Un mismo mensaje puede llevar registros de alta y de anulación mezclados: no hacen falta dos envíos.
Los tres límites que condicionan el diseño
Estas cifras no son recomendaciones. Son las que hay, y determinan cómo tiene que estar montada la cola de envíos:
| Límite | Valor | Consecuencia |
|---|---|---|
| Registros por envío | 1.000 | Hay que trocear los lotes grandes |
| Tiempo de espera entre envíos | 60 s | Valor inicial; la AEAT lo actualiza en cada respuesta y hay que respetar el nuevo |
| Registros por respuesta de consulta | 10.000 | Si hay más, se pagina con una nueva llamada |
El control de flujo lo impone el artículo 16.2 de la Orden HAC/1177/2024, no es una política del servidor que pueda cambiar sin previo aviso.
El mecanismo funciona así: envías, la AEAT te devuelve un valor actualizado de TiempoEsperaEnvio, y para el siguiente envío esperas ese número de segundos o a tener acumulados 1.000 registros —lo que ocurra primero—. Un integrador que ignore ese parámetro y envíe factura a factura acabará estrangulado por su propio diseño.
Cómo responde la AEAT
Hay dos niveles de respuesta y conviene no confundirlos. El del envío completo:
Correcto— todos los registros aceptados.ParcialmenteCorrecto— alguno tiene errores o ha sido rechazado.Incorrecto— rechazo completo.
Y el de cada registro, dentro del anterior:
Correcto— se registra en el sistema.AceptadoConErrores— tiene errores que no provocan el rechazo. Se registra igualmente.Incorrecto— no se registra; hay que subsanar y volver a remitir.
AceptadoConErrores. Un integrador que lo trate como fallo reenviará un registro que ya está dentro y se llevará un rechazo por duplicado; uno que lo trate como éxito silencioso nunca corregirá el dato defectuoso. Hay que registrarlo y avisar.Cuando el rechazo es por duplicado, la respuesta incluye además el estado del registro que ya estaba almacenado —Correcta, AceptadaConErrores o Anulada—, que es justo lo que hace falta para decidir si reintentar o no.
El entorno de pruebas
La AEAT mantiene un portal de pruebas externas en preportal.aeat.es, con sus propias direcciones de WSDL y esquemas bajo prewww2.aeat.es. Se puede probar el ciclo completo —alta, anulación, subsanación y consulta— antes de tocar producción. Conviene, porque las validaciones de negocio son estrictas y la lista de errores es larga: la AEAT publica un documento de validaciones y errores aparte del de servicios web.
Dos detalles que descubren tarde casi todos los que integran: los campos numéricos no admiten ceros a la izquierda (01230 es incorrecto; va 1230), y los espacios al principio y al final de las cadenas de texto se eliminan —la AEAT devuelve y almacena el valor ya recortado, que puede no ser el que tú creías haber enviado—.
Si no eres desarrollador y has llegado hasta aquí
Lo que importa de todo esto en una decisión de compra es una sola pregunta: ¿el programa envía él solo? Un programa en modo «VERI*FACTU» hace toda esta conversación por dentro y no te pide certificados ni te enseña un solo XML. Si un fabricante te dice que tienes que «configurar la API» o subir tú un certificado, estás asumiendo trabajo de integrador sin serlo.
Sin integrar nada
Seis programas que ya hablan con la AEAT
Comparados con precios comprobados, y con la columna que de verdad importa: si puedes llevarte tu libro registro.
Las cifras —1.000 registros por envío, 60 segundos de espera inicial, 10.000 por respuesta de consulta— y los nombres de los estados están tomados del documento «Sistemas Informáticos de Facturación: descripción de servicios web» que publica el Departamento de Informática Tributaria de la AEAT, versión 1.0.3, y del articulado de la Orden HAC/1177/2024. No hemos integrado contra el servicio: lo que aquí se afirma es lo que dice la documentación oficial, y así está dicho.
Orden HAC/1177/2024, de 17 de octubre (BOE-A-2024-22138), artículo 16.2 · WSDL de los servicios web y información técnica de VERI*FACTU, sede electrónica de la AEAT. Enlaces comprobados el 23·08·2026.