Integrar la API de Verifactu en un fin de semana: guía para desarrolladores

Si te preguntas cómo afrontar la integración de la API Verifactu como guía para desarrolladores sin perder semanas de trabajo, la respuesta corta es que es perfectamente factible en 48 horas si cuentas con una buena arquitectura y el proveedor adecuado. Verifactu —el sistema de registro de facturas con envío voluntario o automático a la AEAT contemplado en el Real Decreto 1007/2023— será obligatorio desde el 1 de enero de 2027 para sociedades sujetas al Impuesto sobre Sociedades y desde el 1 de julio de 2027 para autónomos y demás contribuyentes del IRPF con actividad económica. Tienes margen, pero adelantar la integración te evitará prisas y te dará ventaja competitiva.

¿Qué es Verifactu y qué implica para tu software?

Verifactu es el sistema de facturación verificable que impone el RD 1007/2023, desarrollado por la Orden HAC/1177/2024. Obliga a que todo registro de factura esté firmado digitalmente, encadenado criptográficamente con el anterior y, si el sistema opera en modo de envío automático, transmitido a la AEAT en tiempo real. El resultado es un QR y un CSV oficial que el receptor puede validar en la sede electrónica de la Agencia Tributaria.

Los obligados al Suministro Inmediato de Información (SII) quedan excluidos de Verifactu; si tu cliente ya reporta por SII, no necesita este sistema. Para el resto, usar o comercializar software de facturación no conforme puede acarrear sanciones de hasta 50.000 € por ejercicio según el artículo 201 bis de la Ley General Tributaria, introducido por la Ley 11/2021.

Un detalle clave para los equipos de desarrollo: no existe homologación ni certificación oficial del software. El fabricante o proveedor debe presentar una declaración responsable de conformidad con el RD 1007/2023 y la Orden HAC/1177/2024. Eso significa que tú, como desarrollador que integra, debes asegurarte de que el proveedor de la API ha emitido dicha declaración.

Arquitectura de la integración: lo que necesitas entender antes de escribir código

Antes de abrir el editor, conviene tener claro el flujo de datos que exige Verifactu:

1. Generación del registro de factura: tu sistema ERP, e-commerce o SaaS produce los datos de la factura (número, fecha, NIF emisor, NIF receptor, base imponible, cuota de IVA, etc.).
2. Firma y encadenamiento: cada registro debe firmarse con el certificado electrónico del emisor y encadenarse con el hash del registro anterior. Este paso es el más crítico y el que más tiempo consume si lo implementas desde cero.
3. Envío a la AEAT: el registro firmado se transmite al endpoint de la Agencia Tributaria (o se encola para envío por lotes o programado).
4. Recepción del QR y CSV oficial: la AEAT devuelve un código QR y un CSV que deben imprimirse o incluirse en el PDF de la factura.
5. Almacenamiento del encadenamiento: el hash de cada registro debe persistir para encadenar la siguiente factura.

Implementar los pasos 2 a 5 desde cero puede llevar semanas. La alternativa inteligente es delegar ese núcleo en una API especializada como FactuGuard y centrarte únicamente en la lógica de tu negocio.

Comparativa: integración propia vs. API de terceros

Plan de integración en un fin de semana con FactuGuard

A continuación te detallamos cómo estructurar las 48 horas para tener la integración de la api verifactu guia desarrolladores lista y funcionando en entorno de producción.

Sábado por la mañana: alta y exploración del sandbox

1. Regístrate en FactuGuard. El sandbox es gratuito y no requiere tarjeta de crédito.
2. Obtén tu API key de sandbox desde el panel de control.
3. Lee la documentación del endpoint POST /facturas: revisa los campos obligatorios (NIF emisor, número de factura, serie, fecha, líneas de detalle, tipos de IVA).
4. Lanza tu primera llamada con cURL o Postman para validar la conectividad y la autenticación por cabecera.

Sábado por la tarde: mapeo de datos y primera factura de prueba

