API Adaptador Verifactu: La Solución Técnica Definitiva para Integrar tu Software con Hacienda

El panorama tecnológico y fiscal en España ha sufrido un terremoto con la aprobación de la Ley Antifraude y el posterior desarrollo del Reglamento Verifactu. Para los directores de tecnología (CTOs), desarrolladores de software independientes y gerentes de PYMES con sistemas propios, esto plantea una encrucijada crítica: ¿Cómo adaptamos nuestro software actual, que funciona perfectamente, a unos requisitos técnicos de inalterabilidad y comunicación telemática extremadamente complejos?

La respuesta no pasa necesariamente por tirar a la basura tu antiguo ERP ni por contratar a un equipo de criptógrafos durante seis meses. La solución más eficiente, escalable y segura es la implementación de una api adaptador verifactu. Esta tecnología permite externalizar la complejidad normativa, manteniendo tu lógica de negocio intacta.

1. ¿Qué es una API Adaptador Verifactu y cómo salva tu software?

En el ecosistema de desarrollo de software, una API (Application Programming Interface) es el conjunto de definiciones y protocolos que se utiliza para desarrollar e integrar el software de las aplicaciones. En el contexto específico de la nueva normativa fiscal española, una API adaptador Verifactu es un servicio web (generalmente RESTful) diseñado para recibir los datos «crudos» de una factura desde tu sistema y devolverlos procesados, firmados y validados según los estándares de la AEAT.

Tu software de gestión, ya sea un Excel avanzado con macros (que dejará de ser válido por sí mismo), un ERP legacy en Visual Basic, o una moderna plataforma en la nube, necesita «hablar» con Hacienda. Pero Hacienda no habla JSON ni SQL; Hacienda exige ficheros XML con una estructura sintáctica (XSD) muy rígida, firmados con certificados electrónicos cualificados y con huellas digitales encadenadas.

La función de «Caja Negra» Legal

El adaptador funciona como una caja negra para tu sistema:

• Entrada: Datos de facturación (Cliente, Importe, Fecha).

• Proceso Interno (Middleware): Validación de datos, cálculo de hash SHA-256, encadenamiento con el registro anterior, firma electrónica (XAdES), conexión HTTPS segura con la sede de la AEAT.

• Salida: Confirmación de registro (CSV), cadena para el código QR y custodia del log de transacciones.

2. Arquitectura Profunda: El Motor de Cumplimiento

Para los perfiles técnicos, es fundamental comprender qué ocurre dentro de la API. No es solo un «proxy» de envío; es un motor de cumplimiento normativo. El Reglamento Verifactu impone requisitos de Integridad, Conservación, Accesibilidad, Legibilidad, Trazabilidad e Inalterabilidad (I.C.A.L.T.I.).

2.1. El Motor Criptográfico: Hash y Encadenamiento

El corazón de Verifactu es el «encadenamiento». Cada registro de facturación de alta debe incluir una huella digital (Hash) que se calcula basándose en los datos de la propia factura Y en parte de la huella de la factura anterior.

Algoritmo SHA-256: La normativa especifica el uso de ISO/IEC 10118-3:2018. La API se encarga de:

1. Normalizar los campos de la factura (eliminar espacios, ajustar formatos de fecha ISO 8601, decimales).
2. Recuperar el Hash de la factura `F-1` (la anterior cronológicamente).
3. Concatenar los datos + Hash anterior.
4. Generar el nuevo Hash de la factura `F`.

Este proceso garantiza que si alguien intenta insertar, modificar o borrar una factura intermedia en tu base de datos, la cadena matemática se rompe, evidenciando la manipulación ante una inspección. La API gestiona la persistencia de estos hashes para asegurar que nunca se pierda el eslabón anterior, algo crítico para evitar las sanciones millonarias de la AEAT.

2.2. Gestión de Certificados y Firma Desatendida

El envío a la AEAT debe ir firmado electrónicamente. Aquí surgen dos complejidades que la API resuelve:

• Formato de Firma: No vale cualquier firma. Se requiere XAdES-EPES (XML Advanced Electronic Signatures with Explicit Policy based Electronic Signature). Implementar esto desde cero es una pesadilla para cualquier desarrollador.

• Custodia de Claves: La API permite alojar el certificado digital de la empresa (sello electrónico o certificado de representante) en un servidor seguro (HSM – Hardware Security Module) para realizar firmas desatendidas («cloud signing»). Esto significa que tu ERP no necesita tener acceso físico al certificado en cada terminal, lo que mejora la seguridad y facilita el uso en entornos distribuidos o web.

