La API de Verifactu Online para Verifactu está diseñada para facilitar el envío de información fiscal a la Agencia Tributaria, proporcionando una solución accesible a los desarrolladores de software de facturación. En lugar de integrarse directamente con la API de la administración, los desarrolladores pueden realizar sus peticiones a la API de Verifactu Online, evitando así complejidades tecnológicas y barreras técnicas.
Facilidad y rapidez
La API de Verifactu Online está diseñada para ofrecer una integración sencilla y rápida gracias a:
- Además, su documentación es clara y concisa, con ejemplos y colecciones Postman.
- Utiliza JSON, como formato de comunicación principal pero también puede leer XLS y CSV
- No existen límites de tiempo ni de número de llamadas.
- Eliminación de necesidad de certificados propios, utilizando certificados de representación de Verifactu Online.
- Soporte técnico dedicado, especialmente en la fase de integración.
Al utilizar la API de Verifactu Online, se evitan los principales retos de la integración directa con la administración, tales como:
- Documentación confusa e insuficiente.
- Uso obligatorio de XML como formato de comunicación.
- Restricciones de tiempo y frecuencia en las llamadas a la API de la administración.
- Firma obligatoria con certificado.
- Encadenamiento obligatorio de los registros de facturación.
- Generación y verificación de huellas/hash.
Guía rápida de integración con Verifactu
La integración de un software de facturación con la API Verifactu Online para Verifactu debe considerar los siguientes aspectos clave.
Tu código QR al instante
El flujo de funcionamiento de la API Verifactu Online sigue este esquema:
- Cuando se emite una nueva factura en el software de facturación, se envía una petición a la API de Verifactu Online con:
- Una API Key específica de la empresa emisora (NIF contribuyente).
- Un JSON con los datos de la factura (base imponible, IVA, total, etc.).
- La API de Verifactu Online responde de inmediato con un QR en formato Base64, listo para ser incluido en la factura y entregado al destinatario.
- En los siguientes 4 a 100 segundos, Verifactu Online envía la información a la API de la administración.
- La respuesta de la administración se recibe en XML.
- Se debe realizar una llamada posterior para consultar la respuesta de la administración y verificar si la factura fue aceptada o requiere correcciones.
El QR en VeriFactu Online
El QR en el sistema Verifactu es una URL codificada. En concreto, se trata de una URL única en la web de la Agencia Tributaria para una factura en particular. En esta URL, la administración nos dice si le consta haber recibido o no esa factura a través del sistema Verifactu.
La expectativa de la administración es que toda factura emitida por contribuyentes sujetos a la obligación del sistema Verifactu incorporen este QR. De este modo, cualquier receptor de una factura con un QR puede desde su dispositivo móvil acceder cómodamente a la URL de la factura y comprobar que esta ha sido comunicada a la Agencia Tributaria.
El QR se forma a partir de una serie de campos de la factura:
NIF emisor
Serie
Número
Fecha
Importe
La generación del QR es una de las partes más sencillas de la adecuación al sistema Verifactu. Si bien la API Verifactu Online devuelve el QR de manera inmediata cuando se genera una factura nueva, muchos de nuestros usuarios eligen generar el QR ellos mismos y pintarlo sobre la factura, puesto que este proceso es sencillo al existir librerías de generación de QR en la práctica totalidad de los lenguajes de programación.
No obligación de conservación XMLs en Verifactu
En modo Verifactu, no existe la obligación de conservar los registros de facturación enviados a la Agencia Tributaria, ni para el software de facturación ni para el contribuyente, puesto que dichos registros ya han sido remitidos previamente. La administración es clara a este respecto: la obligación de conservación de registros de facturación solo existe en el modo No-Verifactu.
Por registro de facturación, la administración entiende las llamadas realizadas a su API. Cada petición realizada a la API de Verifactu Online que se materialice en una llamada a la API de Verifactu constituye un registro de facturación. Se trata, por tanto, de los ficheros XML de petición a la administración y de respuesta de la administración. En modo Verifactu, no existe la obligación de conservar dichos ficheros.
Dicho esto, Verifactu Online facilita endpoints para descargar los registros de facturación para aquellos usuarios que deseen guardarlos. Asimismo, Verifactu Online guardará esta información durante un periodo amplio de tiempo.
Lo anterior no debe confundirse con la obligación de conservación de facturas derivada del Reglamento de Facturación u otras normas tributarias. Cualquier obligación que el software o sus usuarios (los contribuyentes) tuvieran antes de la aparición del sistema Verifactu sigue vigente tras su implementación.
Declaración responsable Verifactu
Emplazamiento de la declaración responsable
- La sección de pie de página (footer) del sitio web.
- Un endpoint específico en la API, para que los usuarios puedan consultarla fácilmente.
Numeración del software
Llamadas a API REST JSON
La API Verifactu Online es una API RESTful que opera con formato JSON. Antes de comenzar la integración, el desarrollador debe:
Familiarizarse con el concepto APIs REST y el formato JSON.
Revisar recursos y documentación en línea para entender mejor estos conceptos.
Confirmar que su entorno de desarrollo y lenguaje de programación soportan peticiones REST.
Estructurar peticiones JSON
- API Key: Identifica al contribuyente y define si el entorno es test o producción.
- Cuerpo en formato JSON con la información fiscal relevante.
- Crear factura
- Emitir factura rectificativa
- Subsanar factura
Consultar estado de registros
Las respuestas de la Administración a las peticiones no son síncronas. Existe un decalaje de 4 a 100 segundos entre el envío de la petición y la obtención de una respuesta. Por ello, es fundamental que el desarrollador implemente consultas específicas para comprobar el estado de sus peticiones. Esto permite:
- Confirmar que la petición fue procesada correctamente.
- Detectar errores de la Administración y corregirlos a tiempo.
Funcionamiento básico
- Cuando se emite una nueva factura en el software de facturación, se envía una petición a la API de Verifactu Online con:
- Una API Key específica de la empresa emisora (NIF contribuyente).
- Un JSON con los datos de la factura (base imponible, IVA, total, etc.).
- En primer lugar, la API responde de inmediato con un QR en formato Base64, listo para incluir en la factura y entregarlo al destinatario.
- A continuación, Verifactu Online transmite la información a la API de la administración, en un plazo de entre 4 y 100 segundos.
- Posteriormente, la administración devuelve la respuesta en formato XML.
- Por último, el desarrollador debe realizar una llamada para consultar dicha respuesta y confirmar si la factura fue aceptada o requiere correcciones.
API Verifactu Online como reflejo fiel de Verifactu
- Los endpoints.
- La estructura de las llamadas.
- Los mensajes de error devueltos por la administración.