1. Schlüssel holen
Melden Sie sich an und erzeugen Sie einen Schlüssel unter /my/api-keys. Schlüssel sehen aus wie tjk_live_… und werden nur einmal angezeigt — speichern Sie sie serverseitig, niemals im Frontend-Code.
2. Erster Aufruf (60 Sekunden)
`` curl -H "Authorization: Bearer $TRACKJET_API_KEY" \ "https://trackjet.world/api/v1/track/TJTEST-DELIVERED" ``
TJTEST-DELIVERED ist eine Sandbox-Fixture — deterministisch, sicher und jedes Mal identisch, sodass Ihr erster Aufruf funktioniert, bevor Sie eine echte Sendung haben.
3. Der Umschlag (Envelope)
Jede JSON-Antwort hat dieselbe Form:
`` { "ok": true, "data": { … }, "meta": { "request_id": "…", "api_version": "v1" } } ``
Fehler sind ok:false mit einem Problem-Objekt (code, message, status). Loggen Sie immer meta.request_id — nennen Sie es in Support-Anfragen, dann finden wir genau diesen Request.
4. Die Endpunkte, die Sie wirklich nutzen werden
GET /api/v1/detect?number=…— welches Format hat diese Nummer?GET /api/v1/track/{number}— Erkennung + Carrier + Tracking-Oberflächen.GET /api/v1/track/{number}/stream— Live-Ereignisse über SSE, wo ein lizenzierter Feed existiert (schließt sonst ehrlich mitno_live_feed).GET /api/v1/carriers— der Katalog.POST /api/v1/webhooks— siehe Webhooks.
Die vollständige Referenz (OpenAPI 3.1, GraphQL, EPCIS) liegt unter /developers/api.
5. Idempotenz & Retries
Schreib-Endpunkte respektieren einen Idempotency-Key-Header: Wiederholen Sie ein abgelaufenes POST mit demselben Schlüssel, wird nie doppelt angelegt. Rate-Limits gelten pro Schlüssel — siehe Rate-Limits & Tarife.
6. GraphQL-Abfragegrenzen
Der GraphQL-Endpoint ist authentifiziert (API-Schlüssel senden) und begrenzt jede Abfrage, damit eine feindliche oder versehentliche Abfrage den Server nicht überlastet:
- Maximale Tiefe: 8. Verschachtelungen über acht Ebenen werden vor der Ausführung abgewiesen.
- Maximale Komplexität: 1000. Jedes aufgelöste Feld kostet 1; eine Abfrage — auch mit Alias-Batching — darf höchstens 1000 Felder auflösen. Eine Abfrage über dem Limit wird als Validierungsfehler abgewiesen, nicht ausgeführt.
Alias-Batching (dasselbe Feld mehrfach unter verschiedenen Aliassen) ist bis zu dieser Komplexitätsgrenze erlaubt, sodass eine einzelne Anfrage nie zu unbegrenzter Arbeit auffächern kann. Zusammen mit dem Rate-Limit pro Schlüssel (Rate-Limits & Tarife) ist der Gesamtdurchsatz durch Komplexität × Anfragen-pro-Minute begrenzt.