SDI (FatturaPA)

The SDI (Sistema di Interscambio) is Italy’s mandatory e-invoicing platform, run by the Agenzia delle Entrate. All invoices between Italian operators —B2B, B2C and B2G— must be issued and received through the SDI in FatturaPA format (the Italian national structured XML format).

B2Brouter’s REST API generates the FatturaPA XML, transmits it to the SDI and retrieves the acknowledgements, so your integration can focus on business logic.

Simplified invoice

For low-value transactions (up to €400) there is a separate reduced XML format: see the Fattura Semplificata section below.

What is the SDI?

The SDI is the central hub every Italian electronic invoice passes through. In practice:

• Invoices are issued in FatturaPA 1.2 format (xml.fatturapa.1.2), an Italian XML format.
• The SDI validates the document against the official schema (XSD) and delivers it to the recipient.
• Each accepted invoice receives a registration identifier (IdentificativoSdI).
• If the recipient cannot receive the document electronically, the SDI makes it available in their cassetto fiscale.

E-invoicing has been mandatory for all Italian companies since January 2019.

Recipient identification

To route an invoice, the SDI needs to know where to deliver it. There are several ways, and it is important not to confuse them:

Concept	Field in B2Brouter	What it is
Codice Destinatario	recipient_code	Routing code assigned by the SDI to the recipient. 7 characters for private companies, 6 for public administrations (Codice Ufficio).
PEC (Posta Elettronica Certificata)	certified_email	Certified email, an alternative to the Codice Destinatario when the recipient does not have one.
Codice Fiscale / Partita IVA	cin_value / tin_value	The recipient’s tax identifier (not a routing code).
CUP / CIG	file_reference (CUP) / lot_reference (CIG)	Project and tender codes required in certain operations with the public sector; they do not route the invoice.

Default Codice Destinatario

If the Italian contact has neither a Codice Destinatario nor a PEC, B2Brouter automatically uses 0000000 (seven zeros). The SDI then makes the invoice available in the buyer’s cassetto fiscale.

If the buyer is identified by PEC (and not by a Codice Destinatario), leave recipient_code as 0000000 and set the PEC address in certified_email.

To receive invoices in B2Brouter through the SDI, your supplier must use B2Brouter’s Codice Destinatario: EPKDZJB (after registering your company with the Agenzia delle Entrate).

B2B, B2C and B2G

The technical flow is the same in all three cases; what changes is the recipient’s identification:

• B2B (company): identified by the Partita IVA (tin_scheme: 9906). The recipient_code is 7 characters (or 0000000 if the customer does not have one).
• B2C (private consumer): identified by the Codice Fiscale (cin_scheme: 9907). They usually have no Codice Destinatario, so 0000000 is used and the SDI makes the invoice available in the citizen’s cassetto fiscale. On exempt invoices the bollo may apply.
• B2G (public administration): identified by the Codice Ufficio, 6 characters. Mark the contact as public_sector: true and set the 6-character code in recipient_code. With the public sector, split payment often applies (see Esigibilità IVA and split payment).

B2Brouter validates the code length (7 private / 6 public sector) at send time.

Before you start

• An Italian company with a valid Partita IVA and a complete address (validated at send time, not when the account is created).
• A B2Brouter test account: Register here.
• API permissions (request them by opening a support ticket).

API version

In the X-B2B-API-Version header, always use the latest available version of the API. The examples in this guide depend on it (some field names have changed between versions).

Start with the sandbox for your first payload tests. Move to staging (api-staging.b2brouter.net) when you want to test the full submission to the SDI test environment.

Enabling the SDI

For an account to issue to the SDI, it must be enabled with a tax report setting for the sdi authority. See the Tax Report Settings Guide for the general details.

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"
    }
  }'

Response:

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

On creation, B2Brouter enables enabled, auto_generate and auto_send by default, so FatturaPA invoices are generated and sent to the SDI automatically.

Create the Italian company

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"
    }
  }'

