B2Brouter-API-Verbindung konfigurieren

Die B2Brouter-API ermöglicht es Ihnen, Ihr ERP, Ihren E-Commerce oder Ihre eigene Anwendung zu integrieren, um Dokumente automatisch zu erstellen, abzufragen und zu senden.

In dieser Anleitung finden Sie die grundlegenden Informationen für den Einstieg: wo Sie die account_id finden, wie Sie einen API-Schlüssel erzeugen, worin der Unterschied zwischen Produktion und Tests besteht und wie Sie Ihre erste Anfrage senden.

Für vollständige technische Details der Endpunkte lesen Sie auch die Entwicklerdokumentation.

Bevor Sie beginnen

• Sie benötigen ein B2Brouter-Konto.
• Sie müssen Zugriff auf den Tab Entwickler haben.
• Beginnen Sie für Tests mit der Sandbox — sie ist die empfohlene Umgebung für die meisten Tests. Verwenden Sie die vollständige Staging-Umgebung nur für umfangreiche Integrationen oder umfassende End-to-End-Tests.

Wo Sie die account_id finden

Wenn Sie mit der API arbeiten, beziehen sich viele Vorgänge auf ein konkretes Konto und benötigen dessen account_id.

Sie können sie auf zwei Arten finden:

1. Öffnen Sie in B2Brouter den Tab Entwickler.
2. Klicken Sie auf IDs jedes Kontos anzeigen oder auf das Bearbeitungssymbol der Gruppe neben dem Gruppennamen.
3. In der Kontoliste sehen Sie die entsprechende ID jedes Kontos.

Sie können sie auch per API abrufen, indem Sie eine Anfrage zum Auflisten der Gruppenkonten senden. Achten Sie in der Antwort besonders auf die Felder id und identifier.

API key erzeugen

1. Melden Sie sich bei Ihrem B2Brouter-Konto an.
2. Öffnen Sie den Tab Entwickler.
3. Öffnen Sie API Keys.
4. Erstellen Sie einen neuen Schlüssel oder kopieren Sie einen vorhandenen.
5. Bewahren Sie ihn an einem sicheren Ort auf.

API-Schlüssel unterscheiden sich je nach Umgebung. Der Produktionsschlüssel funktioniert nicht für Staging, und der Staging-Schlüssel funktioniert nicht für Produktion.

Unterschied zwischen Staging und Produktion

B2Brouter hat zwei Hauptumgebungen:

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

Empfehlungen:

• Verwenden Sie die Sandbox für die meisten Tests und die anfängliche Integrationsarbeit.
• Verwenden Sie Staging nur für umfangreiche oder umfassende End-to-End-Tests.
• Verwenden Sie Produktion erst, wenn Sie den Ablauf vollständig validiert haben.
• Halten Sie Zugangsdaten und Konfigurationen der Umgebungen getrennt.

Wenn Sie mit einer alten API-Version (2025-01-01) arbeiten, können einige Zugriffe noch app.b2brouter.net verwenden. Für neue Versionen ist jedoch api.b2brouter.net oder api-staging.b2brouter.net die empfohlene Basis.

Authentifizierung

Die B2Brouter-API authentifiziert sich mit dem Header:

• X-B2B-API-Key

Optional können Sie auch senden:

• X-B2B-API-Version

B2Brouter verwendet Authorization: Bearer ... nicht als primären Authentifizierungsmechanismus für diese API. Der korrekte Weg zur Authentifizierung ist X-B2B-API-Key.

Erste Anfrage mit cURL

Ein guter erster Test ist das Auflisten der verfügbaren Konten Ihrer Gruppe:

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

Wenn die Anfrage korrekt ist, erhalten Sie eine JSON-Antwort mit den verfügbaren Konten. Danach können Sie die account_id in Anfragen verwenden, zum Beispiel:

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

Welche account_id Sie verwenden sollten

Wenn Sie Anfragen an Endpunkte wie /accounts/{ACCOUNT_ID}/... senden, können Sie verwenden:

• Die numerische ID des Kontos.
• Oder die Kennung des Kontos, wenn Ihre Gruppe so arbeitet.

Wenn Sie unsicher sind, validieren Sie dies immer zuerst mit der Anfrage GET /accounts.

Umgang mit vorübergehenden Fehlern

In einer realen Integration ist es wichtig, temporäre Fehler zu behandeln, ohne sie als endgültigen Fehler zu betrachten.

Fehler 429 Too Many Requests

Dieser Fehler zeigt an, dass Sie das Anfragelimit überschritten haben.

Wir empfehlen:

• Die Häufigkeit der Aufrufe zu reduzieren.
• Retry mit progressiver Wartezeit (exponential backoff) zu verwenden.
• Sehr häufige Abfrageschleifen zu vermeiden.

Fehler 503 Service Unavailable

Dieser Fehler zeigt eine temporäre Dienststörung an.

Wir empfehlen:

• Es nach einigen Sekunden erneut zu versuchen.
• Eine maximale Anzahl von Versuchen anzuwenden.
• Den Fehler zu protokollieren, um ihn nachverfolgen zu können.

Allgemeine Retry-Empfehlung

Für temporäre Fehler wie 429 oder 503:

• Führen Sie maximal 3 bis 5 erneute Versuche aus.
• Warten Sie zwischen den Versuchen jeweils etwas länger.
• Wiederholen Sie nicht unbegrenzt.

Webhooks

Wenn Sie automatische Benachrichtigungen benötigen, wenn sich der Status einer Rechnung oder eines Dokuments ändert, ist die beste Option, Webhooks statt kontinuierlicher API-Abfragen zu verwenden.

In dieser Anleitung gehen wir nicht im Detail auf die Konfiguration von Webhooks ein. Sie sind jedoch der empfohlene Weg, um Abfragen zu reduzieren und Aktualisierungen in Echtzeit zu erhalten.

Empfohlener nächster Schritt

Nachdem Sie Folgendes validiert haben:

1. Den API-Schlüssel.
2. Den Zugriff auf die richtige Umgebung.
3. Die account_id, die Sie verwenden werden.

Können Sie mit den spezifischen Endpunkten fortfahren, die Ihre Integration in der API-Dokumentation benötigt.