API Docs

Erscheinungsbild

Authentifizierung ​

Jeder Request außer dem Login selbst braucht einen API-Token. Du holst ihn einmal und verwendest ihn dauerhaft wieder.

1. Token holen ​

bash
curl -X POST "https://demo.aircargobook.com/users/login.json" \
  -H "User-Agent: MyApplication / 1.0.0" \
  -d "auth[user]=me@example.com" \
  -d "auth[password]=geheim"

Antwort:

json
{
  "status": "success",
  "auth": {
    "email": "me@example.com",
    "token": "8f14e45fceea167a5a36dedd4bea2543",
    "language": "deu"
  }
}

auth.token ist dein API-Token.

Login prüfen

Ein fehlgeschlagener Login antwortet ebenfalls mit HTTP 200 — dann allerdings mit "status": "error" und ohne auth-Block.

Prüfe deshalb, dass auth.token vorhanden und nicht leer ist. Das ist der verlässliche Test.

Der Login ist einer der wenigen Endpunkte, bei denen status tatsächlich etwas aussagt. Bei den meisten anderen steht es auch bei Erfolg auf "error" — verlass dich dort nicht darauf, siehe Konventionen.

Als JSON geht es genauso:

bash
curl -X POST "https://demo.aircargobook.com/users/login.json" \
  -H "Content-Type: application/json" \
  -d '{"auth": {"user": "me@example.com", "password": "geheim"}}'

2. Token verwenden ​

Der empfohlene Weg ist der Authorization-Header. Das Schema heißt ApplePass — historisch bedingt, aber es muss genau so lauten:

bash
curl "https://demo.aircargobook.com/freights/view/12345.json" \
  -H "Authorization: ApplePass 8f14e45fceea167a5a36dedd4bea2543" \
  -H "User-Agent: MyApplication / 1.0.0"

Alternativ als Query-Parameter — praktisch für schnelle Tests:

bash
curl "https://demo.aircargobook.com/freights/view/12345.json?auth_token=8f14e45..."

Query-Parameter nicht produktiv nutzen

?auth_token= landet in Server-Logs, Proxy-Logs und Browser-Referrern. Für alles, was dauerhaft läuft, den Header verwenden.

Der Token läuft nicht ab ​

Es gibt kein Refresh, kein Ablaufdatum und keine Rotation. Daraus folgt:

Rufe /users/login.json nicht vor jedem Request auf. Hole den Token einmal, lege ihn als Secret ab (Umgebungsvariable, Secrets Manager, Vault) und verwende ihn wieder. Ein Login pro API-Aufruf ist die häufigste Fehlkonfiguration und belastet beide Seiten ohne Nutzen.

Behandle den Token wie ein Passwort. Er ist unbefristet gültig und an einen Benutzer mit allen dessen Rechten gebunden. Nicht ins Repository, nicht ins Frontend, nicht in Logs. Wenn er kompromittiert wurde, melde dich bei support@aircargobook.com — wir setzen einen neuen. Der alte wird dabei ungültig.

Dein Benutzer braucht eine Firma ​

Frachten werden immer der Firma zugeordnet, zu der dein Benutzer gehört (route.company). Ein Benutzer ohne Firmenzuordnung kann keine Frachten anlegen.

Du kannst auch nicht im Namen einer anderen Firma anlegen — es gibt keinen Parameter dafür. Wenn deine Integration Frachten für mehrere Firmen erzeugen soll, brauchst du pro Firma einen eigenen Benutzer und damit einen eigenen Token.

Fehlerbilder ​

SymptomUrsache
401, {"status": "error"}Token fehlt, ist falsch, oder stammt aus der anderen Umgebung
200 mit HTML-Body.json an der URL vergessen
3xx auf eine HTML-SeiteToken gültig, aber keine Berechtigung für diese Aktion
Fracht wird angelegt, gehört aber der falschen FirmaToken gehört zu einem Benutzer in einer anderen Firma

Weiter ​