SDI (FatturaPA)

L’SDI (Sistema di Interscambio) és la plataforma obligatòria de facturació electrònica d’Itàlia, gestionada per l’Agenzia delle Entrate. Totes les factures entre operadors italians —B2B, B2C i B2G— s’han d’emetre i rebre a través de l’SDI en format FatturaPA (el format XML estructurat nacional italià).

La REST API de B2Brouter s’encarrega de generar l’XML FatturaPA, transmetre’l a l’SDI i recuperar-ne els acusaments de recepció, de manera que la teva integració es pot centrar en la lògica de negoci.

Factura simplificada

Per a operacions de baix import (fins a 400 €) existeix un format XML reduït propi: vegeu la secció Fattura Semplificata més avall.

Què és l’SDI?

L’SDI és el punt d’accés central pel qual passen totes les factures electròniques italianes. En la pràctica:

• Les factures s’emeten en format FatturaPA 1.2 (xml.fatturapa.1.2), un XML propi italià.
• L’SDI valida el document contra l’esquema oficial (XSD) i el fa arribar al destinatari.
• Cada factura acceptada rep un identificador de registre (IdentificativoSdI).
• Si el destinatari no pot rebre el document electrònicament, l’SDI el diposita al seu cassetto fiscale.

L’obligatorietat aplica a totes les empreses italianes des del gener de 2019.

Identificació del destinatari

Per encaminar una factura, l’SDI necessita saber on l’ha d’entregar. Hi ha diverses vies, i és important no confondre-les:

Concepte	Camp a B2Brouter	Què és
Codice Destinatario	recipient_code	Codi d’encaminament assignat per l’SDI al destinatari. 7 caràcters per a empreses privades, 6 per a administracions públiques (Codice Ufficio).
PEC (Posta Elettronica Certificata)	certified_email	Correu electrònic certificat, alternativa al Codice Destinatario quan el destinatari no en té.
Codice Fiscale / Partita IVA	cin_value / tin_value	Identificació fiscal del destinatari (no és un codi d’encaminament).
CUP / CIG	file_reference (CUP) / lot_reference (CIG)	Codis de projecte i licitació obligatoris en certes operacions amb la P.A.; no serveixen per encaminar.

Codice Destinatario per defecte

Si el contacte italià no té Codice Destinatario ni PEC, B2Brouter fa servir automàticament 0000000 (7 zeros). L’SDI diposita llavors la factura al cassetto fiscale del comprador.

Si el comprador s’identifica per PEC (i no per Codice Destinatario), deixa recipient_code a 0000000 i informa l’adreça PEC a certified_email.

Per rebre factures a B2Brouter a través de l’SDI, el teu proveïdor ha d’indicar el Codice Destinatario de B2Brouter: EPKDZJB (prèvia registració de la teva empresa a l’Agenzia delle Entrate).

B2B, B2C i B2G

El flux tècnic és el mateix per als tres casos; el que canvia és la identificació del destinatari:

• B2B (empresa): identificada per la Partita IVA (tin_scheme: 9906). El recipient_code té 7 caràcters (o 0000000 si el client no en té).
• B2C (consumidor particular): identificat pel Codice Fiscale (cin_scheme: 9907). Normalment no té Codice Destinatario, així que s’usa 0000000 i l’SDI diposita la factura al cassetto fiscale del ciutadà. En factures exemptes pot aplicar-se el bollo.
• B2G (Administració pública): s’identifica amb el Codice Ufficio de 6 caràcters. Marca el contacte com a public_sector: true i informa el codi de 6 caràcters a recipient_code. Amb la P.A. sovint s’aplica l’split payment (vegeu Esigibilità IVA i split payment).

B2Brouter valida la longitud del codi (7 privat / 6 P.A.) en el moment de l’enviament.

Abans de començar

• Una empresa italiana amb Partita IVA vàlida i adreça completa (es validen en el moment d’enviar, no en crear el compte).
• Un compte a l’entorn de proves de B2Brouter: Registra’t aquí.
• Permisos d’API (sol·licita’ls obrint un tiquet de suport).

Versió d’API

A la capçalera X-B2B-API-Version fes servir sempre l’última versió disponible de l’API. Els exemples d’aquesta guia hi depenen (el nom d’alguns camps ha canviat entre versions).

Comença amb el sandbox per a les primeres proves de payload. Passa a staging (api-staging.b2brouter.net) quan vulguis provar l’enviament complet a l’SDI de proves.

Activar l’SDI

