---
title: API-Schnellstart
description: Legen Sie über die API ein Projekt an, importieren Sie Fracht, starten Sie eine Berechnung und lesen Sie den Ladeplan, mit Postman oder curl.
---

Diese Anleitung führt Sie in acht Schritten von einem API-Schlüssel zu einem Ladeplan und einem Freigabelink. Nutzen Sie sie, um zu prüfen, dass Ihre Integration durchgängig funktioniert. Die [Referenz der Persistenz-API](/de/overview/persistence-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.

## API-Schlüssel erstellen

1. ### Schlüssel anlegen

    Ö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.

2. ### Client wählen

    **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.

    ```bash
    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.

## Ablauf durchspielen

1. ### Projekt anlegen

    ```bash
    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`.

2. ### Ladeplan anlegen

    Ein Projekt beginnt ohne Ladeplan.

    ```bash
    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`.

3. ### Fracht importieren

    Längen sind Millimeter und Gewichte Gramm. Eine Anfrage nimmt bis zu 5.000 Zeilen und wird ganz oder gar nicht angehängt.

    ```bash
    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 }`.

4. ### Laderaum setzen

    Wählen Sie Laderaum-Typen aus der Bibliothek. Die eingebauten See- und Straßentypen sind enthalten.

    ```bash
    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 Ladeplans und senden Sie beides:

    ```bash
    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 Ladeplan zwischenzeitlich geändert, antwortet der Aufruf mit `412` und speichert nichts. Lesen Sie erneut und versuchen Sie es noch einmal.

5. ### Berechnung einreihen

    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.

    ```bash
    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`:

    ```json
    { "id": "cm9x2k", "status": "queued", "loadPlanId": "cm9w7p" }
    ```

    Merken Sie sich `id` als `CALCULATE_ID`.

6. ### Auf das Ergebnis warten

    Fragen Sie den Lauf ab, bis `status` nicht mehr `queued` oder `running` ist:

    ```bash
    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](/de/overview/persistence-api#limits).

    Um das Abfragen zu sparen, registrieren Sie einen Webhook-Endpunkt und warten Sie auf `calculate.completed`. Die [Webhooks-Anleitung](/de/guides/webhooks) behandelt Einrichtung und Signaturprüfung. Das Ereignis nennt den Ladeplan, den Sie im nächsten Schritt lesen.

7. ### Ladeplan lesen

    ```bash
    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.

8. ### Freigabelink erstellen

    ```bash
    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`.

## Fehler und Limits behandeln

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 Ladeplan geändert hat, lesen Sie seine `revision` also erneut. Budgets, Fehlercodes und Idempotenzregeln stehen in der [Referenz](/de/overview/persistence-api#limits).

## Wie es weitergeht

- Erzeugen Sie aus `/api/v1/spec.json` einen typisierten Client, oder stöbern Sie in der Referenz unter `/api/v1` und probieren Sie jede Route aus.
- Erhalten Sie Berechnungsergebnisse per [Webhook](/de/guides/webhooks), statt abzufragen.
- Lesen Sie die [Referenz der Persistenz-API](/de/overview/persistence-api) zu Umfängen, Ablauf von Schlüsseln, seitenweisem Lesen und Versionierung.