API de Verifactu para desarrolladores

¿Estás desarrollando o manteniendo un software de facturación y necesitas cumplir con Verifactu? Aquí tienes todo lo que necesitas saber para integrar la API de Quaderno y olvidarte de rollos.

Esta guía para desarrolladores es para ti, que quieres una solución robusta, rápida de implementar y conforme con el Reglamento Verifactu. Es la referencia de Verifactu para desarrolladores que nos piden a diario los equipos técnicos que integran facturación en España.

¿Por qué usar la API de Quaderno y no conectar directamente con Hacienda?

Como desarrollador, seguro que te tienta hacer la integración desde cero. Pero en cuanto te metes en faena, descubres lo que realmente implica: XML, certificados digitales, documentación críptica y una burocracia que no perdona errores.

Aquí es donde entra la API de Verifactu que tenemos en Quaderno. Te ofrece:

• Formato JSON en lugar de XML, más sencillo y manejable para cualquier stack moderno.
• QR al instante, directamente en la respuesta de la API, para que lo integres en tu factura sin esperar.
• Nos encargamos del encadenamiento, la firma digital y la generación del XML.
• Entorno de pruebas realista, para que no te lleves sorpresas en producción.
• Soporte técnico humano y actualizado, nada de foros desiertos o PDFs desfasados.
• Cumplimiento del Reglamento Verifactu, con la declaración responsable que puedes enseñar a tus clientes.

Resumiéndolo mucho, estas son las ventajas técnicas frente a la integración directa

Aspecto	API Quaderno	Integración directa con AEAT
Formato de envío	JSON	XML
Certificado y firma	Subes tu certificado una vez y nosotros gestionamos el envío	Gestionas el certificado y, en modo no Verifactu, implementas la firma XAdES
Generación de QR	Automática, en la respuesta	Debes generarlo tú mismo
Encadenamiento	Automático	Debes implementarlo tú
Entorno de pruebas	Simula flujo completo	Limitado y poco documentado
Tiempo de puesta en marcha	Días	Semanas o meses
Soporte	Técnico y humano, especializado	Generalista y con poca interacción

Qué implica para un desarrollador integrar Verifactu directamente con la AEAT

Conviene decirlo sin dramatismo: conectar con la AEAT es una integración normal, no magia negra. Lo que la vuelve costosa es que son seis piezas de trabajo distintas y tienen que estar bien a la vez. El Reglamento no da puntos por aproximarse.

Esta es la lista, con dónde está especificada cada pieza.

Pieza	Qué tienes que construir	Dónde está especificado
Formato y transporte	XML en UTF-8 validado contra los esquemas XSD, enviado por servicios web SOAP sobre HTTPS	Art. 16 de la Orden HAC/1177/2024, más los WSDL y esquemas de la Sede de la AEAT
Certificado	Autenticación con certificado electrónico cualificado, y apoderamiento si facturas por cuenta de terceros	Resolución de 18 de diciembre de 2024 sobre representación de terceros
Huella y encadenamiento	SHA-256 sobre siete campos del registro, más la referencia al registro anterior	Arts. 7 y 13 de la Orden HAC/1177/2024
Firma electrónica	XAdES Enveloped Signature según ETSI EN 319 132, solo si operas en modo no Verifactu	Arts. 3 y 14 de la Orden HAC/1177/2024
Código QR	QR de 30x30 a 40x40 mm, nivel de corrección M, con la URL de cotejo y cuatro datos de la factura	Arts. 20 y 21 de la Orden HAC/1177/2024
Errores y control de flujo	Tratamiento de errores admisibles y no admisibles, y respeto del tiempo de espera que devuelve la AEAT	Documento de validaciones y errores de la Sede de la AEAT

Ojo con la firma, que es donde más se subestima el trabajo. En modo Verifactu el envío inmediato del registro es lo que le da la garantía, así que te libras de firmar y de conservar. En modo no Verifactu firmas cada registro con XAdES, lo conservas, mantienes un registro de eventos y lo entregas cuando te lo pidan. Son semanas de diferencia.

