Introducció

Entorns

B2Brouter té tres entorns — consulta Entorns per a una comparació completa.

Entorn	URL base	Quan usar-lo
Sandbox	`https://api.b2brouter.net` (prefix de clau `test_`)	Desenvolupament diari, validació de payloads, incorporació
Staging	`https://api-staging.b2brouter.net`	Integracions grans, proves d’extrem a extrem àmplies, entorns QA d’autoritats
Producció	`https://api.b2brouter.net`	Tràfic en viu

Comença amb Sandbox. És l’entorn recomanat per al desenvolupament inicial i les proves diàries. Usa staging únicament per a integracions a gran escala o proves d’extrem a extrem àmplies que requereixin una configuració completa de l’entorn.

Primers passos

Registra’t i configura el teu compte

Per començar a usar l’API de B2Brouter, registra’t a app.b2brouter.net/en/register. Les instruccions detallades de configuració estan disponibles aquí.

Un cop registrat, inicia sessió a B2Brouter i configura el teu compte amb un pla Basic. Pots trobar instruccions detallades aquí.

Obtenir una clau d’API de sandbox

Obre la secció Developers i crea un sandbox. La teva clau d’API de sandbox comença amb test_ i encamina totes les peticions a l’entorn sandbox automàticament — no cal cap URL separada. Consulta Sandbox per a les instruccions completes de configuració.

Activació de l’entorn Staging

Si necessites l’entorn staging (integracions grans, proves d’extrem a extrem àmplies), registra’t a app-staging.b2brouter.net/en/register. Els comptes de staging comencen amb permisos limitats — envia un tiquet de suport per sol·licitar l’accés necessari. El nostre equip te’l concedirà.

Usar l’API REST

Per accedir a l’API de B2Brouter, segueix aquests passos:

Accedeix al teu compte.
Dins del teu compte, fes clic a la pestanya Developers.
Fes clic a la clau d’API per copiar-la al porta-retalls.
Per trobar els IDs dels comptes, fes clic a Veure IDs per a cada compte o fes clic a la icona Editar grup al costat del nom del teu grup.
Accedeix a la Referència de l’API.

Nota: Les claus d’API són específiques per a cada entorn. Les claus de sandbox (prefix test_) només funcionen al sandbox; les claus de producció només funcionen a producció; les claus de staging només funcionen a staging. Obtén cada clau iniciant sessió a l’entorn corresponent.

Per defecte, la Referència de l’API està documentada amb l’entorn staging. Per canviar a sandbox o producció, obre el desplegable URL base.

Autenticació

Les credencials s’han de proporcionar a les capçaleres de la petició, amb el nom X-B2B-API-Key.

Claus estàndard i claus restringides

A la pestanya Developers hi ha dos tipus de clau d’API:

Clau estàndard: té accés complet a l’API. Cada grup en té una.
Claus restringides: només tenen els permisos que els dones. Crea-les amb Crear clau restringida.

Una clau restringida té un permís per secció de l’API: Cap, Lectura o Escriptura. Escriptura inclou Lectura.

La secció general s’aplica a totes les seccions que no configures una per una. Si una secció no té permís propi i general tampoc en té, la clau no hi té accés.

Les seccions i els permisos que admeten:

Lectura o Escriptura: general, accounts (comptes, empreses i projectes), invoices (factures emeses i rebudes, simplificades, autofactures i importacions), contacts, payments, orders, transports, tax_reports, tax_report_settings, bank_accounts, web_hooks, tin_verifications, attachments, ledgers.
Només Lectura: directory, events, codelists (usuaris i llistes de codis), accounting, knowledge.
Només Escriptura: validation (validació de documents).
Només clau estàndard: reseller_companies. Una clau restringida no hi pot accedir.

Si una clau restringida no té prou permís per a una petició, l’API retorna 401 Unauthorized amb el missatge This API Key has insufficient permissions for this action.

Versió de l’API

A B2Brouter, cada grup té una Versió de l’API per defecte. Pots comprovar-la a la pestanya Developers, sota Claus d’API. Pots especificar manualment la Versió de l’API a les capçaleres de la petició, amb el nom X-B2B-API-Version. Si no s’especifica cap versió, B2Brouter usarà la versió per defecte del grup.

Formats de resposta

B2Brouter proporciona la resposta únicament en format JSON.

Identificadors de compte

Usa l’endpoint Llistar comptes

curl --request GET \
  --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'

En aquesta resposta, para atenció a la informació del camp identifier. Has d’usar aquest ID quan vulguis interactuar amb el compte a través de l’API.

Nota: També pots trobar els IDs dels comptes a la pestanya Developers fent clic a la icona Editar grup al costat del nom del teu grup. Es mostrarà la llista de comptes i els seus IDs.

Limitació de velocitat de l’API

Per garantir un rendiment òptim i un ús just, l’API de B2Brouter aplica límits de velocitat a les peticions entrants:

Límits de velocitat:

Producció: 1.000 peticions per minut
Sandbox / Staging: 600 peticions per minut

Límit de velocitat superat: Quan superes el límit de velocitat, l’API retorna:

Codi d’estat HTTP 429 Too Many Requests

Bones pràctiques:

Implementa exponential backoff quan reps respostes 429
Emmagatzema respostes a la memòria cau quan sigui possible per reduir les crides a l’API
Usa webhooks en lloc de polling per a actualitzacions en temps real

SDKs i biblioteques de client

Pots integrar-te amb l’API directament via HTTP o usant un SDK oficial. El primer SDK oficial és el PHP SDK:

GitHub: https://github.com/B2Brouter/b2brouter-php

Proporciona mètodes per a la gestió completa de factures, descàrregues de documents en múltiples formats, operacions completes d’informes fiscals (incloent Verifactu), utilitats de paginació i gestió d’errors. Es continuaran afegint SDKs addicionals per a altres llenguatges de programació.

Descarregar la Referència OpenAPI

Pots descarregar la referència completa de l’API REST en format OpenAPI (YAML) des dels següents enllaços: