Verifactu

La Ley Antifraude (Ley 11/2021) obliga a las empresas a garantizar que sus sistemas de facturación y contabilidad cumplan estrictos requisitos técnicos para evitar la manipulación de datos. El Real Decreto 1007/2023 define además los requisitos técnicos para los sistemas de facturación digital, enfatizando la necesidad de formatos de factura estandarizados a los que las autoridades fiscales puedan acceder fácilmente.

Estas regulaciones exigen que las empresas adopten sistemas capaces de generar, almacenar y transmitir facturas e informes fiscales de forma segura. La API REST de B2Brouter es una solución técnica que permite a tu empresa cumplir al 100% la normativa de forma sencilla, delegando las complejidades en B2Brouter y centrándote en la lógica de negocio de tu sistema.

¿Qué es Verifactu?

Verifactu es un sistema de cumplimiento diseñado para simplificar el proceso de cumplimiento de los requisitos de facturación establecidos en la Ley Antifraude. Garantiza que todas las facturas generadas por las empresas se transmitan de forma segura a la Agencia Tributaria para que puedan ser verificadas en cuanto a integridad y autenticidad tanto por la Agencia Tributaria como por el cliente. La Autoridad Fiscal española es la AEAT (“Agencia Estatal de Administración Tributaria”).

Verifactu implica la presentación inmediata y en tiempo real de los datos de la factura a la AEAT en cuanto se emite la factura. Esto garantiza que no se puedan realizar modificaciones después de emitir la factura, garantizando así su seguridad. Además, la factura contiene un código QR que permite al destinatario verificar su cumplimiento fiscal a través de la plataforma de la AEAT.

En la práctica, Verifactu requiere:

Crear un archivo XML de informe fiscal.
Calcular una huella digital para cada informe fiscal. Esto incluye una cadena de hash para crear un rastro a prueba de manipulaciones.
Ensamblar un “Libro de Registro” o Ledger que puede incluir uno o varios informes fiscales.
Presentación autenticada del “Libro de Registro” a la AEAT usando un certificado electrónico cualificado.
Respetar las solicitudes limitadas en frecuencia establecidas por la AEAT (máx. 1 llamada por minuto, salvo que se presenten >1.000 facturas).
Generar un código QR para la verificación de la factura, que se incluirá en la factura emitida.
Procesar las respuestas de la AEAT para cada informe fiscal.

Con B2Brouter puedes abstraer gran parte de las complejidades de este proceso y cumplir con la Ley Antifraude emitiendo solo unas pocas llamadas REST a la API. No necesitarás tu propio certificado electrónico cualificado porque B2Brouter es Colaborador Social en la Gestión Tributaria. Solo necesitas una clave API de B2Brouter válida.

Entornos de prueba: Usa el sandbox para las pruebas iniciales de la API y la validación de payloads — el sandbox simula las presentaciones de Verifactu para que puedas ejercitar el ciclo de vida de la factura sin contactar con la AEAT. Para pruebas completas de extremo a extremo con el endpoint de pruebas de la AEAT, usa el entorno de staging (api-staging.b2brouter.net).

Configuración y trabajo con la API de B2Brouter

El primer paso es configurar Verifactu para cada una de las empresas para las que quieras presentar informes fiscales. Puedes consultar la Guía de Tax Report Settings para una descripción completa del proceso. La llamada para configurar una cuenta es la siguiente:

Ejemplo de solicitud

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "Verifactu",
      "start_date": "2025-04-06",
      "auto_generate": true,
      "auto_send": true,
      "reason_vat_exempt": "E1",
      "special_regime_key": "01",
      "reason_no_subject": "N1",
      "credit_note_code": "R1"
    }
  }'

API de facturas

Si usas B2Brouter tanto para emitir facturas como para reportarlas a la Agencia Tributaria, una vez que hayas configurado correctamente tu cuenta, puedes operar como lo harías normalmente para emitir facturas.

Las facturas emitidas contendrán el código QR obligatorio, y el informe fiscal Verifactu se enviará automáticamente a la AEAT. Este es un ejemplo de llamada para crear y emitir una factura:

Ejemplo de solicitud:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/json' \
  --data '{
    "send_after_import": true,
    "invoice": {
      "date": "2025-04-15",
      "due_date": "2025-05-15",
      "number": 48,
      "payment_method": 1,
      "contact": {
        "name": "contact.name",
        "address": "contact.address",
        "city": "contact.city",
        "province": "contact.province",
        "postalcode": "28938",
        "country": "es",
        "email": "john.doe@example.com",
        "language": "es",
        "currency": "EUR",
        "terms": "15",
        "payment_method": 1,
        "tin_scheme": 9920,
        "tin_value": "ESA28388510"
      },
      "invoice_lines_attributes": [
        {
          "quantity": 10.0,
          "description": "line.description",
          "price": 11.0,
          "unit": 9,
          "taxes_attributes": [
            {
              "name": "IVA",
              "percent": 21.0,
              "category": "S"
            }
          ]
        }
      ]
    }
  }'

En la respuesta de la llamada REST POST para crear una factura, si send_after_import está establecido en true, encontrarás una sección tax_report_ids con el ID del informe fiscal asociado a la factura.

Puedes acceder al informe fiscal completo, incluido el código QR, su identificador, su estado y todos los demás campos, llamando al endpoint de obtención de informe fiscal con el ID del informe fiscal proporcionado en la respuesta de la llamada de creación de factura.

El estado del informe fiscal siempre será processing en la respuesta de la llamada POST. Debes verificar el ciclo de vida del informe fiscal. Tienes dos opciones:

La forma recomendada es usando el webhook de informe fiscal. Estados finales: registered, error y registered_with_errors
Consultar el estado del informe fiscal con el endpoint de obtención de informe fiscal hasta que el campo state sea registered, error o registered_with_errors.

API de informes fiscales

Si no usas B2Brouter para emitir facturas, necesitas más control sobre el proceso de generación y procesamiento de informes fiscales, o esperas un alto volumen de informes fiscales, puedes usar la nueva API de informes fiscales.

Esta API está diseñada para el máximo control por parte del usuario y alta disponibilidad. Puedes presentar informes fiscales como payload JSON o como XML válido de Verifactu.

La estructura del formato JSON para los informes fiscales de B2Brouter se basa en PEPPOL Continuous Transaction Control (CTC). La API de informes fiscales de B2Brouter es una API universal no solo orientada a Verifactu sino diseñada para gestionar el reporte fiscal en todo el mundo.

Es importante tener en cuenta que los informes fiscales tienen desgloses fiscales (“desglose” en español) que son la suma de las líneas de la factura original con el mismo impuesto. Es responsabilidad de tu sistema agregar las líneas de la factura por tipo y categoría fiscal y proporcionar los desgloses fiscales necesarios. El modelo TaxReport no realiza ningún cálculo.

Crear un informe fiscal

Para crear un informe fiscal debes llamar al endpoint crear informe fiscal. Un informe fiscal mínimo y válido:

Ejemplo de solicitud:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "Verifactu",
      "invoice_date": "2025-04-03",
      "invoice_number": "11",
      "description": "Lorem ipsum...",
      "customer_party_tax_id": "B12345678",
      "customer_party_country": "es",
      "customer_party_name": "Ejemplo S.L.",
      "tax_inclusive_amount": 121.0,
      "tax_amount": 21.0,
      "invoice_type_code": "F1",
      "currency": "EUR",
      "tax_breakdowns": [
        {
          "name": "IVA",
          "category": "S",
          "non_exemption_code": "S1",
          "percent": 21.0,
          "taxable_base": 100.0,
          "tax_amount": 21.0,
          "special_regime_key": "01"
        }
      ]
    }
  }'

La respuesta de esta llamada POST ya contendrá el campo qr con el código QR (codificado en base64) que debes incluir en la factura para tu cliente. El contenido de este código QR es una URL que permitirá a tu cliente verificar que la AEAT ha recibido y procesado el informe fiscal derivado de su factura.

