Send invoice via SDI

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)

Creating an Italian Company Account

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": "Milano",
      "email": "john.doe@example.com"
    }
  }'

Creating a Customer Contact

When creating an Italian customer:

• Use tin_value for Partita IVA and tin_scheme: 9906.
• Use cin_value and cin_scheme to identify the Scheme for Codice Fiscale.
• transport_type_code should be it.sdi.
• document_type_code should be xml.fatturapa.1.2.
• If the contact has a Codice Destinatario, enter it in the recipient_code field.

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": "Roma",
      "country": "it",
      "transport_type_code": "it.sdi",
      "document_type_code": "xml.fatturapa.1.2",
      "recipient_code": "{CODICE_DESTINATARIO}"
    }
  }'

Creating and Sending 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}
    }
  }'

Additional Fields for Italian Invoices

• type_document: Defines the type of document (TipoDocumento) in the FatturaPA format.
• receipt_reference: Provides details about a referenced receipt (optional, FatturaPA only).

Checking Invoice Status

Option 1: Check Status of Each Invoice Individually

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: Check Status of Multiple 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'

Once 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'

For more details, consult the API Reference.