Billbee-API und Webhooks einrichten

Schritt 1: Zwei Teile: API-Key und API-Passwort

Jeder API-Aufruf braucht zwei Dinge: Den API-Key – er kennzeichnet die Anwendung und gehört dem Entwickler bzw. Dienstleister. Und die Zugangsdaten des Händlers: Benutzername (beim Hauptaccount die E-Mail-Adresse des Billbee-Kontos, bei Mitarbeitern deren Benutzername) plus ein eigenes API-Passwort.

Stolperfalle: Bindest du einen fertigen Dienst an (Fulfiller, Buchhaltungstool), bringt der seinen API-Key mit. Du gibst dann nur Benutzername und API-Passwort weiter – nie dein Login-Passwort.

Schritt 2: API-Key bei Billbee beantragen

Programmierst du selbst, beantragst du den API-Key über das Formular, das in der Billbee-Hilfe zum API-Zugriff verlinkt ist. Der Key kommt per E-Mail; das dauert in der Regel ein paar Werktage. Ein Key gilt für deine Anwendung – auch wenn sie später mehrere Billbee-Konten nutzt.

Stolperfalle: Im Billbee-Konto selbst findest du keinen API-Key. Wer ihn dort sucht, sucht vergeblich – er steht nur in der Mail von Billbee.

Schritt 3: API aktivieren und API-Passwort setzen

Unter Einstellungen → Billbee API → Allgemeine Einstellungen schaltest du „Aktivieren" ein und vergibst ein API-Passwort: mindestens 12 Zeichen, Groß- und Kleinbuchstaben, eine Zahl und ein Sonderzeichen. Dann speichern.

Vergrößern

Stolperfalle: Notier dir das Passwort sofort: Billbee zeigt es danach nie wieder an, auch der Support kann es nicht sehen. Es darf keinen Doppelpunkt enthalten. Und es gilt für Hauptaccount und alle Mitarbeiter gemeinsam – wer es ändert, ändert es für alle Anbindungen.

Schritt 4: Rechnungserstellung über die API erlauben

Im zweiten Reiter Rechnungserstellung legst du fest, ob über die API neue Rechnungen erzeugt werden dürfen. Standardmäßig ist das aus. Brauchst du es (z. B. ein Lagerprogramm erstellt die Rechnung beim Packen), schalte es ein und speichere.

Vergrößern

Stolperfalle: Ist der Schalter aus, scheitert jeder Versuch, über die API eine neue Rechnung zu erzeugen – auch wenn Key und Passwort stimmen.

Schritt 5: Den ersten Aufruf testen

Die API erwartet den API-Key im Header X-Billbee-Api-Key und Benutzername + API-Passwort als Basic-Auth. Ein einfacher Test, der die neueste Bestellung abruft:

curl https://app.billbee.io/api/v1/orders?pageSize=1 \
  -H "X-Billbee-Api-Key: DEIN-API-KEY" \
  -u "deine@mail.de:DEIN-API-PASSWORT"

Alle Endpunkte stehen in der Swagger-Dokumentation; für .NET und PHP gibt es fertige SDKs von Billbee.

Stolperfalle: 401 heißt fast immer: Login-Passwort statt API-Passwort genommen oder beim Mitarbeiter die E-Mail statt des Benutzernamens. 403 heißt: API im Konto nicht aktiviert (Schritt 3) oder das Konto ist nicht aktiv.

Schritt 6: Webhooks: Billbee meldet sich bei dir

Statt ständig nachzufragen, kann Billbee deinen Server bei Ereignissen selbst aufrufen. Webhooks legst du über die API an (POST /api/v1/webhooks) mit Zieladresse, einem geheimen Wort und den gewünschten Ereignissen:

POST https://app.billbee.io/api/v1/webhooks
{
  "WebHookUri": "https://dein-server.de/billbee-hook",
  "Secret": "ein-langes-geheimes-wort",
  "Description": "Neue Bestellungen an unser Lager",
  "Filters": ["order.created", "order.updated"]
}

Verfügbare Ereignisse (GET /api/v1/webhooks/filters): order.created, order.updated, article.created, article.updated, stockarticle.updated, dazu Ereignisse für anonymisierte bzw. wiederhergestellte Bestellungen und Kunden – oder * für alles.

Stolperfalle: Beim Anlegen schickt Billbee einen Test-Aufruf an deine Adresse. Ist dein Server noch nicht bereit, hängst du ?noecho an die Adresse an. Prüfe eingehende Aufrufe mit deinem Secret, sonst kann jeder deine Adresse füttern.