Perquè un compte pugui emetre a l’SDI, cal donar-lo d’alta amb un tax report setting de l’autoritat sdi. Consulta la Tax Report Settings Guide per al detall general.

curl --request POST \
  --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": "sdi"
    }
  }'

Resposta:

{
  "tax_report_setting": {
    "code": "sdi",
    "start_date": null,
    "auto_generate": true,
    "auto_send": true,
    "enabled": true,
    "locked": false
  }
}

En crear-lo, B2Brouter activa per defecte enabled, auto_generate i auto_send, de manera que les factures FatturaPA es generen i s’envien automàticament a l’SDI.

Crear l’empresa italiana

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "account": {
      "country": "it",
      "rounding_method": "half_up",
      "tin_value": "20339260422",
      "tin_scheme": 211,
      "name": "Test Sender Italy",
      "address": "Milano street, 1",
      "city": "Milano",
      "postalcode": "20019",
      "province": "MI",
      "email": "john.doe@example.com",
      "tax_regime": "RF01"
    }
  }'

El camp tax_regime indica el règim fiscal de l’emissor (vegeu Regime fiscale); si no s’informa, s’aplica RF01 (ordinari).

Crear el contacte de client

Quan crees un client italià:

• Fes servir tin_value per a la Partita IVA amb tin_scheme: 9906.
• Fes servir cin_value per al Codice Fiscale amb cin_scheme: 9907 (llista d’esquemes). N’hi ha prou amb un dels dos identificadors.
• L’adreça i el codi postal del contacte són obligatoris per enviar a l’SDI.
• transport_type_code ha de ser it.sdi.
• document_type_code ha de ser xml.fatturapa.1.2.
• Si el contacte té Codice Destinatario, informa’l a recipient_code (7 car. privat / 6 PA). Si no en té, es fa servir 0000000. Opcionalment, informa la PEC del comprador a certified_email.

Esquemes i província

El teu compte emissor identifica la Partita IVA amb tin_scheme: 211 (esquema numèric italià), però als contactes la Partita IVA va amb l’EAS de Peppol 9906 i el Codice Fiscale amb 9907. La province s’informa amb el codi de 2 lletres de la província (MI per Milà, RM per Roma…), no amb el nom sencer.

Noms de camp

Usa recipient_code i certified_email. Els àlies italians codice_destinatario i posta_elettronica_certificata només s’accepten a la versió d’API 2025-01-01; a partir de 2025-10-13 no es processen.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "contact": {
      "tin_scheme": "9906",
      "tin_value": "IT12345678901",
      "name": "Esempio S.r.l.",
      "address": "Via Inventata 88",
      "postalcode": "00184",
      "city": "Roma",
      "province": "RM",
      "country": "it",
      "transport_type_code": "it.sdi",
      "document_type_code": "xml.fatturapa.1.2",
      "recipient_code": "{CODICE_DESTINATARIO}"
    }
  }'

Crear i enviar una factura

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": {
      "type": "IssuedInvoice",
      "invoice_lines_attributes": [
        {
          "quantity": 10,
          "price": 47,
          "description": "Test Item",
          "taxes_attributes": [
            { "name": "IVA", "percent": 22 }
          ]
        }
      ],
      "number": "1",
      "date": "2025-01-22",
      "due_date": "2025-02-22",
      "contact_id": {YOUR_CONTACT_ID}
    }
  }'

Notes:

• El número de factura pot tenir com a màxim 20 caràcters.
• Cada línia ha de tenir descripció i com a mínim un impost.
• La due_date és opcional per al transport it.sdi.

send_after_import i auto_send

Són dues coses independents: send_after_import: true fa que la factura s’enviï en crear-la en comptes de quedar en esborrany; auto_send (al tax report setting de l’SDI) fa que el tax report SDI s’enviï automàticament quan s’envia la factura.

Camps addicionals per a factures italianes

• type_document (a la factura): fixa el TipoDocumento de FatturaPA. És opcional; si no l’informes, B2Brouter l’assigna automàticament. Vegeu Tipus de document.
• receipt_reference (a cada línia, no a la factura): referència a un rebut/scontrino associat a la línia, amb els camps identifier, number i date. Opcional, només FatturaPA:

"invoice_lines_attributes": [
  {
    "quantity": 1,
    "price": 47,
    "description": "Test Item",
    "taxes_attributes": [{ "name": "IVA", "percent": 22 }],
    "receipt_reference": {
      "identifier": "SCONTRINO-001",
      "number": "42",
      "date": "2025-01-20"
    }
  }
]

Tipus de document (TipoDocumento)