Importar un informe fiscal desde un archivo XML de Verifactu

Si tu sistema es capaz de generar archivos XML de Verifactu (un RegistroAlta o un RegistroAnulacion del espacio de nombres SuministroInformacion), puedes importarlos directamente usando la API a través del endpoint de importación.

Si la creación del informe fiscal es exitosa, la respuesta ya contendrá el código QR y el identificador del informe fiscal. Ten en cuenta que B2Brouter realizará el proceso de encadenamiento independientemente de cualquier información de encadenamiento en el XML importado.

Verificar el estado de un informe fiscal

El campo state del informe fiscal siempre será processing tras una creación exitosa. Verifica el ciclo de vida mediante:

El webhook de informe fiscal. Estados finales: registered, error, annulled y registered_with_errors
Consultando el endpoint de obtención de informe fiscal hasta que el campo state sea alguno de: registered, error, annulled y registered_with_errors.

Obtener la representación XML del informe fiscal

Usa el endpoint de descarga del informe fiscal. B2Brouter también incluye un campo llamado xml_base64 en la respuesta GET. Ten en cuenta que el XML solo se puede generar después de que el informe fiscal haya sido encadenado.

Verificación de errores

B2Brouter ha implementado un exhaustivo conjunto de validaciones de los informes fiscales Verifactu basado en las especificaciones publicadas por la AEAT. Si hay un error de validación, el informe fiscal no se creará. Recibirás una respuesta 422: Unprocessable Entity con todos los errores en formato JSON.

Cancelar un informe fiscal

Para cancelar un informe fiscal (“anulación”) usa el verbo DELETE llamando al endpoint de anulación.

Corregir un informe fiscal

Para corregir un informe fiscal (“subsanación”) usa los verbos PATCH o PUT llamando al endpoint de corrección.

API de Ledgers

Los informes fiscales de Verifactu no se envían individualmente a la AEAT, sino que se agrupan en un “Libro de Registro” (Ledger en términos de B2Brouter) que contiene hasta 1.000 informes fiscales. Cada informe fiscal tiene un campo ledger_id que identifica el ID interno del ledger. Con ese ID puedes:

Recuperar la representación XML del Ledger llamando al endpoint de descarga del ledger.
Recuperar la respuesta XML de la AEAT al Ledger enviado por B2Brouter llamando al endpoint de descarga de la respuesta.

Equivalencia entre los campos internos del informe fiscal de B2Brouter y los nodos XML de Verifactu

Campo B2Brouter (basado en PEPPOL CTC)	Nodo XML Verifactu
invoice_date	IDFactura > FechaExpedicionFactura
invoice_number	IDFactura > NumSerieFactura
invoice_series_code	IDFactura > NumSerieFactura
supplier_party_name	NombreRazonEmisor
external_reference	RefExterna
correction	Subsanacion
annullation	Anulación
previously_refused	RechazoPrevio
invoice_type_code	TipoFactura
amend_type	TipoFactura
amended_number	FacturasRectificadas > IDFacturaRectificada > NumSerieFactura
amended_series_code	FacturasRectificadas > IDFacturaRectificada > NumSerieFactura
amended_date	FacturasRectificadas > IDFacturaRectificada > FechaExpedicionFactura
amended_tax_exclusive	ImporteRectificacion > BaseRectificada
amended_tax_amount	ImporteRectificacion > CuotaRectificada
tax_point_date	FechaOperacion
description	DescripcionOperacion
simplified_art7273	FacturaSimplificadaArt7273
ticket	FacturaSinIdentifDestinatarioArt61d
macrodata	Macrodato
issued_by_third_party_or_receiver	EmitidaPorTerceroODestinatario
third_party_name	Tercero > NombreRazon
third_party_tax_id	Tercero > NIF
customer_party_name	Destinatarios > IDDestinatario > NombreRazon
customer_party_tax_id	Destinatarios > IDDestinatario > NIF or IDOtro > IDType
customer_party_country	Destinatarios > IDDestinatario > IDOtro > CodigoPais
customer_party_tax_scheme	Destinatarios > IDDestinatario > IDOtro > IDType
tax_breakdowns[].name	Desglose > DetalleDesglose > Impuesto
tax_breakdowns[].special_regime_key	Desglose > DetalleDesglose > ClaveRegimen
tax_breakdowns[].non_exemption_code	Desglose > DetalleDesglose > CalificacionOperacion
tax_breakdowns[].exemption_code	Desglose > DetalleDesglose > OperacionExenta
tax_breakdowns[].percent	Desglose > DetalleDesglose > TipoImpositivo
tax_breakdowns[].taxable_base	Desglose > DetalleDesglose > BaseImponibleOimporteNoSujeto
tax_breakdowns[].taxable_base_at_cost	Desglose > DetalleDesglose > BaseImponibleACoste
tax_breakdowns[].tax_amount	Desglose > DetalleDesglose > CuotaRepercutida
tax_amount	CuotaTotal
tax_inclusive_amount	ImporteTotal
previous_id	Encadenamiento > RegistroAnterior > NumSerieFactura