The tax_regime field states the issuer’s tax regime (see Regime fiscale); if omitted, RF01 (ordinary) is applied.

Create the customer contact

When you create an Italian customer:

• Use tin_value for the Partita IVA with tin_scheme: 9906.
• Use cin_value for the Codice Fiscale with cin_scheme: 9907 (scheme list). One of the two identifiers is enough.
• The contact’s address and postal code are required to send to the SDI.
• transport_type_code must be it.sdi.
• document_type_code must be xml.fatturapa.1.2.
• If the contact has a Codice Destinatario, set it in recipient_code (7 chars private / 6 public sector). If not, 0000000 is used. Optionally, set the buyer’s PEC in certified_email.

Schemes and province

Your issuing account identifies the Partita IVA with tin_scheme: 211 (Italian numeric scheme), whereas on contacts the Partita IVA uses the Peppol EAS 9906 and the Codice Fiscale uses 9907. The province must be the 2-letter code of the province (MI for Milano, RM for Roma…), not the full name.

Field names

Use recipient_code and certified_email. The Italian aliases codice_destinatario and posta_elettronica_certificata are only accepted in API version 2025-01-01; from 2025-10-13 onwards they are not processed.

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}"
    }
  }'

Create and send an invoice

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:

• The invoice number can be at most 20 characters.
• Each line must have a description and at least one tax.
• due_date is optional for the it.sdi transport.

send_after_import and auto_send

These are two independent things: send_after_import: true makes the invoice be sent when it is created instead of staying as a draft; auto_send (on the SDI tax report setting) makes the SDI tax report be sent automatically when the invoice is sent.

Additional fields for Italian invoices

• type_document (on the invoice): sets the FatturaPA TipoDocumento. Optional; if omitted, B2Brouter assigns it automatically. See Document type.
• receipt_reference (on each line, not on the invoice): reference to a receipt/scontrino linked to the line, with the fields identifier, number and date. Optional, FatturaPA only:

"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"
    }
  }
]

Document type (TipoDocumento)

The TipoDocumento (type_document) classifies the invoice (fattura, nota di credito, autofattura…). B2Brouter assigns it automatically based on the invoice type and content, but you can force it with a valid code (TD01–TD06, TD16–TD27).

Behavior:

• If you do not set type_document, it is assigned automatically: TD01 by default, TD04 for credit notes/amendments, TD16 when there are taxes with Natura N6, and TD17/TD18/TD19 for self-invoices (see Autofattura).
• If you set it with a valid code, it is emitted as-is. If the value is not valid, it is ignored and the automatic assignment applies (no error is raised).

To see how each JSON field maps to the FatturaPA XML nodes, use the invoice field mapper.

VAT nature codes (Natura)

When an operation carries no VAT (exempt, non-taxable, reverse charge…), FatturaPA does not use a percentage but a Natura code (N1–N7). In B2Brouter it is set in category inside taxes_attributes, with percent: 0:

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

Code	Meaning
N1	Excluded pursuant to art. 15
N2.1 / N2.2	Not subject (art. 7-bis and others)
N3.1–N3.6	Non-taxable (exports, intra-EU supplies, San Marino…)
N4	Exempt
N5	Margin scheme / VAT not shown
N6.1–N6.9	Reverse charge (inversione contabile) — see Autofattura
N7	VAT chargeable in another EU state

B2Brouter fills in the reason associated with each Natura code automatically; you only need to set the category.

Use the subdivided codes

Always use the subdivided code (N2.1, N3.2, N6.9…). The generic codes N2, N3 and N6 have been deprecated since 2021 and are not accepted.

Regime fiscale

The issuer’s tax regime is set in the account’s tax_regime field. The default is RF01 (ordinary). Accepted values:

Code	Regime		Code	Regime
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

The payment method is set with the payment_method field (on the contact or the invoice) and B2Brouter maps it to the FatturaPA ModalitaPagamento code (MPxx). See the Payment Method Guide for the payment_method values.

Most common mappings:

MP FatturaPA	Payment method
MP01	Cash (contanti)
MP02	Cheque (assegno)
MP05	Bank transfer (bonifico)
MP06	Promissory note (vaglia cambiario)
MP08	Credit/debit card

Note

B2Brouter generates a subset of the MP codes (not all of MP01–MP23). If you need a specific code that is not generated, contact support.

Esigibilità IVA and split payment

Esigibilità indicates when the VAT becomes due. It is set in the vat_payability field of the contact (default I):

Value	Meaning
I	Immediate (default)
D	Deferred (esigibilità differita)
S	Split payment (scissione dei pagamenti)

The value S (split payment) typically applies to invoices to the public sector: the buyer pays the VAT directly to the tax authority, so B2Brouter deducts it from the amount due (the subtotal and the VAT are shown, but the payable_amount does not include the VAT).

Ritenuta d’acconto

For professionals subject to withholding (ritenuta d’acconto), set amounts_withheld_reason (the payment reason) and the withheld amount on the invoice. B2Brouter deducts the amount from the amount due and generates the DatiRitenuta block in the XML.

There are two ways to state the amount:

• amounts_withheld: the exact amount to withhold. Recommended when the withholding base is not the total (for example, only the taxable base).
• withheld_percent: a percentage that B2Brouter applies to the invoice total (VAT included). Note: if you expect the withholding on the taxable base, use amounts_withheld.

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

With the example above on a base with VAT, the response returns the computed amounts_withheld and the payable_amount reduced by that amount.

Current limitations

FatturaPA supports a single withholding per invoice. B2Brouter emits the withholding type as RT01 and the stated payment reason.

Bollo

The bollo (imposta di bollo) is a €2.00 stamp duty required on VAT-free invoices exceeding €77.47.

B2Brouter applies it automatically when all of these conditions are met:

• The company has the bollo option enabled (apply_stamp_duty), which is configured on the company (not through this API).
• The issuer is Italian and the total exceeds €77.47.
• There is at least one tax with an applicable exemption Natura: N2.1, N2.2, N3.5, N3.6 or N4.
• The document is not an integration/self-invoice (TD16–TD19).

When it applies, the XML includes <DatiBollo> with BolloVirtuale: SI and ImportoBollo: 2.00. You can also add it manually as a line with the description “bollo”, price 2 and tax N1 at 0%.

Credit and debit notes

To correct an invoice that has already been issued:

• Nota di credito (credit note): create the invoice with is_credit_note: true. B2Brouter assigns TD04 automatically.
• Nota di debito (debit note): set type_document: "TD05".

To link the original invoice (so the SDI relates the documents), add a reference with invoice_references of type amend, or set amended_invoice_number and amended_invoice_date.

Note

A nota di credito created with is_credit_note: true generates the TipoDocumento TD04 in FatturaPA 1.2 format.

Receiving invoices

Your suppliers’ invoices can reach B2Brouter through different reception channels:

• SDI: register B2Brouter’s Codice Destinatario (EPKDZJB) with the Agenzia delle Entrate; Italian suppliers issue towards this code.
• Peppol or email: enable the corresponding reception transport on the account to receive international suppliers that issue through those channels.

Whatever the channel, the invoice enters as a received invoice (ReceivedInvoice). To query them: GET /accounts/{id}/received_invoices (list) and GET /received_invoices/{id} (get).

When the supplier has not gone through the SDI (typically a foreign supplier), the purchase must be declared to the SDI as an autofattura. If you have a reception transport enabled, B2Brouter does it automatically when the invoice arrives; if you receive them in other software, you register them yourself (via the API) and they are integrated all the same. See the next section.

Autofattura and reverse charge

When you buy from a foreign supplier (or in internal reverse charge operations), Italian law requires you to self-invoice: declare the operation to the SDI on your own behalf.

In B2Brouter, the autofattura is not created as a separate document: it is generated automatically from the received invoice. The flow is:

1. Make sure the account has the SDI enabled (with auto_generate, which is the default).
2. Get the supplier’s invoice into the account as a received invoice: if you have a reception transport (Peppol/email) enabled, it arrives on its own; if you receive it in other software, register it via the API with POST /accounts/{id}/invoices and type: "ReceivedInvoice". Set the type_operation (services or goods) and the appropriate VAT Natura (e.g. N6.x for reverse charge); the supplier goes inside the contact object.
3. On creation, B2Brouter automatically generates an integration tax report (the autofattura), exports it in FatturaPA format and, if the SDI has auto_send, sends it. You can query it with the tax reports endpoint.

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" }]
        }
      ]
    }
  }'

The integration’s TipoDocumento is computed automatically:

Situation	Code
Internal reverse charge (taxes with Natura N6)	TD16
Purchase of services from a non-resident supplier	TD17
Intra-EU purchase of goods	TD18
Purchase of goods from an extra-EU supplier	TD19

How the code is chosen

Natura N6 takes priority: if a line carries a tax with category N6.x, TD16 is emitted regardless of type_operation. To get TD17/TD18/TD19, register the received invoice without N6 —with the self-assessed Italian VAT (e.g. percent: 22)— and then type_operation decides: services → TD17, intra-EU goods → TD18, extra-EU goods → TD19.

B2Brouter automatically fills in the DatiFattureCollegate block (reference to the received invoice) and marks the document as a self-invoice (SoggettoEmittente: CC).

Fattura Semplificata

The Fattura Elettronica Semplificata (art. 21-bis of DPR 633/72) is a reduced XML format for low-value transactions: the total cannot exceed €400. It is legally equivalent to an ordinary invoice, but uses its own structure (FatturaElettronicaSemplificata, version FSM10) with fewer required fields —for example, it does not export payment data—. Like any Italian invoice, it must be submitted to the SDI.

In B2Brouter it is created as an IssuedInvoice with the document type xml.fattura.semplificata.1.0.2 (on the invoice or the contact).

Validation rules

Requirement	Value
Maximum invoice total	€400
Buyer’s tax identifier	Codice Fiscale or Partita IVA (one of the two required)
Buyer’s address and postal code	Required
VAT per line	Exactly one tax per line
Global discounts or charges	Not allowed (use line-level discounts)

Create a simplified invoice

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 }]
        }
      ]
    }
  }'

Document type (TipoDocumento)

For the simplified format, B2Brouter assigns the TipoDocumento automatically; do not set type_document:

• TD07 — Fattura Semplificata (default).
• TD08 — Nota di Credito Semplificata (when is_credit_note: true or an amendment).

If you set a valid code from the ordinary FatturaPA (TD01–TD06, TD16–TD27), it will be emitted as-is inside the simplified XML and the SDI will reject it (XSD error), because the simplified format only accepts TD07, TD08 and TD09. TD09 (Nota di Debito Semplificata) is not currently supported.

Note

The simplified format does not export payment data: due_date, payment_method, etc. are accepted by the API but do not appear in the XML.

Checking the invoice status

With send_after_import: true, the invoice is sent to the SDI through the it.sdi transport and goes through sending → sent. If the SDI (or the recipient) rejects it, it moves to error with the reason. When the SDI returns the registration identifier (IdentificativoSdI), it becomes available in to_net_id.

Issued vs. self-invoices

Issued invoices do not generate any tax report: the submission to the SDI is the transport itself. Self-invoices generated from received invoices, on the other hand, are tax reports (see Autofattura) and are queried with the tax reports endpoint.

Option 1: query a single invoice

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'

Option 2: query several invoices

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'

When the invoice reaches its final state, mark it as acknowledged to remove it from the active list:

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'

Additional resources

B2Brouter

• Invoice field mapper (FatturaPA)
• Payment Method Guide
• API Reference

Official documentation (Agenzia delle Entrate)

• FatturaPA format — XSD schemas, XSLT stylesheets and specifications
• Sistema di Interscambio (SDI) documentation
• Technical specifications of the format (Agenzia delle Entrate)