El TipoDocumento (type_document) classifica la factura (fattura, nota di credito, autofattura…). B2Brouter l’assigna automàticament segons el tipus i el contingut de la factura, però el pots forçar amb un codi vàlid (TD01–TD06, TD16–TD27).

Comportament:

• Si no informes type_document, s’assigna sol: TD01 per defecte, TD04 per a abonaments/rectificatives, TD16 quan hi ha impostos amb Natura N6, i TD17/TD18/TD19 per a autofactures (vegeu Autofattura).
• Si l’informes amb un codi vàlid, s’emet tal qual. Si el valor no és vàlid, s’ignora i s’aplica l’assignació automàtica (no es genera cap error).

Per veure com cada camp del JSON es correspon amb els nodes de l’XML FatturaPA, fes servir el mapador de camps de factura.

Natura IVA (operacions sense IVA)

Quan una operació no porta IVA (exempta, no imposable, reverse charge…), FatturaPA no fa servir un percentatge sinó un codi Natura (N1–N7). A B2Brouter s’informa a category dins de taxes_attributes, amb percent: 0:

"taxes_attributes": [
  { "name": "IVA", "percent": 0, "category": "N2.1" }
]

Codi	Significat
N1	Escloses ex art. 15
N2.1 / N2.2	No subjectes (art. 7-bis i altres)
N3.1–N3.6	No imposables (exportació, intracomunitària, San Marino…)
N4	Exemptes
N5	Règim del marge / IVA no exposta
N6.1–N6.9	Inversió comptable (reverse charge) — vegeu Autofattura
N7	IVA exigible en un altre estat de la UE

B2Brouter completa automàticament el motiu associat a cada codi Natura; només cal informar la category.

Usa els codis subdividits

Informa sempre el codi subdividit (N2.1, N3.2, N6.9…). Els codis genèrics N2, N3 i N6 estan obsolets des del 2021 i no s’accepten.

Regime fiscale

El règim fiscal de l’emissor s’informa al camp tax_regime del compte (empresa). Per defecte és RF01 (ordinari). Valors admesos:

Codi	Règim		Codi	Règim
RF01	Ordinario		RF12	Agriturismo
RF02	Contribuenti minimi		RF13	Vendite a domicilio
RF04	Agricoltura e pesca		RF14	Rivendita beni usati / oggetti d’arte
RF05	Vendita sali e tabacchi		RF15	Agenzie di vendite all’asta
RF06	Commercio fiammiferi		RF16	IVA per cassa P.A.
RF07	Editoria		RF17	IVA per cassa
RF08	Servizi telefonia pubblica		RF18	Altro
RF09	Documenti di trasporto/sosta		RF19	Regime forfettario
RF10	Intrattenimenti e giochi
RF11	Agenzie viaggi e turismo

Modalità di pagamento

La forma de pagament s’estableix amb el camp payment_method (al contacte o a la factura) i B2Brouter la tradueix al codi FatturaPA ModalitaPagamento (MPxx). Consulta la Payment Method Guide per als valors de payment_method.

Correspondències més habituals:

MP FatturaPA	Forma de pagament
MP01	Efectiu (contanti)
MP02	Xec (assegno)
MP05	Transferència bancària (bonifico)
MP06	Pagaré (vaglia cambiario)
MP08	Targeta de crèdit/dèbit

Nota

B2Brouter genera un subconjunt dels codis MP (no tots els MP01–MP23). Si necessites un codi concret que no es genera, contacta amb el suport.

Esigibilità IVA i split payment

L’esigibilità indica quan és exigible l’IVA. S’informa al camp vat_payability del contacte (per defecte I):

Valor	Significat
I	Immediata (per defecte)
D	Diferida (esigibilità differita)
S	Split payment (scissione dei pagamenti)

El valor S (split payment) s’aplica típicament en factures a la P.A.: el comprador ingressa l’IVA directament a l’erari, de manera que B2Brouter la descompta de l’import a pagar (el subtotal i l’IVA es mostren, però el payable_amount no inclou l’IVA).

Ritenuta d’acconto

Per als professionals subjectes a retenció (ritenuta d’acconto), informa a la factura amounts_withheld_reason (la causal de pagament) i l’import retingut. B2Brouter descompta l’import de l’import a pagar i genera el bloc DatiRitenuta a l’XML.

Tens dues maneres d’indicar l’import:

• amounts_withheld: l’import exacte a retenir. Recomanat quan la base de la retenció no és el total (p. ex. només la base imposable).
• withheld_percent: un percentatge que B2Brouter aplica sobre el total de la factura (IVA inclosa). Compte: si esperes la retenció sobre la base imposable, fes servir amounts_withheld.

