Verifactu
La Llei antifrau (Llei 11/2021) estableix que les empreses han de garantir que els seus sistemes de facturació i comptabilitat compleixin estàndards tècnics estrictes per evitar la manipulació de dades. El Reial decret 1007/2023 defineix més detalladament els requisits tècnics dels sistemes digitals de facturació i posa l’accent en la necessitat de formats de factura estandarditzats que puguin ser consultats fàcilment per l’Administració tributària.
Aquesta normativa obliga les empreses a adoptar sistemes capaços de generar, emmagatzemar i transmetre factures i tax reports de manera segura. La REST API de B2Brouter és una solució tècnica que permet que la teva empresa sigui fàcilment 100% compliant, delegant la complexitat a B2Brouter i deixant-te centrar en la lògica de negoci del teu sistema.
Què és Verifactu?
Section titled “Què és Verifactu?”Verifactu és un sistema de compliment normatiu dissenyat per simplificar el procés d’adaptació als requisits de facturació establerts per la Llei antifrau. Garanteix que totes les factures generades per les empreses es transmetin de manera segura a l’Administració tributària perquè en verifiqui la integritat i autenticitat, tant per part de l’Administració tributària com del client. L’Administració tributària espanyola és l’AEAT (“Agencia Estatal de Administración Tributaria”).
Verifactu implica l’enviament immediat i en temps real de les dades de factura a l’AEAT tan bon punt la factura s’emet. Això garanteix que no es puguin fer modificacions un cop la factura ja està emesa, assegurant-ne la seguretat. A més, la factura conté un codi QR que permet al destinatari verificar-ne el compliment fiscal a través de la plataforma de l’AEAT.
En la pràctica, Verifactu requereix:
- Crear un fitxer XML de tax report.
- Calcular una empremta digital per a cada tax report. Això inclou una cadena hash per crear una traça immutable.
- Construir un “Libro de Registro” o Ledger que pot incloure un o diversos tax reports.
- Fer un enviament autenticat del “Libro de Registro” a l’AEAT utilitzant un certificat electrònic qualificat.
- Respectar el rate limit establert per l’AEAT, amb un màxim d’1 crida per minut, tret que s’enviïn més de 1.000 factures.
- Generar un codi QR per a la verificació de la factura, que s’ha d’incloure a la factura emesa.
- Processar les respostes de l’AEAT per a cada tax report.
Amb B2Brouter pots abstraure bona part de la complexitat d’aquest procés i complir la Llei antifrau fent només unes poques crides REST a l’API. No et caldrà tenir el teu propi certificat electrònic qualificat perquè B2Brouter és col·laborador social en la gestió tributària. Només necessites una API Key vàlida de B2Brouter.
Entorns de prova: utilitza sandbox per a les primeres proves d’API i validació de payloads. El sandbox simula els enviaments Verifactu perquè puguis provar el cicle de vida de la factura sense connectar amb l’AEAT. Per fer proves completes end-to-end amb l’endpoint de proves de l’AEAT, utilitza l’entorn staging (
api-staging.b2brouter.net).
Configuració i treball amb l’API de B2Brouter
Section titled “Configuració i treball amb l’API de B2Brouter”El primer pas és configurar Verifactu per a cadascuna de les empreses per a les quals vulguis enviar tax reports. Pots consultar la Tax Report Settings Guide per a una descripció completa del procés. La crida per configurar un compte és la següent:
Exemple de petició
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" } }'Invoice API
Section titled “Invoice API”Si utilitzes B2Brouter tant per emetre factures com per informar-ne a l’Administració tributària, un cop hagis configurat correctament el teu compte, podràs operar de la manera habitual per emetre factures.
Les factures emeses contindran el codi QR obligatori i el tax report Verifactu s’enviarà automàticament a l’AEAT. Aquest és un exemple de crida per crear i emetre una factura:
Exemple de petició:
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" } ] } ] } }'A la resposta de la crida REST POST per crear una factura, si send_after_import està establert a true, trobaràs una secció tax_report_ids on hi haurà l’ID del tax report associat a la factura.
Pots accedir al tax report complet, incloent-hi el codi QR, l’identificador, l’estat i la resta de camps, cridant el get tax report endpoint amb l’ID retornat a la resposta de la creació de factura.
L’estat del tax report sempre serà processing a la resposta del POST. Has de comprovar el cicle de vida del tax report. Tens dues opcions:
- La manera recomanada és utilitzar el tax report web hook. Estats finals: registered, error i registered_with_errors
- Fer polling de l’estat del tax report amb el get tax report endpoint fins que el camp state sigui registered, error o registered_with_errors
Tax Report API
Section titled “Tax Report API”Si no utilitzes B2Brouter per emetre factures, necessites més control sobre el procés de generació i tractament de tax reports, o esperes un volum alt de tax reports, pots utilitzar la nova Tax Report API.
Aquesta API està dissenyada per oferir el màxim control a l’usuari i alta disponibilitat. Pots enviar tax reports tant en format JSON com en format XML Verifactu vàlid.
L’estructura del format JSON per als tax reports de B2Brouter es basa en PEPPOL Continuous Transaction Control (CTC). La Tax Report API de B2Brouter és una API universal no només orientada a Verifactu, sinó pensada per gestionar tax reporting arreu del món.
És important remarcar que els tax reports tenen tax breakdowns (“desglose” en castellà), que són la suma de les línies de la factura original amb el mateix impost. És responsabilitat del teu sistema agrupar les línies de factura per tipus i categoria fiscal i proporcionar els tax breakdowns necessaris. El model TaxReport no fa càlculs.
Crear un tax report
Section titled “Crear un tax report”Per crear un tax report has de cridar l’endpoint create tax report. Un tax report mínim i vàlid:
Exemple de petició:
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 resposta d’aquesta crida POST ja contindrà el camp qr amb el codi QR codificat en base64 que has d’incloure a la factura del client. El contingut d’aquest QR és una URL que permetrà al client comprovar que l’AEAT ha rebut i processat el tax report derivat de la seva factura.
Importar un tax report des d’un fitxer XML Verifactu
Section titled “Importar un tax report des d’un fitxer XML Verifactu”Si el teu sistema és capaç de generar fitxers XML Verifactu, com ara un RegistroAlta o un RegistroAnulacion del namespace SuministroInformacion, els pots importar directament a través de l’API mitjançant l’import endpoint.
Si la creació del Tax Report és correcta, la resposta ja contindrà el codi QR i l’identificador del Tax Report. Tingues en compte que B2Brouter farà el procés d’encadenament independentment de qualsevol informació d’encadenament que hi hagi a l’XML importat.
Comprovar l’estat d’un tax report
Section titled “Comprovar l’estat d’un tax report”El camp state del tax report sempre serà processing després d’una creació correcta. Comprova’n el cicle de vida mitjançant:
- El tax report web hook. Estats finals: registered, error, annulled i registered_with_errors
- El polling del get tax report endpoint fins que el camp state sigui un de: registered, error, annulled i registered_with_errors
Obtenir la representació XML del tax report
Section titled “Obtenir la representació XML del tax report”Utilitza el download tax report endpoint. B2Brouter també inclou un camp anomenat xml_base64 a la resposta del GET. Tingues en compte que l’XML només es pot generar després que el tax report hagi estat encadenat.
Comprovació d’errors
Section titled “Comprovació d’errors”B2Brouter ha implementat un conjunt exhaustiu de validacions dels tax reports Verifactu basades en les especificacions publicades per l’AEAT. Si hi ha un error de validació, el tax report no es crearà. Rebràs una resposta 422: Unprocessable Entity amb tots els errors en format JSON.
Anul·lar un tax report
Section titled “Anul·lar un tax report”Per anul·lar un tax report (“anulación” en castellà), utilitza el verb DELETE cridant l’annullation endpoint.
Corregir un tax report
Section titled “Corregir un tax report”Per corregir un tax report (“subsanación” en castellà), utilitza els verbs PATCH o PUT cridant el correction endpoint.
Ledgers API
Section titled “Ledgers API”Els tax reports Verifactu no s’envien individualment a l’AEAT, sinó agrupats en un “Libro de Registro” (Ledger en la terminologia de B2Brouter), que conté fins a 1000 tax reports. Cada tax report té un camp ledger_id que identifica l’ID intern del ledger. Amb aquest ID pots:
- Recuperar la representació XML del Ledger cridant el download ledger endpoint
- Recuperar la resposta XML de l’AEAT al Ledger enviat per B2Brouter cridant el download response endpoint
Equivalència entre els camps interns de tax report de B2Brouter i els nodes XML de Verifactu
Section titled “Equivalència entre els camps interns de tax report de B2Brouter i els nodes XML de Verifactu”| Camp de B2Brouter (basat en PEPPOL CTC) | Node XML de 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 o 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 |
Fitxers XSD
Section titled “Fitxers XSD”| Fitxer XSD | Descripció |
|---|---|
| SuministroLR.xsd | Operacions d’alta i anul·lació dels sistemes Verifactu i no Verifactu |
| RespuestaSuministro.xsd | Resposta de les operacions dels sistemes Verifactu i no Verifactu |
| ConsultaLR.xsd | Operació de consulta de registres de facturació Verifactu |
| RespuestaConsultaLR.xsd | Resposta de l’operació de consulta de registres de facturació Verifactu |
| SuministroInformacion.xsd | Definició de tipus comuns |
Descripcions de codis per a camps específics
Section titled “Descripcions de codis per a camps específics”Codis de tipus de factura
Section titled “Codis de tipus de factura”Paràmetre: invoice_type_code
| Codi | Descripció |
|---|---|
| F1 | Factura (art. 6, 7.2 i 7.3 del RD 1619/2012) |
| F2 | Factura simplificada i factures sense identificació del destinatari (art. 6.1.d) RD 1619/2012 |
| F3 | Factura emesa en substitució de factures simplificades facturades i declarades |
| R1 | Factura rectificativa (error fonamentat en dret i art. 80 u, dos i sis LIVA) |
| R2 | Factura rectificativa (art. 80.3) |
| R3 | Factura rectificativa (art. 80.4) |
| R4 | Factura rectificativa (resta de casos) |
| R5 | Factura rectificativa en factures simplificades |
Codis de clau de règim especial
Section titled “Codis de clau de règim especial”Paràmetre: special_regime_key
| Codi | Descripció |
|---|---|
| 01 | Operació de règim general |
| 02 | Exportació |
| 03 | Operacions a què s’aplica el règim especial de béns usats, objectes d’art, antiguitats i objectes de col·lecció |
| 04 | Règim especial de l’or d’inversió |
| 05 | Règim especial de les agències de viatges |
| 06 | Règim especial de grup d’entitats en IVA (nivell avançat) |
| 07 | Règim especial del criteri de caixa |
| 08 | Operacions subjectes a IPSI / IGIC |
| 17 | Operació acollida a algun dels règims previstos al capítol XI del títol IX (OSS i IOSS) |
| 18 | Recàrrec d’equivalència |
| 19 | Operacions d’activitats incloses en el règim especial d’agricultura, ramaderia i pesca (REAGYP) |
| 20 | Règim simplificat |
Codis de no exempció
Section titled “Codis de no exempció”Paràmetre: non_exemption_code
| Codi | Descripció |
|---|---|
| S1 | Operació subjecta i no exempta, sense inversió del subjecte passiu |
| S2 | Operació subjecta i no exempta, amb inversió del subjecte passiu |
Codis de no subjecció
Section titled “Codis de no subjecció”Paràmetre: no_subject_code
| Codi | Descripció |
|---|---|
| N1 | Operació no subjecta article 7, 14, altres |
| N2 | Operació no subjecta per regles de localització |
Codis d’exempció
Section titled “Codis d’exempció”Paràmetre: exemption_code
| Codi | Descripció |
|---|---|
| E1 | Exempta per l’article 20 |
| E2 | Exempta per l’article 21 |
| E3 | Exempta per l’article 22 |
| E4 | Exempta pels articles 23 i 24 |
| E5 | Exempta per l’article 25 |
| E6 | Exempta per altres |
Tipus d’identificador del client
Section titled “Tipus d’identificador del client”Paràmetre: customer_party_tax_scheme
| Codi | Descripció |
|---|---|
| 02 | EU VAT ID (NIF-IVA) |
| 03 | Passaport |
| 04 | Identificador oficial emès pel país de residència |
| 05 | Certificat de residència |
| 06 | Altre document acreditatiu |
| 07 | No registrat |