Envoyer une facture via SDI

Ce guide explique comment envoyer des factures au SDI (Il Sistema di Interscambio) avec une entreprise italienne via l’API B2Brouter.

Le SDI est le point d’accès central de facturation géré par l’Agenzia delle Entrate, et toutes les factures doivent être envoyées par ce système au format FatturaPA 1.2.

Prérequis

• Une entreprise italienne avec une Partita IVA valide.
• Un compte enregistré dans l’environnement de test de B2Brouter : Register Here
• Des permissions API (à demander via un ticket de support : Open a Ticket)

Créer un compte entreprise italien

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

Créer un contact client

Lors de la création d’un client italien :

• utilisez tin_value pour la Partita IVA et tin_scheme: 9906 ;
• utilisez cin_value et cin_scheme pour identifier le scheme du Codice Fiscale ;
• transport_type_code doit être it.sdi ;
• document_type_code doit être xml.fatturapa.1.2 ;
• si le contact possède un Codice Destinatario, indiquez-le dans le champ recipient_code.

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

Créer et envoyer une facture

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

Champs supplémentaires pour les factures italiennes

• type_document : définit le type de document (TipoDocumento) dans le format FatturaPA.
• receipt_reference : fournit des détails sur un reçu référencé (optionnel, FatturaPA uniquement).

Vérifier le statut de la facture

Option 1 : vérifier le statut de chaque facture individuellement

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 : vérifier le statut de plusieurs 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'

Une fois la facture arrivée à son état final, marquez-la comme reconnue pour la retirer de la liste active :

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'

Pour plus de détails, consultez la référence API.