Italian Invoice Submission via SDI with B2Brouter

Introduction

This guide explains how to send invoices to the SDI (Il Sistema di Interscambio) with an Italian company through the B2Brouter API.

The SDI is the central invoicing access point managed by the Agenzia delle Entrate, and all invoices must be sent through this system in the FatturaPA 1.2 format.

Prerequisites

An Italian company with a valid Partita IVA.
A registered account on B2Brouter’s test environment: Register Here
API permissions (Request via a support ticket: Open a Ticket)

In case of doubt about the registration process, please refer to the [User Guide].

Obtaining API Credentials

Once permissions are granted:

Log in to your B2Brouter account.
Navigate to the Integration menu (lightning bolt icon).
Select B2Brouter API.
Click Show API Key to retrieve your API key.

Creating an Italian Company Account

If you already have an API key, you can directly create an Italian company using the API:

Request Example:

curl --request POST
--url https://app-staging.b2brouter.net/accounts
--header 'X-B2B-API-Key: YOUR_API_KEY'
--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": "Milano",
    "email": "helpdesk@b2brouter.net"
  }
}'

Sample Response:

{
    "account": {
        "id": 73132,
        "tin_value": "IT20339260422",
        "tin_scheme": 211,
        "cin_value": null,
        "cin_scheme": null,
        "name": "Test Sender Italy",
        "address": "Milano street, 1",
        "address2": null,
        "city": "Milano",
        "postalcode": "20019",
        "province": "Milano",
        "country": "it",
        "currency": "EUR",
        "contact_person": null,
        "phone": null,
        "email": "helpdesk@b2brouter.net",
        "rounding_method": "half_up",
        "round_before_sum": false,
        "apply_taxes_per_line": false,
        "archived": false,
        "created_at": "2025-01-22T16:02:34.000Z",
        "updated_at": "2025-01-22T16:02:34.000Z"
    }
}

Creating a Customer Contact

Once we got our company set up, we can start by creating the contacts that we will later invoice.

When creating an Italian customer, consider whether they will be registered with their Partita IVA or Codice Fiscale:

Use taxcode for Partita IVA.
Use 0210:taxcode to identify the Scheme for Codice Fiscale.
transport_type_code should be it.sdi.
document_type_code should be fatturapa.1.2.

Finally, if your contact have a Codice Destinatario (a routing code) to integrate their invoices from the SDI, enter it in the recipient_code field

You can also:

Set the VAT payability using the vat_payability field.
Add a certified email at certified_email field if they use Posta Elettronica Certificata (PEC).
Define a payment_method and bank_account_id for the contact. This is recommended but can also be set when creating the invoice.

Request Example:

curl --request POST
--url https://app-staging.b2brouter.net/projects/YOUR_PROJECT_ID/clients.json
--header 'X-B2B-API-Key: YOUR_API_KEY'
--header 'accept: application/json'
--header 'content-type: application/json'
--data '{
  "client": {
    "name": "Test Client Italy",
    "address": "Milano, 2",
    "postalcode": "20019",
    "city": "Milano",
    "province": "Milano",
    "country": "it",
    "transport_type_code": "it.sdi",
    "document_type_code": "fatturapa.1.2",
    "recipient_code": "1234567"
  }
}'

Sample Response:

{
    "client": {
        "id": 1313196666,
        "taxcode": "IT41683330934",
        "name": "Test Client Italy",
        "email": null,
        "website": null,
        "address": "Milano, 2",
        "address2": null,
        "postalcode": "20019",
        "city": "Milano",
        "province": "Milano",
        "country": "it",
        "language": "en",
        "currency": "EUR",
        "invoice_format": "send_fatturapa",
        "transport_type": "it.sdi",
        "document_type": "xml.fatturapa.1.2",
        "transport_type_code": "it.sdi",
        "document_type_code": "xml.fatturapa.1.2",
        "bank_account_number": null,
        "iban": null,
        "bic": null,
        "bank_account_id": null,
        "payment_method": 1,
        "payment_method_text": null,
        "terms": "custom",
        "sepa_type": "CORE",
        "company_identifier": null,
        "edi_code": null,
        "phone": null,
        "integration_code": null,
        "recipient_code": "1234567",
        "cin_scheme": null,
        "cin_value": null,
        "pin_scheme": null,
        "pin_value": null,
        "party_identification": null,
        "contact_person": null,
        "routing_codes": {
            "cin1_scheme": null,
            "cin1_value": null,
            "cin2_scheme": null,
            "cin2_value": null,
            "cin3_scheme": null,
            "cin3_value": null,
            "cin4_scheme": null,
            "cin4_value": null,
            "cin5_scheme": null,
            "cin5_value": null
        },
        "created_at": "2025-01-22T16:12:54Z",
        "updated_at": "2025-01-22T16:12:54Z"
    }
}

Once the contact is created, it's relevant to save the id of the contact to be able to use it later on to manage the contact or to link it to an invoice.

Creating and Sending an Invoice

To create and send an invoice in one step, use the "Create an issued invoice" call with the flag send_after_import: true.