Archivos XSD

Archivo XSD	Descripción
SuministroLR.xsd	Operaciones de alta y anulación de los sistemas Verifactu y no Verifactu
RespuestaSuministro.xsd	Respuesta de las operaciones de los sistemas Verifactu y no Verifactu
ConsultaLR.xsd	Operación de consulta de registros de facturación Verifactu
RespuestaConsultaLR.xsd	Respuesta de la operación de consulta de registros de facturación Verifactu
SuministroInformacion.xsd	Definición de tipos comunes

Descripciones de códigos para campos específicos

Códigos de tipo de factura

Parámetro: invoice_type_code

Código	Descripción
F1	Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)
F2	Factura Simplificada y Facturas sin identificación del destinatario (art. 6.1.d) RD 1619/2012
F3	Factura emitida en sustitución de facturas simplificadas facturadas y declaradas
R1	Factura Rectificativa (Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA)
R2	Factura Rectificativa (Art. 80.3)
R3	Factura Rectificativa (Art. 80.4)
R4	Factura Rectificativa (Resto)
R5	Factura Rectificativa en facturas simplificadas

Códigos de clave de régimen especial

Parámetro: special_regime_key

Código	Descripción
01	Operación de régimen general.
02	Exportación.
03	Operaciones a las que se aplique el régimen especial de bienes usados, objetos de arte, antigüedades y objetos de colección.
04	Régimen especial del oro de inversión.
05	Régimen especial de las agencias de viajes.
06	Régimen especial grupo de entidades en IVA (Nivel Avanzado)
07	Régimen especial del criterio de caja.
08	Operaciones sujetas al IPSI / IGIC.
17	Operación acogida a alguno de los regímenes previstos en el Capítulo XI del Título IX (OSS e IOSS)
18	Recargo de equivalencia.
19	Operaciones de actividades incluidas en el Régimen Especial de Agricultura, Ganadería y Pesca (REAGYP)
20	Régimen simplificado

Códigos de no exención

Parámetro: non_exemption_code

Código	Descripción
S1	Operación Sujeta y No exenta - Sin inversión del sujeto pasivo.
S2	Operación Sujeta y No exenta - Con Inversión del sujeto pasivo.

Códigos de no sujeción

Parámetro: no_subject_code

Código	Descripción
N1	Operación No Sujeta artículo 7, 14, otros.
N2	Operación No Sujeta por Reglas de localización.

Códigos de exención

Parámetro: exemption_code

Código	Descripción
E1	Exenta por el artículo 20
E2	Exenta por el artículo 21
E3	Exenta por el artículo 22
E4	Exenta por los artículos 23 y 24
E5	Exenta por el artículo 25
E6	Exenta por otros

Tipo de identificación del cliente

Parámetro: customer_party_tax_scheme

Código	Descripción
02	NIF-IVA de la UE
03	Pasaporte
04	Documento de identidad oficial emitido por el país de residencia
05	Certificado de residencia
06	Otro documento acreditativo
07	No registrado