Zum Inhalt springen
EntwicklerdokumentationAPI-ReferenzLadeplanung

Job erstellen

Validiert die Anfrage, reserviert den Höchstpreis aus Ihren Credits und stellt einen Job in die Warteschlange.

POSThttps://runner.cargoduo.com/v1/pack

Antwortet mit 202 und dem Job; fragen Sie GET /v1/jobs/{id} ab oder übergeben Sie ?wait=, um die Antwort bis zum Ende des Jobs zurückzuhalten. Validierungsfehler (422) sind kostenlos und erzeugen keinen Job.

Authentifizierung

Bearer-API-Schlüssel mit Berechtigungpack:writeMehr erfahren

Query-Parameter

NameTypErforderlichBeschreibung
waitinteger
integer
Nein

Wie viele Sekunden die Antwort auf das Ende des Jobs wartet. Rechtzeitig fertig: 200 mit eingebettetem Ergebnis. Sonst: 202.

Standard 00–60

Header-Parameter

NameTypErforderlichBeschreibung
Idempotency-Keystring
string
Nein

Ein beliebiger eindeutiger String, etwa eine UUID oder Ihre Bestellnummer. Derselbe Schlüssel innerhalb von 24 h liefert den ursprünglichen Job, statt einen neuen anzulegen und abzurechnen.

≤ 128 chars

Body-Parameter

application/json
NameTypErforderlichBeschreibung
referencestring
string
Nein

Ihre eigene Referenz (Bestellnummer, Sendungs-ID …). Wird am Job zurückgegeben.

≤ 128 chars
vehiclesVehicle[]erforderlich
Vehicle[]
Ja

Fahrzeugdefinitionen. Jede darf quantity > 1 haben. Mindestens eine.

itemsItem[]erforderlich
Item[]
Ja

Artikeldefinitionen. Jede darf quantity > 1 haben. Mindestens eine.

groupsGroup[]
Group[]
Nein

Optionale Gruppen (Kunden, Stopps, Aufträge). Erforderlich für jede Gruppe, die ein Artikel nennt, wenn options.group_routing nicht "none" ist; andernfalls werden Gruppen aus den Gruppennamen der Artikel in der Reihenfolge ihres Auftretens angelegt.

optionsOptions
Options
Nein

Ladeoptionen. Alle Felder sind optional.

Beispielanfrage

curl -X POST "https://runner.cargoduo.com/v1/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042",
    "vehicles": [
      {
        "id": "trailer",
        "type": "trailer",
        "name": "13.6 m trailer",
        "length": 1360,
        "width": 245,
        "height": 270,
        "max_weight": 24000
      }
    ],
    "items": [
      {
        "id": "pallet-eu",
        "label": "Euro pallet",
        "length": 120,
        "width": 80,
        "height": 140,
        "weight": 450,
        "quantity": 18,
        "stackable": false
      },
      {
        "id": "carton-a",
        "label": "Carton A",
        "length": 60,
        "width": 40,
        "height": 40,
        "weight": 12,
        "quantity": 40,
        "rotation": "upright"
      }
    ],
    "options": {
      "packing_mode": "auto"
    }
  }'

Beispielantwort

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "created_at": "2026-10-19T09:12:03Z",
  "started_at": null,
  "finished_at": null,
  "progress": {
    "stage": "queued",
    "vehicles_done": 0,
    "placed_items": 0
  },
  "summary": {
    "items_requested": 58,
    "items_placed": 0,
    "items_unplaced": 0,
    "vehicles_used": 0,
    "total_weight": 0,
    "volume_utilization": 0,
    "queue_ms": 0,
    "compute_ms": 0
  },
  "cost": {
    "credits": 0,
    "reserved_credits": 1.11,
    "rate_card_version": 1,
    "breakdown": {
      "base": 0,
      "vehicles": 0,
      "compute": 0,
      "large_load": 0
    }
  },
  "error": null,
  "warnings": [],
  "result_url": "https://runner.cargoduo.com/v1/jobs/job_4bK9mT2xQe7LpW1zRc8VdN3f/result",
  "pdf_url": "",
  "expires_at": "2026-11-02T09:12:03Z"
}