When invoicing an Italian customer, ensure you provide all the required fields in the INVOICE OBJECT, including:

number
date
At least one invoice_lines_attributes
At least one taxes_attributes
contact_id or a complete CONTACT OBJECT

Additional Fields for Italian Invoices

In addition to the general fields, some specific fields are needed for the Italian invoicing workflow:

1. type_document: Defines the type of document (TipoDocumento) in the FatturaPA format. Check the API Reference for available options. If not provided, a default may be used.

2. receipt_reference: Provides details about a referenced receipt. This field is optional and applies only to the FatturaPA format.

Request Example:

curl --request POST
--url https://app-staging.b2brouter.net/projects/YOUR_PROJECT_ID/invoices.json
--header 'X-B2B-API-Key: YOUR_API_KEY'
--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
  }
}'

Sample Response:

{
  "invoice": {
    "id": 100523,
    "type": "IssuedInvoice",
    "number": "14",
    "to_net": null,
    "to_net_id": null,
    "from_net": "api",
    "from_net_id": null,
    "project": {
      "id": 3678,
      "name": "Enterprise Test Company"
    },
    "company": {
      "id": 3346,
      "name": "Enterprise Test Company",
      "taxcode": "ES14834629C",
      "address": "Main Street 1",
      "address2": null,
      "postalcode": "08201",
      "city": "Barcelona",
      "province": "Barcelona",
      "country": "es"
    },
    "client": {
      "id": 1313181394,
      "name": "Ajuntament de Figueres",
      "taxcode": "ESP1707200J",
      "address": "Invented Address, 1",
      "address2": null,
      "postalcode": "08201",
      "city": "Barcelona",
      "province": "Barcelona",
      "country": "es",
      "party_identification": null
    },
    "state": "sending",
    "date": "2025-01-24",
    "due_date": "2025-02-24",
    "ponumber": null,
    "file_reference": null,
    "payment_method_info": "Cash payment",
    "is_credit_note": false,
    "adjustment_in_cents": 0,
    "charge_reason": null,
    "charge_amount": 0.0,
    "charge_percent": 0.0,
    "discount_text": null,
    "discount_percent": 0.0,
    "discount_amount": 0.0,
    "subtotal": 500.0,
    "taxes": [
      {
        "name": "VAT 21,00%",
        "base": 500.0,
        "amount": 105.0
      }
    ],
    "total": 605.0,
    "currency": "EUR",
    "amounts_withheld_reason": null,
    "withheld_percent": 0.0,
    "amounts_withheld": 0.0,
    "payable_amount": 605.0,
    "extra_info": null,
    "attachments": [
    ],
    "created_at": "2025-01-24T08:52:25Z",
    "updated_at": "2025-01-24T08:52:25Z",
    "state_updated_at": "2025-01-24T08:52:25Z",
    "ack_at": null
  }
}

Once the invoice has been created and sent you will save the id of this invoice that will be useful to get back information from this invoice later on.

Checking Invoice Status

Once the invoice is sent, we need to confirm if the process was successful and if the invoice was properly registered on the SDI (Sistema di Interscambio) with its registration ID shown in the field to_net_id.

There are two options to check this:

Option 1: Check Status of Each Invoice Individually

You can query the status of each invoice using its internal ID with the "Get an invoice" API.

Request Example:

curl --request GET
--url 'https://app-staging.b2brouter.net/invoices/99915.json?include=lines'
--header 'X-B2B-API-Key: YOUR_API_KEY'
--header 'accept: application/json'

Sample Response:

{
  "invoice": {
    "id": 99915,
    "state": "sent",
    "to_net_id": null,
    "total": 573.4,
    "currency": "EUR",
    "created_at": "2025-01-22T16:30:39Z",
    "state_updated_at": "2025-01-22T16:30:41Z"
  }
}

Option 2: Check Status of Multiple Invoices

Alternatively, you can get the status of all issued invoices at once with the "List of issued invoices" API.

Request Example:

curl --request GET
--url 'https://app-staging.b2brouter.net/projects/73132/invoices.json?offset=0&limit=25'
--header 'X-B2B-API-Key: YOUR_API_KEY'
--header 'accept: application/json'

Sample Response:

{
  "invoices": [
    {
      "id": 99915,
      "state": "sent",
      "to_net_id": null,
      "total": 573.4,
      "currency": "EUR",
      "created_at": "2025-01-22T16:30:39Z",
      "state_updated_at": "2025-01-22T16:30:41Z"
    }
  ]
}

Mark Invoice as Acknowledged

If you use the list option, it is also useful to mark invoices as "acknowledged" when they reach their final state. This can be done using the "Mark an invoice as acknowledged" API, which prevents the invoice from appearing in the list of issued invoices.

Request Example:

curl --request POST
--url 'https://app-staging.b2brouter.net/invoices/99915/ack.json'
--header 'X-B2B-API-Key: YOUR_API_KEY'
--header 'accept: application/json'

Conclusion

This guide covers the key steps to sending invoices to the SDI through B2Brouter’s API.

For more details, consult the API Reference.