Authentifizierung (API-Key) – aifinyo | Billomat

Damit die Billomat API weiß, wer du bist, musst du bei jeder Anfrage deinen persönlichen API-Schlüssel mitschicken.

Was ist der API-Schlüssel?

Der API-Schlüssel ist dein persönliches „Passwort" für die Billomat API. Da die API keine Sitzungen speichert – jede Anfrage steht also für sich allein – muss der Schlüssel bei jedem einzelnen Request mitgeschickt werden.

Der API-Schlüssel ist an einen bestimmten Billomat-Benutzer gebunden. Die API-Anfragen laufen damit immer im Kontext und mit den Rechten dieses Benutzers.

Wichtig: Behandle deinen API-Schlüssel wie ein Passwort. Wer ihn kennt, hat über die API vollen Zugriff auf deinen Account. Wie du ihn sicher aufbewahrst, erfährst du im Artikel Sicherheit & HTTPS.

API-Zugriff aktivieren und Schlüssel generieren

Bevor du die API nutzen kannst, muss der API-Zugriff für deinen Benutzer einmalig freigeschaltet werden. So geht's:

Navigiere zu Einstellungen > Mitarbeiter.
Öffne deinen Benutzer und aktiviere dort den API-Zugriff.
Generiere anschließend einen persönlichen API-Schlüssel – dieser wird dir einmalig angezeigt und sollte direkt sicher gespeichert werden.

Tipp: Leg für jede externe Anwendung oder Integration am besten einen eigenen Billomat-Benutzer an. So kannst du den Zugriff für eine einzelne Integration jederzeit deaktivieren, ohne andere Anbindungen zu beeinflussen.

Wie übergibst du den API-Schlüssel?

Es gibt zwei Möglichkeiten, den API-Schlüssel bei einer Anfrage mitzuschicken:

Methode 1: Per HTTP-Header (empfohlen)

Der Schlüssel wird im Request-Header unter X-BillomatApiKey übergeben. Das ist die bevorzugte Methode, da der Schlüssel so nicht in URLs oder Server-Logs auftaucht.

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
https://{deineBillomatID}.billomat.net/api/clients

Methode 2: Per GET-Parameter

Alternativ kann der Schlüssel direkt als URL-Parameter übergeben werden. Diese Methode ist einfacher für schnelle Tests im Browser, aber weniger sicher für den produktiven Einsatz.

https://{deineBillomatID}.billomat.net/api/clients?api_key={dein-api-schluessel}

Hinweis: URLs mit API-Schlüssel im GET-Parameter können in Browser-Verläufen, Server-Logs und Proxy-Protokollen gespeichert werden. Verwende diese Methode daher nur für kurze Tests – nie in produktiven Anwendungen.

Registrierte Apps: App-ID und App-Secret

Wenn du eine App in Billomat registrierst (unter Einstellungen > Administration > Apps), erhältst du zusätzlich eine App-ID und ein App-Secret. Diese müssen bei allen Anfragen dieser App zusätzlich zum API-Schlüssel mitgeschickt werden.

Der Vorteil: Registrierte Apps erhalten ein höheres Rate-Limit-Kontingent – also mehr erlaubte Anfragen pro Zeitintervall. Mehr dazu im Artikel Rate Limiting & Zugriffsbegrenzung.

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
     -H 'X-AppId: {deine-app-id}' \
     -H 'X-AppSecret: {dein-app-secret}' \
  https://{deineBillomatID}.billomat.net/api/clients

Wichtig: Vergisst du, App-ID und App-Secret mitzuschicken, werden deine Anfragen nicht der registrierten App zugeordnet – du nutzt dann das niedrigere Standard-Kontingent, auch wenn eine App registriert ist.

Was passiert bei einem falschen oder fehlenden API-Schlüssel?

Fehlt der API-Schlüssel oder ist er ungültig, antwortet die API mit dem HTTP-Statuscode 401 Unauthorized. Die Fehlermeldung im Response-Body sieht so aus:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Unauthorized</error>
</errors>

Überprüfe in diesem Fall, ob der API-Schlüssel korrekt eingegeben wurde und ob der API-Zugriff für den betreffenden Benutzer unter Einstellungen > Mitarbeiter aktiviert ist.

Nächste Schritte

Jetzt wo du weißt, wie du dich authentifizierst, geht es weiter mit:

Datenformate: XML & JSON – in welchem Format Anfragen und Antworten aufgebaut sind
Daten lesen (GET) – wie du Daten aus Billomat abfragst

Verknüpfung mit