Enviar factures (d'extrem a extrem)

Aquesta guia mostra un flux d’API net per enviar factures: crear o reutilitzar un contacte, crear o importar una factura, enviar-la i recuperar els fitxers finals.

Requisits previs

Clau d’API: X-B2B-API-Key
Versió d’API: X-B2B-API-Version
ACCOUNT_ID: el compte que emet la factura.

IDs importants:

ACCOUNT_ID: compte propietari (paràmetre de ruta a /accounts/{ACCOUNT_ID}/...).
CONTACT_ID: contacte destinatari (emmagatzemat dins del compte).
INVOICE_ID: identificador de factura (usat als endpoints /invoices/{INVOICE_ID}...).

1) Obtenir o crear el contacte destinatari

1.1) Cercar contactes (opcional)

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/contacts?offset=0&limit=25&name=Example%20Customer' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

1.2) Cercar al directori (opcional)

Si coneixes l’identificador i el país del destinatari, pots recuperar informació pública del directori i usar-la per construir el contacte.

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/es/ESB63276174 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

1.3) Crear un contacte (si no en tens cap)

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": {
      "name": "Example Customer",
      "country": "es",
      "is_client": true,
      "email": "billing@example.com",
      "tin_scheme": "9920",
      "tin_value": "ESB00000000",
      "transport_type_code": "b2brouter",
      "document_type_code": "json"
    }
  }'

Nota: CONTACT_ID es retorna a la resposta. No el confondràs amb ACCOUNT_ID.

2) Crear (JSON) o importar (XML) la factura

2.1) Crear factura usant JSON

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 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "send_after_import": false,
    "invoice": {
      "type": "IssuedInvoice",
      "contact_id": {CONTACT_ID},
      "number": "INV-0001",
      "date": "2026-01-21",
      "terms": "custom",
      "due_date": "2026-02-21",
      "currency": "EUR",
      "invoice_lines_attributes": [
        {
          "quantity": 1,
          "price": 10,
          "description": "Example service",
          "taxes_attributes": [
            { "name": "VAT", "category": "S", "percent": 21 }
          ]
        }
      ]
    }
  }'

2.2) Importar factura des d’un fitxer (quan ja generes XML)

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices/import?send_after_import=false' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'content-type: application/octet-stream' \
  --data 'data:text/xml;name=invoice.xml;base64,PD94bWw+Li4u'

2.3) Què passa amb les dades del contacte que porta la factura (`update_contact`)

Quan importes un fitxer, o crees una factura amb un bloc contact en lloc de contact_id, B2Brouter cerca el comprador entre els contactes del compte pels seus identificadors i fa servir el contacte que troba. Per defecte, una importació no modifica mai un contacte existent:

Si alguna dada del fitxer (adreça, codis d’encaminament, mètode d’enviament) no coincideix amb la del contacte, la factura queda assignada a una unitat organitzativa d’aquest contacte amb les dades del fitxer. El contacte no canvia.
Si només difereix el nom, no passa res: no es crea cap unitat organitzativa ni s’escriu cap camp, i la factura surt amb el nom desat al contacte.

El paràmetre update_contact és opcional, per defecte està desactivat i existeix a totes les versions de l’API. Envia update_contact=true (com a paràmetre de consulta a la crida d’importació, o com a camp de primer nivell del cos JSON a la crida de creació, igual que send_after_import) perquè la importació actualitzi el contacte en lloc de crear una unitat organitzativa. Si ja existeix una unitat organitzativa amb aquestes dades, s’utilitza aquesta.

Les dades descriptives del fitxer (el nom inclòs, l’adreça i la resta de camps que no són identificadors) substitueixen les del contacte.
Els identificadors (identificador fiscal, identificador d’empresa, identificador Peppol i codis d’encaminament) només s’omplen si al contacte estaven buits. Un identificador que ja té valor no se sobreescriu mai, encara que el fitxer en porti un de diferent.
Un valor buit al fitxer no esborra mai el valor desat.
A les factures rebudes el paràmetre s’ignora: un document rebut no actualitza mai el contacte del proveïdor.
L’endpoint d’importació massiva /invoices/imports no admet aquest paràmetre.

Decideix quina banda mana sobre les dades del contacte. Amb update_contact=true a totes les crides, la factura que envies és la referència: qualsevol canvi al fitxer es propaga a la fitxa del contacte i a les factures posteriors. Sense el paràmetre, la fitxa del contacte a B2Brouter és la referència, i la corregeixes amb l’API de contactes o des de l’aplicació web.

3) Enviar la factura

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/send_invoice/{INVOICE_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

4) Recuperar la factura i descarregar els fitxers finals

4.1) Obtenir el payload de la factura

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'

4.2) Descarregar fitxers de factura legals/originals

Consulta la guia Descarregar factures.