3. Desarrollo Propio vs. API Externa: La Decisión del Millón

Muchas empresas con departamento de IT se plantean: «¿Por qué pagar una API si tenemos programadores?». La respuesta radica en el coste de oportunidad y el riesgo normativo (Liability).

Análisis de Coste Total de Propiedad (TCO)

4. Guía Técnica de Integración Paso a Paso

A continuación, detallamos el flujo de trabajo que un equipo de desarrollo debe seguir para integrar una API Verifactu estándar. Aunque cada proveedor tiene su documentación (Swagger/OpenAPI), los pasos lógicos son universales.

Fase 1: Preparación del Entorno

Solicita acceso al entorno de Sandbox. Nunca comiences a desarrollar contra el entorno de producción de la AEAT. En el Sandbox, las facturas no tienen validez tributaria y puedes probar casos de error (facturas rectificativas, NIFs erróneos, saltos de fecha) sin miedo a inspecciones.

Fase 2: Mapeo de Datos (Data Mapping)

Debes alinear tu modelo de datos con el de la API. Presta atención a:

• Series de Facturación: Verifactu es estricto. No puedes mezclar series ni tener huecos.

• Tipos de Operación: Debes distinguir si es una entrega de bienes, prestación de servicios, o pagos anticipados.

• Regímenes de IVA: Identificar correctamente si es Régimen General, Recargo de Equivalencia, Exento (y su causa), etc.

Fase 3: Implementación del Disparador (Trigger)

La normativa exige la remisión «inmediata» tras la expedición. En términos de UX/UI:

1. El usuario pulsa «Emitir Factura».
2. El sistema bloquea la edición del documento.
3. Se envía la petición (Request) a la API.
4. Se espera la respuesta (Response) síncrona.

Fase 4: Gestión de la Respuesta y Storage

La API devolverá un objeto JSON que suele contener:

• status: Éxito o Error.

• csv: Código Seguro de Verificación asignado por la AEAT.

• chain_hash: La huella digital generada.

• qr_url: La cadena de texto para generar el código QR.

Fase 5: Impresión y Código QR

Debes actualizar tu motor de generación de PDFs (o tickets) para incluir el código QR con los datos devueltos por la API y la frase legal: «Factura verificable en la sede electrónica de la AEAT» o el distintivo «VERI*FACTU». Para detalles de diseño y ubicación, consulta requisitos del código QR en facturas.

5. Ejemplos de Código para Desarrolladores

Veamos cómo se materializa esto en código real. Estos ejemplos son ilustrativos para un endpoint REST estándar.

Ejemplo PHP (cURL) para PrestaShop/WooCommerce

// Datos de la factura extraídos del pedido
$payload = [
    'api_key' => 'sk_live_xxxxxxxx',
    'emisor' => ['nif' => 'B12345678'],
    'factura' => [
        'serie' => '2025',
        'numero' => '00123',
        'fecha_expedicion' => '2025-01-15T10:00:00', // ISO 8601
        'tipo' => 'F1', // Factura completa
        'cliente' => [
            'nombre' => 'Cliente Ejemplo S.L.',
            'nif' => 'B98765432',
            'pais' => 'ES'
        ],
        'lineas' => [
            ['descripcion' => 'Servicio Consultoría', 'base' => 1000.00, 'iva' => 21]
        ]
    ]
];

$ch = curl_init('https://api.proveedor-verifactu.com/v1/invoices/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($httpCode === 200 && $result['status'] === 'success') {
    // ÉXITO: Guardar datos fiscales
    updateInvoiceDatabase($invoiceId, $result['csv'], $result['qr_string'], $result['chain_hash']);
} else {
    // ERROR: Gestionar rechazo o reintento
    logError("Error Verifactu: " . $result['error_message']);
    // No permitir finalizar la venta o marcar como "pendiente de corrección"
}
    

Ejemplo Python (Requests) para Odoo/Django

import requests
import json

url = "https://api.proveedor-verifactu.com/v1/invoices/send"
headers = {
    "Authorization": "Bearer sk_live_xxxxxxxx",
    "Content-Type": "application/json"
}

data = {
    "invoice": {
        "serial": "2025",
        "number": "00123",
        "date": "2025-01-15",
        "total_amount": 1210.00,
        "taxes": [{"rate": 21, "base": 1000.00}]
    }
}

