Anleitungen
Legen Sie über die API ein Projekt an, importieren Sie Fracht, starten Sie eine Berechnung und lesen Sie den Load Plan, mit Postman oder curl.
Diese Anleitung führt Sie in acht Schritten von einem API-Schlüssel zu einem Load Plan und einem Share Link. Nutzen Sie sie, um zu prüfen, dass Ihre Integration durchgängig funktioniert. Die Referenz der Persistenz-API behandelt jede Route, jedes Feld und jeden Fehler.
Bevor Sie beginnen
Der API-Zugriff braucht den Enterprise-Plan und die Rolle Owner oder Admin, die Rollen, die API-Schlüssel verwalten. Sandbox- oder Testschlüssel gibt es noch nicht. Jede Anfrage wirkt auf Ihre echte Organisation. Probieren Sie den Ablauf deshalb an einem Wegwerf-Projekt aus.
Öffnen Sie Einstellungen → API-Schlüssel und erstellen Sie einen Schlüssel mit dem Umfang Lesen und schreiben. Das Geheimnis beginnt mit sc_live_ und wird nur einmal angezeigt. Kopieren Sie es sofort.
Postman. Wählen Sie Import, dann Link, und fügen Sie https://<ihre-app>/api/v1/postman.json ein. Der Server baut diese Collection aus demselben OpenAPI-Dokument wie /api/v1/spec.json, sie stimmt also immer mit der API überein. Öffnen Sie die Collection, dann Variables, und tragen Sie Ihren Schlüssel in den Current value von apiKey ein. baseUrl ist schon gesetzt. Jede Anfrage erbt das Bearer-Token. Die Anfragen, die einen Idempotency-Key brauchen, füllen bei jedem Senden einen neuen aus.
curl. Setzen Sie zwei Variablen und senden Sie dieselben Anfragen wie in den Schritten unten.
export ORIGIN="https://app.example.com"
export CARGO_MARSHAL_API_KEY="sc_live_…"Die Schritte unten zeigen curl. Öffnen Sie in Postman die Anfrage mit derselben Methode und demselben Pfad, füllen Sie die Pfadvariablen aus und senden Sie sie.
curl -sS -X POST "$ORIGIN/api/v1/projects" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Idempotency-Key: quickstart-project-1" \
-H "Content-Type: application/json" \
-d '{"name":"Hamburg 40HC","transportMode":"sea"}'Der Aufruf antwortet mit 201 und dem Projekt. Merken Sie sich seine id als PROJECT_ID.
Ein Projekt beginnt ohne Load Plan.
curl -sS -X POST "$ORIGIN/api/v1/projects/$PROJECT_ID/load-plans" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Idempotency-Key: quickstart-plan-1" \
-H "Content-Type: application/json" \
-d '{"name":"Plan A"}'Die Antwort ist 201 mit id, revision, stale und einer leeren Liste equipment. Merken Sie sich die id als LOAD_PLAN_ID.
Längen sind Millimeter und Gewichte Gramm. Eine Anfrage nimmt bis zu 5.000 Zeilen und wird ganz oder gar nicht angehängt.
curl -sS -X POST "$ORIGIN/api/v1/projects/$PROJECT_ID/cargo" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Idempotency-Key: quickstart-cargo-1" \
-H "Content-Type: application/json" \
-d '{"lines":[{"name":"Euro pallet","quantity":12,"lengthMm":1200,"widthMm":800,"heightMm":1100,"weightG":250000}]}'Der Aufruf antwortet mit 201 und { "count": 1 }.
Wählen Sie Equipment-Typen aus der Bibliothek. Die eingebauten See- und Straßentypen sind enthalten.
curl -sS "$ORIGIN/api/v1/libraries/equipment?mode=sea&limit=10" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY"Nehmen Sie die id eines Typs aus items, lesen Sie mit GET /load-plans/$LOAD_PLAN_ID die aktuelle revision des Load Plans und senden Sie beides:
curl -sS -X PATCH "$ORIGIN/api/v1/load-plans/$LOAD_PLAN_ID/equipment" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":3,"equipmentTypeIds":["cm8x2k4f70001qz0h3m5v6b7n"]}'Die Antwort enthält die neue revision und die Zeilen in equipment. Hat jemand den Load Plan zwischenzeitlich geändert, antwortet der Aufruf mit 412 und speichert nichts. Lesen Sie erneut und versuchen Sie es noch einmal.
Lesen Sie die aktuelle revision noch einmal und reihen Sie dann ein. Eine Wiederholung mit demselben Idempotency-Key liefert die erste Antwort, statt einen zweiten Lauf zu starten.
curl -sS -X POST "$ORIGIN/api/v1/load-plans/$LOAD_PLAN_ID/calculate" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Idempotency-Key: quickstart-calculate-1" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":4}'Der Aufruf antwortet mit 202:
{ "id": "cm9x2k", "status": "queued", "loadPlanId": "cm9w7p" }Merken Sie sich id als CALCULATE_ID.
Fragen Sie den Lauf ab, bis status nicht mehr queued oder running ist:
curl -sS "$ORIGIN/api/v1/calculates/$CALCULATE_ID" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY"Der Lauf endet als completed, failed, cancelled oder timed_out. Während er läuft, zeigen phase, processedItems und totalItems den Fortschritt. Ein fehlgeschlagener Lauf trägt einen failureCode. Fragen Sie alle paar Sekunden ab, nicht in einer engen Schleife, denn es gelten Limits.
Um das Abfragen zu sparen, registrieren Sie einen Webhook-Endpunkt und warten Sie auf calculate.completed. Die Webhooks-Anleitung behandelt Einrichtung und Signaturprüfung. Das Ereignis nennt den Load Plan, den Sie im nächsten Schritt lesen.
curl -sS "$ORIGIN/api/v1/load-plans/$LOAD_PLAN_ID" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY"Ist resultStatus gleich solved, enthält result die Felder units, placements, totals, warnings und unloaded. Fracht, die nicht passte, steht mit einem Grund in unloaded. Prüfen Sie warnings und, wenn vorhanden, axleWarnings und stopWarnings, bevor Sie nach dem Plan handeln.
curl -sS -X POST "$ORIGIN/api/v1/load-plans/$LOAD_PLAN_ID/share-links" \
-H "Authorization: Bearer $CARGO_MARSHAL_API_KEY" \
-H "Idempotency-Key: quickstart-share-1" \
-H "Content-Type: application/json" \
-d '{"expiresAt":"2026-12-31T23:59:59Z"}'Die Antwort enthält eine url nur zum Ansehen. url und token erscheinen nur in dieser Antwort, speichern Sie sie also. Eine Wiederholung derselben Anfrage liefert für beide null.
Jeder Fehler hat denselben JSON-Body. Verzweigen Sie nach code und, wo gesetzt, nach data.reason, nie nach message. Heben Sie den Antwort-Header x-request-id für den Support auf.
Wiederholen Sie ein 429 nach der Zahl der Sekunden in Retry-After. Wiederholen Sie ein 503 mit Backoff. Ein 412 heißt, dass sich der Load Plan geändert hat, lesen Sie seine revision also erneut. Budgets, Fehlercodes und Idempotenzregeln stehen in der Referenz.
/api/v1/spec.json einen typisierten Client, oder stöbern Sie in der Referenz unter /api/v1 und probieren Sie jede Route aus.