{
  "invoice": {
    "type": "IssuedInvoice",
    "withheld_percent": 20,
    "amounts_withheld_reason": "A",
    "...": "..."
  }
}

Amb l’exemple anterior sobre una base amb IVA, la resposta retorna amounts_withheld calculat i el payable_amount reduït en aquest import.

Limitacions actuals

FatturaPA admet una sola retenció per factura. B2Brouter emet el tipus de ritenuta com a RT01 i la causal de pagament indicada.

Bollo

El bollo (imposta di bollo) és un segell de 2,00 € obligatori en factures sense IVA d’import superior a 77,47 €.

B2Brouter l’aplica automàticament quan es compleixen totes aquestes condicions:

• L’empresa té activada l’opció de bollo (apply_stamp_duty), que es configura a l’empresa (no per aquest API).
• L’emissor és italià i el total supera els 77,47 €.
• Hi ha almenys un impost amb una Natura d’exempció aplicable: N2.1, N2.2, N3.5, N3.6 o N4.
• El document no és d’integració/autofattura (TD16–TD19).

Quan s’aplica, l’XML inclou <DatiBollo> amb BolloVirtuale: SI i ImportoBollo: 2.00. També pots afegir-lo manualment com una línia amb descripció «bollo», preu 2 i impost N1 al 0 %.

Rectificatives

Per rectificar una factura ja emesa:

• Nota di credito (abonament): crea la factura amb is_credit_note: true. B2Brouter assigna TD04 automàticament.
• Nota di debito (càrrec addicional): informa type_document: "TD05".

Per vincular la factura original (perquè l’SDI relacioni els documents), afegeix una referència amb invoice_references de tipus amend, o informa amended_invoice_number i amended_invoice_date.

Nota

Una nota di credito creada amb is_credit_note: true genera el TipoDocumento TD04 en format FatturaPA 1.2.

Recepció de factures

Les factures dels teus proveïdors poden entrar a B2Brouter per diferents canals de recepció:

• SDI: registra el Codice Destinatario de B2Brouter (EPKDZJB) a l’Agenzia delle Entrate; els proveïdors italians emeten cap a aquest codi.
• Peppol o correu electrònic: activa el transport de recepció corresponent al compte per rebre proveïdors internacionals que emeten per aquestes vies.

Sigui quin sigui el canal, la factura entra com a factura rebuda (ReceivedInvoice). Les consultes: GET /accounts/{id}/received_invoices (llistar) i GET /received_invoices/{id} (obtenir).

Quan el proveïdor no ha passat per l’SDI (típicament un proveïdor estranger), la compra s’ha de declarar a l’SDI com a autofattura. Si has activat un transport de recepció, B2Brouter ho fa automàticament en arribar la factura; si les reps en un altre programari, les registres tu (via API) i s’integren igual. Vegeu la secció següent.

Autofattura i reverse charge

Quan compres a un proveïdor estranger (o en operacions de reverse charge intern), la normativa italiana obliga a autofacturar-te: declarar l’operació a l’SDI en nom teu.

A B2Brouter, l’autofattura no es crea com un document a part: es genera automàticament a partir de la factura rebuda. El flux és:

1. Assegura’t que el compte té l’SDI activat (amb auto_generate, que és el valor per defecte).
2. Aconsegueix la factura del proveïdor al compte com a factura rebuda: si tens un transport de recepció (Peppol/correu) actiu, hi entra sola; si la reps en un altre programari, registra-la via API amb POST /accounts/{id}/invoices i type: "ReceivedInvoice". Indica el type_operation (services o goods) i la Natura de l’IVA que correspongui (p. ex. N6.x per a reverse charge); el proveïdor va dins de l’objecte contact.
3. En crear-la, B2Brouter genera automàticament un tax report d’integració (l’autofattura), l’exporta en format FatturaPA i, si l’SDI té auto_send, l’envia. El pots consultar amb l’endpoint de tax reports.

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 '{
    "invoice": {
      "type": "ReceivedInvoice",
      "number": "RIC-001",
      "date": "2026-07-22",
      "type_operation": "services",
      "contact": {
        "tin_scheme": "9930",
        "tin_value": "DE137869841",
        "name": "Fornitore Estero GmbH",
        "address": "Berlin str 1",
        "postalcode": "10115",
        "city": "Berlin",
        "country": "de"
      },
      "invoice_lines_attributes": [
        {
          "quantity": 1,
          "price": 500,
          "description": "Consulenza estera",
          "taxes_attributes": [{ "name": "IVA", "percent": 0, "category": "N6.9" }]
        }
      ]
    }
  }'