try:
    response = requests.post(url, json=data, headers=headers, timeout=10)
    response.raise_for_status() # Lanza excepción si no es 200
    
    api_response = response.json()
    
    # Guardar huella y CSV
    invoice.verifactu_csv = api_response['csv']
    invoice.verifactu_qr = api_response['qr_string']
    invoice.save()
    
except requests.exceptions.RequestException as e:
    # Manejo de errores de conexión o rechazo de la API
    print(f"Error crítico enviando a Verifactu: {e}")
    # Implementar lógica de "Reintento" o "Modo Offline"
    

6. Seguridad, ISO 27001 y RGPD

Cuando integras una API externa, estás enviando datos financieros y personales de tus clientes a un tercero. Esto tiene implicaciones serias en materia de Protección de Datos (RGPD) y seguridad corporativa.

Al elegir tu proveedor de API, debes exigir:

• Certificación ISO 27001: Es el estándar de oro en seguridad de la información. Garantiza que el proveedor tiene controles estrictos sobre quién accede a los datos.

• Esquema Nacional de Seguridad (ENS): Valorable positivamente, ya que acredita el cumplimiento de estándares exigidos por la administración española.

• Ubicación de los Servidores: Los datos deben residir en la Unión Europea para cumplir con el RGPD sin burocracia adicional.

• Acuerdo de Encargado de Tratamiento: Debes firmar un contrato donde el proveedor de la API actúe como encargado del tratamiento de los datos, comprometiéndose a no usarlos para fines propios.

7. Casos de Uso Complejos: TPVs, SaaS y Multi-Tenant

La integración de la API no es igual para una tienda de zapatos que para una plataforma SaaS que da servicio a miles de empresas.

Para Software SaaS (Multi-Tenant)

Si eres un desarrollador que vende un software en la nube a muchas empresas, necesitas una API que soporte Multi-Tenancy. Esto significa que con una sola integración técnica, puedes gestionar los certificados digitales y los envíos de miles de NIFs diferentes, manteniendo los datos segregados y seguros. La API debe permitirte configurar un «profile» o «entidad» para cada uno de tus clientes.

Para TPVs y Puntos de Venta Físicos

Los comercios minoristas tienen un reto: la conectividad. ¿Qué pasa si se cae internet en la tienda? La API y tu software deben soportar un modo «Store & Forward». El TPV debe ser capaz de generar y firmar (o al menos hashear) la factura en local (o en un servidor intermedio) y encolar el envío para cuando vuelva la conexión, respetando el orden secuencial. Si gestionas TPVs, es vital que leas nuestra guía específica sobre TPV Verifactu.

Para E-commerce (WooCommerce / Shopify)

Las tiendas online emiten facturas 24/7 automáticamente. Aquí no hay un humano para corregir errores. La integración debe ser robusta y manejar excepciones (ej: NIFs intracomunitarios inválidos) sin detener las ventas. Existen plugins que conectan estas plataformas con APIs Verifactu. Aprende más en adaptar WooCommerce a Verifactu.

8. Errores Fatales que Debes Evitar

Basándonos en la experiencia técnica de integraciones reales, estos son los «bugs» que pueden costarte una inspección:

1. Reutilización de huecos: Si anulas la factura 10, no puedes volver a usar el número 10 para otra venta. Debes saltar al 11. El «hueco» de la 10 queda registrado como anulada.
2. Fechas incoherentes: Enviar una factura con fecha de expedición anterior a la fecha de la última factura enviada de la misma serie. El sistema de encadenamiento detectará la cronología rota.
3. Edición post-envío: Permitir modificar una factura en el ERP después de haber recibido el OK de la API. Esto crea una discrepancia entre tu contabilidad y la de Hacienda. Solución: Inmutabilidad total post-envío.
4. No gestionar los tiempos de espera (Timeouts): Si la AEAT tarda en responder, tu software no puede «colgarse» ni duplicar el envío por impaciencia. Implementa idempotency keys si la API lo soporta.

9. Verifactu y la Factura Electrónica B2B (Ley Crea y Crece)

Es fundamental no confundir Verifactu (envío de registros fiscales a Hacienda) con la Factura Electrónica B2B (intercambio de facturas entre empresas). Sin embargo, ambos sistemas convergen. Una buena API adaptador debería estar preparada para, en el futuro cercano, no solo enviar el registro a Hacienda, sino también generar la factura en formato Facturae y enviarla al cliente a través de las plataformas de intercambio públicas o privadas.

Preparar tu integración hoy para Verifactu es poner los cimientos para la obligatoriedad B2B. Para entender la diferencia, revisa Verifactu vs Facturación Tradicional.