Y esto no se termina nunca: la especificación ya se ha modificado dos veces. No construyes algo que se acaba, adoptas un componente que ahora te pertenece.

De esas seis piezas hay una que no se queda en la capa de integración. Te cambia la base de datos.

Encadenamiento y huella: lo que cambia en tu modelo de datos

Todo el mundo menciona el encadenamiento en una lista de características. Casi nadie dice lo que significa para tu esquema, que es lo que necesitas antes de escribir la primera migración.

El mecanismo, en corto. Los registros de facturación no son independientes entre sí: cada uno arrastra cuatro datos del registro inmediatamente anterior, según el artículo 7 de la Orden HAC/1177/2024:

• Los primeros 64 caracteres de su huella
• Su NIF
• Su número de factura
• Su fecha de expedición

El primer registro de todos se marca como origen de la cadena.

Por eso las correcciones son registros nuevos, no ediciones. Hay tres tipos de registros de facturación: alta, subsanación para corregir uno ya presentado y anulación para dejar sin efecto uno anterior. Una anulación no borra nada, añade un registro que dice que el anterior queda anulado.

En tu código eso se traduce en cuatro cosas:

• El orden no es ORDER BY created_at. El orden es la cadena.
• Un envío fallido ya ocupó su lugar en la secuencia. Al reintentar reenvías ese registro, no generas uno nuevo.
• «Ya le asignaré el número luego» y «renumeramos a cierre de ejercicio» dejan de estar disponibles.
• Los datos de prueba y los de producción no pueden compartir cadena.

El caso clásico es un cron de suscripciones que reintenta un cobro fallido y regenera la factura. Con Verifactu activo esa segunda factura es un registro nuevo, no un reemplazo, y la primera sigue necesitando su anulación.

¿Cómo funciona nuestra API?

Puedes ver muchos más detalles en nuestra documentación técnica, pero aquí tienes el flujo típico para emitir una factura con Verifactu usando la API de Quaderno:

1. Envías la factura en JSON

Solo necesitas hacer una petición POST con los datos de la factura. Nada de firmar, generar hashes ni preparar XMLs. Nosotros nos encargamos.

Por ejemplo:

{
  "type": "sale",
  "currency": "EUR",
  "customer": {
    "first_name": "Luis",
    "last_name": "García",
    "street_line_1": "Calle Alcalá",
    "city": "Madrid",
    "postal_code": "28014",
    "country": "ES",
    "tax_id": "00000000T"
  },
  "evidence": {
    "billing_country": "ES",
    "ip_address": "255.255.255.255",
    "bank_country": "ES"
  },
  "items": [
    {
      "description": "Suscripción mensual a contenido digital",
      "amount": 9.90,
      "product_code": "DIG_ES_001",
      "tax": {
        "country": "ES",
        "rate": 21.0,
        "tax_code": "eservice",
        "name": "IVA"
      }
    }
  ],
  "payment": {
    "method": "credit_card"
  },
  "processor": "aPaymentProcessor",
  "processor_id": "pp_1234567890"
}

2. Quaderno gestiona el resto

Nos ocupamos del:

• Encadenamiento del registro (referencia a la factura anterior)
• Generación del XML en el formato oficial
• Autenticación del envío con tu certificado electrónico
• Envío a la AEAT
• Espera de la respuesta oficial

3. Rectificaciones y trazabilidad

¿Necesitas emitir una factura rectificativa o subsanar un error? Puedes hacerlo desde la API, y el registro original se mantiene intacto, que es lo que exige el encadenamiento. Además guardamos un histórico de logs para que puedas depurar qué pasó en cada envío.

Casos de uso comunes para desarrolladores

Aquí es donde la API de Quaderno demuestra su utilidad real. No solo cumple con Verifactu, también resuelve problemas cotidianos que te vas a encontrar sí o sí como desarrollador:

1. Crear y emitir facturas nuevas

