Enviar factura via SDI

Aquesta guia explica com enviar factures a l’SDI (Il Sistema di Interscambio) amb una empresa italiana mitjançant l’API de B2Brouter.

L’SDI és el punt d’accés central de facturació gestionat per l’Agenzia delle Entrate, i totes les factures s’han d’enviar a través d’aquest sistema en format FatturaPA 1.2.

Prerequisits

• Una empresa italiana amb una Partita IVA vàlida.
• Un compte registrat a l’entorn de proves de B2Brouter: Registra’t aquí
• Permisos d’API (sol·liciteu-los obrint un tiquet de suport: Obrir un tiquet)

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

Crear un contacte de client

Quan creeu un client italià:

• Feu servir tin_value per a la Partita IVA i tin_scheme: 9906.
• Feu servir cin_value i cin_scheme per identificar l’esquema del Codice Fiscale.
• transport_type_code hauria de ser it.sdi.
• document_type_code hauria de ser xml.fatturapa.1.2.
• Si el contacte té un Codice Destinatario, introduïu-lo al camp 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}"
    }
  }'

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

Camps addicionals per a factures italianes

• type_document: defineix el tipus de document (TipoDocumento) en el format FatturaPA.
• receipt_reference: proporciona detalls sobre un rebut referenciat (opcional, només FatturaPA).

Comprovar l’estat de la factura

Opció 1: consultar l’estat de cada factura individualment

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 l’estat de 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, marqueu-la com a reconeguda per eliminar-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'

Per a més detalls, consulteu la referència de l’API.