v1.0.0

aircargobook API

JSON-API der aircargobook-Plattform — Ratensuche, Frachtenbörse und Angebote.

Über diese API legst du Frachten in der aircargobook-Frachtenbörse an, rufst sie ab,
suchst Trucking-Raten und gibst Angebote ab.

Grundprinzip: `.json` an die URL

Jeder Endpunkt liefert JSON, sobald die URL auf .json endet. Ohne diese Endung
bekommst du die HTML-Oberfläche zurück. Das ist die häufigste Fehlerquelle beim
ersten Integrieren:

✗  POST /freights/add          →  HTML
✓  POST /freights/add.json     →  JSON

Response-Envelope

Alle JSON-Antworten sind gleich verpackt:

{
  "data":   { },
  "status": "error",
  "auth":   { "email": "…", "token": "…", "language": "deu" }
}

⚠️ Wo die Nutzdaten liegen, ist pro Endpunkt verschieden

Es gibt keinen einheitlichen Schlüssel. Verlass dich auf die Tabelle, nicht auf ein
Muster:

Endpunkt	Nutzdaten
`POST /freights/add.json`	`data` — die Fracht liegt flach in `data`, die ID also unter `data.id`
`POST /freights/edit/{id}.json`	`data` (wie beim Anlegen)
`GET /freights/view/{id}.json`	`data.route`
`GET /freights/enlist/{id}.json`	`data.routes` (Array)
`POST /quotes/add.json`	`data.bid`
`POST /pricing/search/results.json`	`data.rates`, `data.combinations`

Beim Anlegen also data.id lesen — nicht data.route.id.

`status` prüfen

status ist "success", wenn der Request durchgelaufen ist, und "error", wenn nicht.
Als Gürtel-und-Hosenträger empfiehlt sich, zusätzlich das erwartete Nutzdatenfeld zu
prüfen — beim Anlegen also data.id.

Formatierte Anzeigefelder (`f_`-Prefix)

Neben den Rohwerten liefern Frachten fertig formatierte Felder für die Anzeige. Die
kannst du direkt in deine Oberfläche schreiben, statt selbst zu formatieren:

Feld	Rohwert	formatiert
`f_from` / `f_to`	`FRA` + `DE`	`FRA (DE)`
`f_eta` / `f_etd`	`2026-09-22 14:00:00`	`2026-09-22 14:00`
`f_eta_end` / `f_etd_end`	`null`	`nicht festgelegt` (in der Sprache des Users)
`caption`	—	`FRA (DE) to MUC (DE) - (Bestellung 4711)`

Zeitangaben kommen in der Zeitzone der Anwendung und ohne Sekunden. Ist ein Wert nicht
gesetzt, steht dort ein übersetzter Platzhaltertext statt null — praktisch für die
Anzeige, unbrauchbar zum Rechnen. Für Logik immer die Rohfelder nehmen, für die
Darstellung die f_-Varianten.

Weitere Anzeigefelder: display_id (Kundenreferenz oder ID), info,
delivery_status_in_words, list_icon, media_types, editable.

f_from und f_to unterliegen derselben Maskierung wie die Rohfelder: bei Frachten,
deren Details du nicht sehen darfst, steht dort xxx (XX).

Fehlerbehandlung

Die Endpunkte werden auch von der Weboberfläche genutzt. Daraus folgen drei
Eigenheiten, die dein Client behandeln muss:

Behandle 3xx und HTML-Antworten als Fehler. Ein fehlgeschlagener Request
antwortet nicht immer mit einem 4xx-JSON — teils kommt ein Redirect auf eine
HTML-Seite. Prüfe daher den Content-Type: alles außer application/json ist ein
Fehlschlag. Setze deinen HTTP-Client so, dass er Redirects nicht automatisch
folgt, sonst siehst du am Ende einen 200 mit HTML-Body.

Einzige Ausnahme: das Ausschreiben einer Fracht antwortet planmäßig mit 302 und
war trotzdem erfolgreich — dort den Zustand per GET nachprüfen.
Prüfe die Antwort gegen das, was du gesendet hast. Beim Anlegen und Ändern von
Frachten werden unbekannte oder falsch typisierte Felder still ignoriert — status
ist trotzdem "success". Ein eta ohne Uhrzeit verschwindet zum Beispiel spurlos.
Vergleiche die zurückgegebene Ressource mit deinem Request.
404 heißt „nicht gefunden oder nicht für dich sichtbar". Frachten anderer
Firmen sind von nicht existierenden nicht unterscheidbar.

Request-Body

Query-Parameter, Formularfelder und JSON-Body werden serverseitig zusammengeführt.
Jedes dokumentierte Body-Feld funktioniert daher auch als application/json, als
application/x-www-form-urlencoded oder als Query-Parameter. Für neue Integrationen
ist application/json die Empfehlung.

Bitte einen User-Agent senden

Schicke, sofern dein HTTP-Client das zulässt, einen aussagekräftigen User-Agent
im Format Softwarename / Version:

User-Agent: MyApplication / 1.0.0

Das hilft uns, Requests deiner Integration bei Rückfragen und Störungen
zuzuordnen — ohne ihn sehen wir nur eine anonyme HTTP-Bibliothek.

Environments

Entwickle immer gegen die Demo-Umgebung. Beide Umgebungen haben getrennte
Datenbestände und getrennte Zugangsdaten — ein Token aus der Demo funktioniert
nicht in der Produktion.

Umgebung	Basis-URL
Demo / Integration	`https://demo.aircargobook.com`
Produktion	`https://www.aircargobook.com`

Contact

aircargobook Support/support@aircargobook.com

Servers

https://demo.aircargobook.comDemo / Integration — hier entwickeln und testen

https://www.aircargobook.comProduktion

Die Spec verwenden

Die vollständige OpenAPI-3.1-Spec liegt unter /openapi.json und lässt sich direkt in Postman, Insomnia oder Bruno importieren.

Typisierten Client generieren:

bash

# TypeScript
npx openapi-typescript https://docs.aircargobook.com/openapi.json -o src/acb-api.d.ts

# Python
openapi-python-client generate --url https://docs.aircargobook.com/openapi.json

# PHP / Java / weitere
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.aircargobook.com/openapi.json -g php -o ./acb-client

Wo fange ich an?

Ich will …	Hier
einen Token holen	Auth
eine Fracht anlegen und ausschreiben	Freights — oder erst das Kochbuch
Angebote zu meiner Fracht abrufen	`GET /freights/view/{id}.json` → `_bids`, siehe Freights
ein Angebot abgeben	Quotes
Trucking-Raten suchen	Pricing

Vorher lesen

Konventionen erklärt Envelope, Fehlerbehandlung und Datumsformate — das gilt für jeden Endpunkt hier und ist einmal zu lesen deutlich billiger als pro Endpunkt herauszufinden.

aircargobook API​

Grundprinzip: .json an die URL