La API te permite enviar facturas en formato JSON desde cualquier parte de tu stack: backend propio, microservicios o plataforma de terceros. Lo haces con una petición POST y recibes un enlace a la factura, que emite Quaderno.

¿Tienes un sistema de suscripciones con cientos de clientes? Puedes automatizarlo todo desde el cron job que ya tienes para renovar pagos.

Así, cada renovación genera su factura, la comunica a la AEAT y tú no tocas ni una línea más de código después de integrar.

2. Rectificar, subsanar y volver a enviar

Los errores ocurren, y conviene saber quién los recoge. Si la AEAT rechaza un registro, recibes un delivery.rejected con el motivo; si falla el envío, un delivery.failed. Para corregir el contenido de una factura ya emitida emites una factura rectificativa, porque el registro original no se toca. Y el reintento lo decides tú: nuestra API no reenvía por su cuenta, así que esa lógica vive en tu integración.

Todo con endpoints bien documentados y respuestas claras. Te olvidas del «debug a ciegas».

3. Operar con varios clientes, NIF o entornos

Si tu software da servicio a múltiples empresas o perfiles fiscales, puedes asociar cada NIF con una clave y gestionar sus facturas de forma independiente. Incluso puedes tenerlos en modo test o producción de forma simultánea.

Para llamar a nuestra API te basta una clave: no hay certificados de cliente ni librerías que instalar, y puedes gestionarlo todo desde tu API Gateway o backend. Tu certificado electrónico es otra cosa y sí hace falta, pero lo subes una vez y lo usamos nosotros para autenticar el envío a la AEAT. Flexible para quien desarrolla SaaS y también para quien desarrolla a medida.

Entorno de pruebas y puesta en producción

Lo típico al empezar una integración fiscal es que te frenes: la documentación no cuadra, los entornos no funcionan igual que en producción, y encima nadie responde tus dudas. Aquí, eso NO pasa.

1. Los dos entornos de pruebas que existen

Hay dos entornos de pruebas y se confunden constantemente, así que vamos a separarlos.

Uno es el de la AEAT. La Agencia publica un portal de pruebas externas junto con la documentación técnica, los WSDL y los esquemas. Sirve para algo muy concreto: validar que tu XML pasa los esquemas XSD y que calculas bien la huella, antes de que exista ningún registro real.

No sirve para pruebas de carga. Y el paso que se lleva la primera mañana entera es siempre el mismo: conseguir los certificados de prueba.

El otro es el sandbox de tu proveedor, del que hablamos justo debajo. La regla que no conviene saltarse es la misma en ambos: nunca apuntes un sandbox contra una cadena de producción, por lo que veíamos en el apartado anterior.

2. Sandbox realista y accesible desde el minuto uno

En cuanto creas tu cuenta, tienes un entorno sandbox funcional. Sin esperas. Y se comporta igual que el entorno en producción, lo que significa que puedes probar todos los flujos reales sin tener que cambiar tu código después.

3. Logs detallados y respuestas legibles

¿Algo ha fallado? No te devolvemos un código y ya está. Te decimos exactamente qué ha pasado: si hay un campo malformado, un NIF no válido, una línea mal calculada.

4. Asistencia técnica que habla tu idioma

Si algo no encaja o no sabes cómo montar cierto caso, no estás solo. Puedes escribirnos y hablarás con alguien que entiende tu contexto, que ha visto cientos de integraciones como la tuya y que va a darte una solución clara y útil. Si hay un bloqueo, lo desbloqueamos contigo.

Seguridad, cumplimiento y confianza

Y no basta con que funcione. Tiene que cumplir con la ley, garantizar la trazabilidad y evitar cualquier marrón legal para ti o para tus clientes.

1. Cumplimiento del Reglamento Verifactu

