Enviar factura por SDI

Esta guía explica cómo enviar facturas al SDI (Il Sistema di Interscambio) con una empresa italiana a través de la API de B2Brouter.

El SDI es el punto de acceso central de facturación gestionado por la Agenzia delle Entrate, y todas las facturas deben enviarse a través de este sistema en formato FatturaPA 1.2.

Requisitos previos

• Una empresa italiana con una Partita IVA válida.
• Una cuenta registrada en el entorno de pruebas de B2Brouter: Regístrate aquí
• Permisos de API (solicítalos a través de un ticket de soporte: Abrir un ticket)

Crear una cuenta de 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 contact de cliente

Al crear un cliente italiano:

• Usa tin_value para la Partita IVA y tin_scheme: 9906.
• Usa cin_value y cin_scheme para identificar el Scheme del Codice Fiscale.
• transport_type_code debe ser it.sdi.
• document_type_code debe ser xml.fatturapa.1.2.
• Si el contact tiene un Codice Destinatario, introdúcelo en el campo 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 y 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}
    }
  }'

Campos adicionales para facturas italianas

• type_document: Define el tipo de documento (TipoDocumento) en el formato FatturaPA.
• receipt_reference: Proporciona detalles sobre un recibo referenciado (opcional, solo FatturaPA).

Comprobar el estado de la factura

Opción 1: Comprobar el estado de cada factura individualmente

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ón 2: Comprobar el estado de varias facturas

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'

Una vez que la factura alcanza su estado final, márcala como confirmada para eliminarla de la lista 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'

Para más detalles, consulta la Referencia de la API.