Antworten

  • 200OKJob innerhalb von ?wait abgeschlossen, Ergebnis eingebettet. Auch bei einer idempotenten Wiederholung eines abgeschlossenen Jobs.
    NameTypErforderlichBeschreibung
    idstringerforderlich
    string
    Ja

    Job-ID (job_…).

    objectstringerforderlich
    string
    Ja

    Immer job.

    job
    statusstringerforderlich
    string
    Ja

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Nein

    Ihre Referenz aus der Anfrage.

    sourcestring
    string
    Nein

    Wo der Job angelegt wurde.

    apiplayground
    project_idstring
    string
    Nein

    Das Projekt (prj_…), in dem ein Job von POST /v1/projects/{id}/pack seinen Plan speichert. Fehlt bei anderen Jobs.

    created_atstringerforderlich
    string
    Ja

    Zeitstempel nach RFC 3339.

    started_atstring | null
    string | null
    Nein

    Beginn der Berechnung (RFC 3339) oder null.

    finished_atstring | null
    string | null
    Nein

    Ende des Jobs (RFC 3339) oder null.

    progressJobProgress
    JobProgress
    Nein

    Live-Fortschritt, solange der Job wartet oder läuft.

    summaryJobSummary
    JobSummary
    Nein

    Anzahlen und Zeiten.

    costJobCost
    JobCost
    Nein

    Berechnete Credits (endgültig, sobald der Job beendet ist) und die Reservierung während der Laufzeit.

    errorJobError | null
    JobError | null
    Nein

    Warum der Job fehlgeschlagen ist oder abgebrochen wurde; sonst null.

    warningsWarning[]
    Warning[]
    Nein

    Nicht blockierende Hinweise zur Anfrage (auch im Ergebnis wiederholt).

    result_urlstring
    string
    Nein

    Rufen Sie diese URL per GET ab, um das vollständige Ergebnis zu erhalten, sobald status den Wert succeeded hat.

    pdf_urlstring
    string
    Nein

    Ein Browser-Link, der den Ladeplan als PDF erzeugt (3D-Ansichten + Ladeschritte). Gültig bis expires_at. Danach leer.

    expires_atstring
    string
    Nein

    Zeitpunkt, zu dem Anfrage- und Ergebnis-Bodies sowie der PDF-Link gelöscht werden (RFC 3339). Job-Metadaten und Abbuchungen bleiben erhalten.

    resultResult
    Result
    Nein

    Das vollständige Ergebnis, nur eingebettet, wenn angefordert (?include=result) oder wenn POST /v1/pack?wait= rechtzeitig fertig wurde.

  • 202AcceptedJob angenommen (wartend oder laufend).
    NameTypErforderlichBeschreibung
    idstringerforderlich
    string
    Ja

    Job-ID (job_…).

    objectstringerforderlich
    string
    Ja

    Immer job.

    job
    statusstringerforderlich
    string
    Ja

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Nein

    Ihre Referenz aus der Anfrage.

    sourcestring
    string
    Nein

    Wo der Job angelegt wurde.

    apiplayground
    project_idstring
    string
    Nein

    Das Projekt (prj_…), in dem ein Job von POST /v1/projects/{id}/pack seinen Plan speichert. Fehlt bei anderen Jobs.

    created_atstringerforderlich
    string
    Ja

    Zeitstempel nach RFC 3339.

    started_atstring | null
    string | null
    Nein

    Beginn der Berechnung (RFC 3339) oder null.

    finished_atstring | null
    string | null
    Nein

    Ende des Jobs (RFC 3339) oder null.

    progressJobProgress
    JobProgress
    Nein

    Live-Fortschritt, solange der Job wartet oder läuft.

    summaryJobSummary
    JobSummary
    Nein

    Anzahlen und Zeiten.

    costJobCost
    JobCost
    Nein

    Berechnete Credits (endgültig, sobald der Job beendet ist) und die Reservierung während der Laufzeit.

    errorJobError | null
    JobError | null
    Nein

    Warum der Job fehlgeschlagen ist oder abgebrochen wurde; sonst null.

    warningsWarning[]
    Warning[]
    Nein

    Nicht blockierende Hinweise zur Anfrage (auch im Ergebnis wiederholt).

    result_urlstring
    string
    Nein

    Rufen Sie diese URL per GET ab, um das vollständige Ergebnis zu erhalten, sobald status den Wert succeeded hat.

    pdf_urlstring
    string
    Nein

    Ein Browser-Link, der den Ladeplan als PDF erzeugt (3D-Ansichten + Ladeschritte). Gültig bis expires_at. Danach leer.

    expires_atstring
    string
    Nein

    Zeitpunkt, zu dem Anfrage- und Ergebnis-Bodies sowie der PDF-Link gelöscht werden (RFC 3339). Job-Metadaten und Abbuchungen bleiben erhalten.

    resultResult
    Result
    Nein

    Das vollständige Ergebnis, nur eingebettet, wenn angefordert (?include=result) oder wenn POST /v1/pack?wait= rechtzeitig fertig wurde.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonDer Body ist kein gültiges JSON, oder ein Feld hat den falschen Typ.
    • idempotency_key_invalidDer Header Idempotency-Key ist länger als 128 Zeichen.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI-Schlüssel fehlt, ist fehlerhaft oder unbekannt.
    • key_revokedDer Schlüssel wurde widerrufen.
    • key_expiredDer Schlüssel ist abgelaufen.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsDie verfügbaren Credits decken nicht einmal den günstigsten möglichen Lauf dieses Jobs.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedDie aufrufende IP-Adresse steht nicht auf der Allowlist des Schlüssels.
    • subscription_inactiveDie Organisation hat kein aktives Abonnement, das die API enthält.
    • account_inactiveDie Organisation ist gesperrt oder hat keinen Inhaber mit aktivem Konto.
    • scope_missingDem Schlüssel fehlt eine Berechtigung, die dieser Endpoint benötigt.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 413Payload too largepayload_too_large
    • payload_too_largeDer Anfrage-Body ist größer als 10 MB.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 422Unprocessable entityvalidation_failed
    • validation_failedDie Anfrage ist wohlgeformtes JSON, beschreibt aber einen ungültigen Job. details[] listet alle Probleme auf.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsDie Organisation hat bereits die maximale Zahl wartender und laufender Jobs.
    • rate_limitedZu viele Anfragen in der aktuellen Minute, Stunde oder am aktuellen Tag (pro Schlüssel oder pro Organisation) oder mehr als 60 fehlgeschlagene Authentifizierungen pro Minute von Ihrer IP-Adresse.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 500Internal server errorinternal_error
    • internal_errorAuf unserer Seite ist ein Fehler aufgetreten.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes
  • 503Service unavailableapi_disabled
    • api_disabledDie API ist vorübergehend deaktiviert (Wartung) oder für die Organisation abgeschaltet.
    NameTypErforderlichBeschreibung
    errorErrorBodyerforderlich
    ErrorBody
    Ja
    Alle Fehlercodes