Conviene ser precisos, porque hay mucha confusión en el mercado: la AEAT no homologa, no aprueba y no certifica software de facturación. La certificación existe y es obligatoria, pero la firma el propio fabricante. Lo que exige el RD 1007/2023 es que el productor del software emita una declaración responsable, y responda él de lo que declara. Eso es lo que puedes enseñar a tus clientes o a un inspector. Si alguien te vende «software homologado Verifactu», desconfía: el registro de software garante existe en TicketBAI, no aquí.

2. Seguridad a nivel enterprise

Tus datos y los de tus clientes están protegidos por tres cosas:

• Toda la comunicación usa TLS.
• Los datos se almacenan cumpliendo el RGPD.
• Formamos parte del programa de seguridad de Visma, con auditorías periódicas y control de acceso granular.

3. Mantenimiento normativo y responsabilidad

Si mañana Hacienda cambia el formato del XML, añade un nuevo campo o impone un nuevo QR… nosotros nos adaptamos. Tú no tienes que rehacer nada. Además, te damos acceso a la declaración responsable, que puedes usar para acreditar ante tus clientes que tu sistema cumple con la ley.

Y, si un inspector fiscal pregunta, tienes respaldo documental y técnico desde el primer día.

Qué te ahorra la API de Quaderno, y qué te obliga a aceptar

Volvamos a la lista de seis piezas del principio. Con nuestra API no construyes ninguna. La factura se envía con un POST /transactions en JSON, la misma llamada que harías sin Verifactu, y la configuración son dos pasos que haces una sola vez:

1. Subes tu certificado electrónico en la página de Certificados. Tiene que estar emitido al mismo NIF y al mismo nombre que figuran en tu cuenta de Quaderno.
2. Conectas Verifactu desde la página de Integraciones y autorizas el envío a la AEAT.

A partir de ahí enviamos automáticamente todas las facturas, tickets y abonos a la Agencia Tributaria. La respuesta trae el verification_code y la verification_url, y el documento generado muestra su identificador y el QR para que tu cliente lo compruebe.

Para saber cómo fue cada envío tienes tres webhooks, y merece la pena distinguirlos porque piden código distinto:

• delivery.succeeded: la AEAT ha aceptado el registro.
• delivery.failed: el envío falló por un problema técnico, de red o de servicio. Los datos pueden estar perfectos.
• delivery.rejected: la AEAT rechazó el documento por errores de validación. Aquí sí tienes que corregir algo.

Un límite honesto: nuestra API no reintenta ni hace seguimiento de una llamada fallida. Los webhooks te cuentan qué pasó; qué hacer con eso es tu código.

Si estás evaluando el producto y no el cómo, la página de la API de Verifactu tiene el detalle comercial y el resto de integraciones.

Tres limitaciones que debes conocer antes de diseñar

Ninguna de las páginas que compiten por esta búsqueda publica las suyas. Preferimos que las sepas ahora y no a mitad de la integración.

1. La numeración y la fecha de emisión las asigna Quaderno. Con Verifactu activo no puedes fijar un number ni un issue_date propios. Ya sabes por qué: es la cadena.
2. Validamos nombre y NIF contra el registro de la AEAT en las facturas completas a clientes españoles. Si la validación falla, la factura se guarda como borrador en la bandeja de entrada para que corrijas los datos a mano, y no se emite. Necesitas un estado para «emitida en mi sistema, todavía no emitida fiscalmente».
3. Quaderno es un sistema exclusivamente VERI*FACTU. El campo 1.e de su declaración responsable lo declara así, de modo que el envío no es un flag que puedas desactivar desde la cuenta. Para detenerlo hay que escribir a soporte. Una cadena que puedes apagar en silencio no es una cadena.

¿Ya lo tienes claro?

Perfecto. Disfruta de nuestra API de Verifactu para desarrolladores.

Para seguir, esto es lo que puedes hacer ahora mismo:

• Accede a la documentación técnica y empieza a trastear.
• ¿Prefieres que alguien te oriente primero? Reserva una sesión con nuestro equipo técnico y saldrás con las ideas claras.
• ¿Quieres probar sin compromiso? Crea tu cuenta gratuita y accede al entorno de test en menos de 2 minutos.