1. Mapea los campos de tu modelo de datos interno a los campos del JSON de FactuGuard. Presta atención a los formatos de fecha (ISO 8601) y a los importes (decimal con punto, sin símbolo de moneda).
2. Envía una factura de prueba completa y verifica que recibes el QR y el CSV oficial en la respuesta.
3. Prueba el envío de una factura rectificativa y una anulación: estos casos de uso suelen pasarse por alto y generan incidencias en producción.
4. Si usas Stripe, activa la importación automática desde Stripe disponible en FactuGuard y comprueba que los cargos se convierten en facturas correctamente.

Domingo por la mañana: integración en tu código base

1. Crea un servicio o módulo dedicado (VerifactuService o similar) que encapsule todas las llamadas a la API. Nunca disperses las llamadas por el código.
2. Implementa reintentos con backoff exponencial: la AEAT puede tener latencia variable y tu integración debe ser resiliente.
3. Persiste en tu base de datos el identificador de registro devuelto por FactuGuard y el estado de envío (pendiente, enviado, error). Esto es crítico para auditorías.
4. Si tu volumen lo justifica, configura el modo por lotes o programado en lugar del envío automático uno a uno.

Domingo por la tarde: tests, revisión y paso a producción

1. Escribe tests de integración que cubran los flujos principales: factura ordinaria, rectificativa y anulación.
2. Verifica que el QR generado es legible y que el CSV pasa la validación en la sede electrónica de la AEAT (en cuanto esté disponible el validador público).
3. Cambia la API key de sandbox por la de producción y ajusta la variable de entorno del endpoint base.
4. Despliega en staging, ejecuta una factura real de bajo importe y confirma el ciclo completo.

Planes de FactuGuard: elige el que se ajusta a tu proyecto

Todos los planes incluyen facturación multi-NIF y acceso API. La contratación anual aplica un descuento del 10 %. Para agencias y desarrolladores que integran Verifactu para múltiples clientes, el plan Partner es el más eficiente por coste unitario.

Errores comunes que debes evitar

• No persistir el hash de encadenamiento: si tu base de datos pierde el hash del último registro, la cadena se rompe y debes coordinarlo con la AEAT.
• Ignorar las facturas rectificativas: tienen campos específicos (referencia a la factura original, motivo de rectificación) que no son opcionales.
• Confundir Verifactu con la factura electrónica B2B: Verifactu regula el registro y reporte a la AEAT; la factura electrónica obligatoria entre empresas deriva de la Ley Crea y Crece y es un sistema diferente que FactuGuard no gestiona actualmente.
• Asumir que cualquier software cumple: recuerda que solo es válido el software cuyo fabricante haya emitido la declaración responsable de conformidad. Verifica este punto antes de elegir cualquier proveedor.
• No probar el modo offline: si tu aplicación puede operar sin conexión, necesitas una estrategia de cola para enviar los registros en cuanto se recupere la conectividad.

Preguntas frecuentes

¿Cuándo es obligatorio Verifactu para mi cliente?

Desde el 1 de enero de 2027 para empresas sujetas al Impuesto sobre Sociedades y desde el 1 de julio de 2027 para autónomos y demás contribuyentes del IRPF con actividad económica. Los obligados al SII quedan excluidos de esta obligación.

¿Necesito que el software esté homologado o certificado por la AEAT?

No existe un proceso de homologación oficial. El fabricante o proveedor del software debe emitir una declaración responsable de conformidad con el RD 1007/2023 y la Orden HAC/1177/2024. Es tu responsabilidad verificar que tu proveedor ha emitido dicha declaración.

¿Qué pasa si mi software no cumple con Verifactu?

El artículo 201 bis de la Ley General Tributaria contempla sanciones de hasta 50.000 € por ejercicio por producir, comercializar o usar software de facturación no conforme. La infracción aplica tanto al desarrollador como al usuario final.

¿Puedo probar la API de FactuGuard antes de comprometer un pago?

Sí. FactuGuard ofrece un sandbox gratuito sin necesidad de tarjeta de crédito. Puedes explorar todos los endpoints, enviar facturas de prueba y recibir respuestas simuladas antes de activar cualquier plan de pago.

En resumen, integrar la api verifactu guia desarrolladores en un fin de semana no es una promesa vacía: con un proveedor como FactuGuard que abstrae la firma, el encadenamiento y la comunicación con la AEAT, tu equipo puede centrarse en la lógica de negocio y tener el sistema operativo antes de que llegue la obligación legal.