Configurer la connexion API de B2Brouter

L’API de B2Brouter vous permet d’intégrer votre ERP, votre e-commerce ou votre application propre pour créer, consulter et envoyer des documents automatiquement.

Dans ce guide, vous trouverez les informations de base pour commencer : où localiser l’account_id, comment générer une clé API, quelle est la différence entre production et tests, et comment effectuer votre première requête.

Pour les détails techniques complets des endpoints, consultez également la documentation pour les développeurs.

Avant de commencer

• Vous avez besoin d’un compte B2Brouter.
• Vous devez avoir accès à l’onglet Développeurs.
• Pour effectuer des tests, commencez par le sandbox — c’est l’environnement recommandé pour la plupart des tests. Utilisez l’environnement de staging complet uniquement pour les intégrations à grande échelle ou les tests de bout en bout étendus.

Où trouver l’account_id

Lorsque vous travaillez avec l’API, de nombreuses opérations sont effectuées sur un compte spécifique et nécessitent son account_id.

Vous pouvez le trouver de deux manières :

1. Dans B2Brouter, accédez à l’onglet Développeurs.
2. Cliquez sur Voir les ID de chaque compte ou sur l’icône de modification du groupe que vous avez à côté du nom du groupe.
3. Dans la liste des comptes, vous verrez l’ID correspondant à chaque compte.

Vous pouvez également l’obtenir via l’API en effectuant une requête pour lister les comptes du groupe. Dans la réponse, faites attention en particulier aux champs id et identifier.

Comment générer une clé API

1. Accédez à votre compte B2Brouter.
2. Allez dans l’onglet Développeurs.
3. Entrez dans API Keys.
4. Créez une nouvelle clé ou copiez-en une existante.
5. Conservez-la dans un endroit sûr.

Les clés API sont différentes selon l’environnement. La clé de production ne fonctionne pas pour le staging, et la clé de staging ne fonctionne pas pour la production.

Différence entre staging et production

B2Brouter dispose de deux environnements principaux :

• Production : https://api.b2brouter.net
• Staging : https://api-staging.b2brouter.net

Recommandations :

• Utilisez le sandbox pour la plupart des tests et le travail d’intégration initial.
• Utilisez staging uniquement pour les tests à grande échelle ou de bout en bout.
• Utilisez production uniquement lorsque vous avez entièrement validé le flux.
• Gardez séparées les identifiants et configurations de chaque environnement.

Si vous travaillez avec une ancienne version de l’API (2025-01-01), certains accès peuvent encore utiliser app.b2brouter.net, mais pour les nouvelles versions, la base recommandée est api.b2brouter.net ou api-staging.b2brouter.net.

Authentification

L’API de B2Brouter s’authentifie avec l’en-tête :

• X-B2B-API-Key

Optionnellement, vous pouvez également envoyer :

• X-B2B-API-Version

B2Brouter n’utilise pas Authorization: Bearer ... comme mécanisme principal d’authentification pour cette API. La façon correcte de s’authentifier est avec X-B2B-API-Key.

Première requête avec cURL

Un bon premier test consiste à lister les comptes disponibles de votre groupe :

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

Si la requête est correcte, vous obtiendrez une réponse JSON avec les comptes disponibles. À partir de là, vous pourrez utiliser l’account_id dans des requêtes telles que, par exemple :

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

Quel account_id utiliser

Lorsque vous effectuez des requêtes vers des endpoints tels que /accounts/{ACCOUNT_ID}/..., vous pouvez utiliser :

• L’ID numérique du compte.
• Ou bien l’identifiant du compte, si votre groupe l’utilise ainsi.

En cas de doute, commencez toujours par valider avec la requête GET /accounts.

Gestion des erreurs transitoires

Dans une intégration réelle, il est important de gérer les erreurs temporaires sans les considérer comme définitives.

Erreur 429 Too Many Requests

Cette erreur indique que vous avez dépassé la limite de requêtes.

Nous vous recommandons :

• Réduire la fréquence des appels.
• Effectuer un retry avec une attente progressive (exponential backoff).
• Éviter les boucles de consultation très fréquentes.

Erreur 503 Service Unavailable

Cette erreur indique un incident temporaire du service.

Nous vous recommandons :

• Réessayer après quelques secondes.
• Appliquer un nombre maximum de tentatives.
• Enregistrer l’erreur pour pouvoir en faire un suivi.

Recommandation générale de retry

Pour les erreurs temporaires telles que 429 ou 503 :

• Effectuez entre 3 et 5 nouvelles tentatives au maximum.
• Attendez un peu plus entre chaque tentative.
• Ne réessayez pas indéfiniment.

Webhooks

Si vous avez besoin de recevoir des notifications automatiques lorsque l’état d’une facture ou d’un document change, la meilleure option est d’utiliser des webhooks plutôt que d’effectuer des consultations continues à l’API.

Dans ce guide, nous n’entrons pas dans les détails de la configuration des webhooks, mais c’est la voie recommandée pour réduire les requêtes et recevoir des mises à jour en temps réel.

Prochaine étape recommandée

Une fois que vous avez validé :

1. La clé API.
2. L’accès à l’environnement correct.
3. L’account_id que vous allez utiliser.

Vous pouvez continuer avec les endpoints spécifiques dont votre intégration a besoin dans la documentation API.