bexio-API: erste Schritte für Entwickler

Ihre erste Anfrage an die bexio-API besteht aus drei Dingen: einem Token, den Sie über den Authorization Code Flow bei auth.bexio.com holen, den Headern Accept und Authorization und einer Adresse unter api.bexio.com, zum Beispiel für die Kontaktliste. Dieser Beitrag führt Sie von der Anmeldung bis zum ersten erfolgreichen Aufruf und zeigt, wie Sie sicher testen. Wie Sie Zugang und Scopes einrichten, steht im Beitrag bexio-API: Zugang und Token einrichten.

Der Ablauf im Überblick

Die Dokumentation nennt dafür den «Authorization Code Grant» nach OAuth 2.0 (RFC 6749, Abschnitt 4.1). Die Anwendung muss serverseitig laufen, weil sie das Client Secret mitsendet.

Schritt 1: Autorisierung starten

Die Adressen der Anmeldung liefert die Discovery-Datei unter https://auth.bexio.com/realms/bexio/.well-known/openid-configuration. Der Autorisierungs-Endpunkt lautet https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth. Die Dokumentation kündigte die Abschaltung der älteren Adresse idp.bexio.com für den 31. März 2025 an. Verwenden Sie nur die neuen Adressen.

Leiten Sie den Benutzer mit diesen Parametern weiter. Die Namen stammen aus dem Standard:

https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=openid%20offline_access%20contact_show&state=<ZUFALLSWERT>

• response_type=code verlangt einen Autorisierungscode.
• redirect_uri muss genau zu einer Adresse passen, die Sie in der App eingetragen haben.
• scope nennt die gewünschten Rechte, getrennt durch Leerzeichen. offline_access brauchen Sie für ein Refresh Token.
• state ist ein Zufallswert, den bexio unverändert zurückgibt. Er schützt vor gefälschten Rückleitungen.

Nach der Zustimmung hängt bexio den code an Ihre Redirect-URL.

Schritt 2: Code gegen Token tauschen

Senden Sie den Code an den Token-Endpunkt https://auth.bexio.com/realms/bexio/protocol/openid-connect/token. Die Dokumentation zeigt dafür kein Beispiel und verweist auf RFC 6749. Die Parameter unten folgen deshalb dem Standard:

curl -X POST 'https://auth.bexio.com/realms/bexio/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=<CODE>' \
  -d 'redirect_uri=<REDIRECT_URI>' \
  -d 'client_id=<CLIENT_ID>' \
  -d 'client_secret=<CLIENT_SECRET>'

bexio nimmt Parameter nur im Body entgegen. Die Antwort enthält ein Access Token und ein ID Token. Mit offline_access kommt ein Refresh Token dazu. Den Code verwenden Sie nur einmal.

Schritt 3: Die erste Anfrage

Die Kontaktliste verlangt den Scope contact_show. Mit dem Access Token rufen Sie sie so ab:

curl -X GET 'https://api.bexio.com/2.0/contact?limit=20&order_by=name_1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Erhalten Sie eine Liste mit Kontakten, funktionieren Anmeldung, Token und Scope. Ein Personal Access Token verwenden Sie genauso im Header. Der Unterschied liegt nur darin, wie Sie ihn bekommen.

Schritt 4: Das Token erneuern

Mit offline_access erhalten Sie ein Refresh Token. Senden Sie es mit grant_type=refresh_token an denselben Token-Endpunkt und Sie bekommen ein neues Access Token. Die Scopes ändern sich dabei nicht. Die Dokumentation fordert in ihrer Migrationsanleitung, ein neu ausgegebenes Refresh Token anstelle des alten zu speichern. Übernehmen Sie das auch im Normalbetrieb. Eine Offline-Sitzung wird geschlossen, wenn sie ein Jahr lang nicht erneuert wird. Wie lange ein Access Token gültig bleibt, nennt die Dokumentation nicht. Verlassen Sie sich auf die Fehlerantwort 401 und erneuern Sie dann.

Endpunkte und Konventionen

Löschen ist laut Dokumentation endgültig und lässt sich nicht rückgängig machen. Bei der Suche besteht jedes Kriterium aus field, value und criteria. Fehlt criteria, gilt like. Möglich sind unter anderem =, !=, >, <, like, is_null und in. Was die Schnittstelle abdeckt und wo Grenzen liegen, erklärt der Beitrag Die bexio-Schnittstelle: was damit möglich ist.

Fehlercodes und Anfragelimit

Fehler kommen als Statuscode mit einem JSON-Body wie {"error_code": 404, "message": "Page not found"}.

Das Limit gilt pro Unternehmen und Minute. Die Kopfzeilen RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset zeigen Grenze, Restmenge und Sekunden bis zum Neustart. Lesen Sie sie aus und pausieren Sie, bevor die Schnittstelle 429 meldet. Bei 401 und 403 hilft der Beitrag bexio-Schnittstelle meldet 401 oder 403, bei 429 und 500 der Beitrag bexio-Schnittstelle meldet 429 oder 500.

Sicher testen

1. Sandbox verwenden: Zum Entwickeln nennt bexio einen API-Sandbox-Account. Testen Sie dort, nicht in Ihrer echten Buchhaltung.
2. Musterdaten anlegen: Legen Sie zum Beispiel einen Kontakt «Muster Haustechnik AG» an. Pflichtfelder sind laut Dokumentation contact_type_id (1 für Firmen, 2 für Personen), name_1, user_id und owner_id. Die Benutzer-IDs liefert die Benutzerverwaltung der Schnittstelle.
3. Erst lesen, dann schreiben: Prüfen Sie mit GET, was Ihre Anfrage liefert, bevor Sie POST oder PATCH einsetzen.
4. Zwei Apps trennen: Für die Produktion legen Sie eine zweite App mit eigenem Client Secret an.
5. Anfragen nachstellen: Reproduzieren Sie Probleme mit einem Werkzeug wie Postman. Die Dokumentation verlangt das, bevor Sie einen Fehler melden. Geben Sie im Meldeformular keine Zugangsdaten an.
6. Versand beachten: Bei den Endpunkten zum Versenden von Dokumenten nennt die Dokumentation für die Testphase eine Einschränkung auf die Adresse, die zum Token gehört.

Häufige Fragen

Gibt es eine OpenAPI-Definition?

Laut den FAQ der Dokumentation nicht, sie ist aber geplant. Prüfen Sie den Stand in der Dokumentation, bevor Sie Code daraus generieren wollen.

Wo erfahre ich von Änderungen?

Die Dokumentation führt ein Änderungsprotokoll, eine Statusseite und einen Entwickler-Newsletter. Neue Pflichtfelder und abgelöste Felder stehen im Protokoll.

Wer hilft bei Problemen in meiner Anbindung?

Die Schnittstelle wird laut Dokumentation und Hilfe so bereitgestellt, wie sie beschrieben ist. Es gibt keine begleitete Umsetzung und keinen Code-Support. Anwender mit einer Anbindung von Dritten wenden sich an den Anbieter.

Fazit

Mit drei Bausteinen klappt der Einstieg: Token über den Authorization Code Flow, die Header Accept und Authorization und die Adresse unter api.bexio.com. Starten Sie in der Sandbox, lesen Sie vor dem Schreiben und beachten Sie das Anfragelimit. Löschen ist endgültig, deshalb gehört echte Buchhaltung nicht in Ihre ersten Tests.