Configurar la connexió API de B2Brouter

La API de B2Brouter et permet integrar el teu ERP, ecommerce o aplicació pròpia per crear, consultar i enviar documents automàticament.

En aquesta guia trobaràs la informació bàsica per començar: on localitzar l’account_id, com generar una clau API, quina diferència hi ha entre producció i proves i com fer la teva primera petició.

Per al detall tècnic complet dels endpoints, consulta també la documentació per a desenvolupadors.

Abans de començar

• Necessites un compte de B2Brouter.
• Has de tenir accés a la pestanya Desenvolupadors.
• Per fer proves, comença amb el sandbox — és l’entorn recomanat per a la majoria de proves. Utilitza l’entorn de staging complet només per a integracions a gran escala o proves exhaustives de punta a punta.

On trobar l’account_id

Quan treballes amb la API, moltes operacions es fan sobre un compte concret i necessiten el seu account_id.

El pots trobar de dues maneres:

1. Dins de B2Brouter, ves a la pestanya Desenvolupadors.
2. Fes clic a Veure els IDs de cada compte o a la icona d’editar del grup que tens al costat del nom del grup.
3. A la llista de comptes hi veuràs l’ID corresponent a cada compte.

També el pots obtenir via API fent una petició per llistar els comptes del grup. En la resposta, fixa’t especialment en els camps id i identifier.

Com generar una API key

1. Accedeix al teu compte de B2Brouter.
2. Ves a la pestanya Desenvolupadors.
3. Entra a API Keys.
4. Crea una nova clau o copia’n una d’existent.
5. Guarda-la en un lloc segur.

Les claus API són diferents segons l’entorn. La clau de producció no serveix per a staging, i la de staging no serveix per a producció.

Diferència entre staging i producció

B2Brouter té dos entorns principals:

• Producció: https://api.b2brouter.net
• Staging: https://api-staging.b2brouter.net

Recomanacions:

• Utilitza el sandbox per a la majoria de proves i el treball d’integració inicial.
• Utilitza staging només per a proves a gran escala o de punta a punta.
• Utilitza producció només quan ja hagis validat completament el flux.
• Mantén separades les credencials i configuracions de cada entorn.

Si treballes amb una versió antiga de la API (2025-01-01), alguns accessos encara poden utilitzar app.b2brouter.net, però per a les versions noves la base recomanada és api.b2brouter.net o api-staging.b2brouter.net.

Autenticació

La API de B2Brouter s’autentica amb la capçalera:

• X-B2B-API-Key

Opcionalment, també pots enviar:

• X-B2B-API-Version

B2Brouter no utilitza Authorization: Bearer ... com a mecanisme principal d’autenticació per a aquesta API. La manera correcta d’autenticar-se és amb X-B2B-API-Key.

Primera petició amb cURL

Una bona primera prova és llistar els comptes disponibles del teu grup:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts \
  --header 'X-B2B-API-Key: {LA_TEVA_API_KEY}' \
  --header 'X-B2B-API-Version: 2025-10-13' \
  --header 'accept: application/json'

Si la petició és correcta, obtindràs una resposta JSON amb els comptes disponibles. A partir d’aquí ja podràs utilitzar l’account_id en peticions com, per exemple:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {LA_TEVA_API_KEY}' \
  --header 'X-B2B-API-Version: 2025-10-13' \
  --header 'accept: application/json'

Quin account_id has d’utilitzar

Quan facis peticions a endpoints com /accounts/{ACCOUNT_ID}/..., pots utilitzar:

• L’ID numèric del compte.
• O bé l’identificador del compte, si el teu grup el fa servir així.

Si tens dubtes, comença sempre validant-ho amb la petició GET /accounts.

Gestió d’errors transitoris

En una integració real, és important gestionar els errors temporals sense considerar-los un error definitiu.

Error 429 Too Many Requests

Aquest error indica que has superat el límit de peticions.

Et recomanem:

• Reduir la freqüència de les crides.
• Fer retry amb espera progressiva (exponential backoff).
• Evitar bucles de consulta molt freqüents.

Error 503 Service Unavailable

Aquest error indica una incidència temporal del servei.

Et recomanem:

• Tornar-ho a provar al cap d’uns segons.
• Aplicar un màxim d’intents.
• Registrar l’error per poder-ne fer seguiment.

Recomanació general de retry

Per a errors temporals com 429 o 503:

• Fes entre 3 i 5 reintents com a màxim.
• Espera una mica més entre cada intent.
• No reintentes indefinidament.

Webhooks

Si necessites rebre notificacions automàtiques quan canvia l’estat d’una factura o d’un document, la millor opció és utilitzar webhooks en lloc de fer consultes contínues a la API.

En aquesta guia no entrem al detall de la configuració de webhooks, però és la via recomanada per reduir consultes i rebre actualitzacions en temps real.

Següent pas recomanat

Un cop hagis validat:

1. La clau API.
2. L’accés a l’entorn correcte.
3. L’account_id que faràs servir.

Ja pots continuar amb els endpoints específics que necessiti la teva integració a la documentació API.