El TipoDocumento de la integració es calcula automàticament:

Situació	Codi
Reverse charge intern (impostos amb Natura N6)	TD16
Compra de serveis a proveïdor no resident	TD17
Compra de béns intracomunitària	TD18
Compra de béns a proveïdor extra-UE	TD19

Com es tria el codi

La Natura N6 té prioritat: si una línia porta un impost amb categoria N6.x, s’emet TD16 sigui quin sigui el type_operation. Per obtenir TD17/TD18/TD19, registra la factura rebuda sense N6 —amb l’IVA italiana autoliquidada (p. ex. percent: 22)— i llavors el type_operation decideix: services → TD17, goods intracomunitari → TD18, goods extra-UE → TD19.

B2Brouter omple automàticament el bloc DatiFattureCollegate (referència a la factura rebuda) i marca el document com a autofattura (SoggettoEmittente: CC).

Fattura Semplificata

La Fattura Elettronica Semplificata (art. 21-bis del DPR 633/72) és un format XML reduït per a operacions de baix import: el total no pot superar els 400 €. És legalment equivalent a una factura ordinària, però utilitza una estructura pròpia (FatturaElettronicaSemplificata, versió FSM10) amb menys camps obligatoris —per exemple, no exporta dades de pagament—. Com qualsevol factura italiana, s’ha de presentar a l’SDI.

A B2Brouter es crea com una IssuedInvoice amb el tipus de document xml.fattura.semplificata.1.0.2 (a la factura o al contacte).

Regles de validació

Requisit	Valor
Total màxim de la factura	400 €
Identificador fiscal del comprador	Codice Fiscale o Partita IVA (obligatori un dels dos)
Adreça i codi postal del comprador	Obligatoris
IVA per línia	Exactament un impost per línia
Descomptes o càrrecs globals	No permesos (usa descomptes a nivell de línia)

Crear una factura simplificada

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": {
      "type": "IssuedInvoice",
      "document_type_code": "xml.fattura.semplificata.1.0.2",
      "number": "S-2025-001",
      "date": "2025-09-10",
      "contact_id": 123456789,
      "invoice_lines_attributes": [
        {
          "quantity": 2,
          "price": 50.00,
          "description": "Servizi di consulenza",
          "taxes_attributes": [{ "name": "IVA", "percent": 22 }]
        }
      ]
    }
  }'

Tipus de document (TipoDocumento)

Per al format simplificat, B2Brouter assigna el TipoDocumento automàticament; no informis type_document:

• TD07 — Fattura Semplificata (per defecte).
• TD08 — Nota di Credito Semplificata (quan is_credit_note: true o rectificativa).

Si hi poses un codi vàlid de la FatturaPA ordinària (TD01–TD06, TD16–TD27), s’emetrà tal qual dins l’XML simplificat i l’SDI el rebutjarà (error XSD), perquè el format simplificat només admet TD07, TD08 i TD09. El TD09 (Nota di Debito Semplificata) no està suportat actualment.

Nota

El format simplificat no exporta dades de pagament: due_date, payment_method, etc. s’accepten a l’API però no apareixen a l’XML.

Comprovar l’estat de la factura

Amb send_after_import: true, la factura s’envia a l’SDI pel transport it.sdi i passa per sending → sent. Si l’SDI (o el destinatari) la rebutja, passa a error amb el detall del motiu. Quan l’SDI retorna l’identificador de registre (IdentificativoSdI), queda disponible a to_net_id.

Emeses vs. autofactures

Les factures emeses no generen cap tax report: l’enviament a l’SDI és el transport mateix. En canvi, les autofactures generades des de factures rebudes sí que són tax reports (vegeu Autofattura) i es consulten amb l’endpoint de tax reports.

Opció 1: consultar una factura

curl --request GET \
  --url 'https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Opció 2: consultar diverses factures

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Quan la factura arribi a l’estat final, marca-la com a reconeguda per treure-la de la llista activa:

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/ack \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Recursos addicionals

B2Brouter

• Mapador de camps de factura (FatturaPA)
• Payment Method Guide
• Referència de l’API

Documentació oficial (Agenzia delle Entrate)

• Formato FatturaPA — esquemes XSD, fulls XSLT i especificacions
• Documentació del Sistema di Interscambio (SDI)
• Especificacions tècniques del format (Agenzia delle Entrate)