Przejdź do treści
Dokumentacja dla deweloperówDokumentacja APIProjekty

Zaplanuj załadunek projektu

Planuje załadunek pojazdów i pozycji projektu dokładnie tak jak POST /v1/pack: ta sama cena, rezerwacja kredytów, limity, Idempotency-Key, ?wait= i zadanie.

POSThttps://runner.cargoduo.com/v1/projects/{id}/pack

Gdy zadanie zakończy się sukcesem, jego plan zostaje zapisany w projekcie, który potem otwiera się w aplikacji z tym planem. Jeśli projekt zmienił się w trakcie zadania, plan zostaje tylko przy zadaniu (ostrzeżenie project_not_saved). ID w wyniku pochodzą z projektu: vehicle_id to ID slotu (pv_…), a item_id to ID pozycji (item_…).

Uwierzytelnianie

Klucz API (Bearer) z zakresempack:writeresources:writeWięcej informacji

Parametry ścieżki

NazwaTypWymaganyOpis
idstringwymagane
string
Tak

ID projektu (prj_…).

Parametry zapytania

NazwaTypWymaganyOpis
waitinteger
integer
Nie

Ile sekund wstrzymać odpowiedź w oczekiwaniu na zakończenie zadania. Zakończone na czas: 200 z wynikiem w odpowiedzi. W przeciwnym razie: 202.

Domyślnie 00–60

Parametry nagłówka

NazwaTypWymaganyOpis
Idempotency-Keystring
string
Nie

Dowolny unikalny ciąg znaków, np. UUID lub numer Twojego zamówienia. Ten sam klucz w ciągu 24 h zwraca pierwotne zadanie zamiast tworzyć i rozliczać nowe.

≤ 128 chars

Parametry treści

application/json
NazwaTypWymaganyOpis
referencestring
string
Nie

Twój numer referencyjny, zwracany w zadaniu. Domyślnie nazwa projektu.

≤ 128 chars
optionsProjectPackOptions
ProjectPackOptions
Nie

Opcje uruchomienia. Wszystkie pola są opcjonalne.

Przykładowe zapytanie

curl -X POST "https://runner.cargoduo.com/v1/projects/prj_3051/pack" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Idempotency-Key: order-1042-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1042"
  }'

Przykładowa odpowiedź

202 Accepted · Job
{
  "id": "job_4bK9mT2xQe7LpW1zRc8VdN3f",
  "object": "job",
  "status": "queued",
  "reference": "order-1042",
  "source": "api",
  "project_id": "prj_3051",
  "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"
}

Odpowiedzi

  • 200OKZadanie zakończyło się w czasie ?wait, wynik jest w odpowiedzi. Także idempotentne powtórzenie zakończonego zadania.
    NazwaTypWymaganyOpis
    idstringwymagane
    string
    Tak

    ID zadania (job_…).

    objectstringwymagane
    string
    Tak

    Zawsze job.

    job
    statusstringwymagane
    string
    Tak

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Nie

    Twój numer referencyjny z zapytania.

    sourcestring
    string
    Nie

    Gdzie utworzono zadanie.

    apiplayground
    project_idstring
    string
    Nie

    Projekt (prj_…), w którym zadanie POST /v1/projects/{id}/pack zapisuje swój plan. Brak w innych zadaniach.

    created_atstringwymagane
    string
    Tak

    Znacznik czasu RFC 3339.

    started_atstring | null
    string | null
    Nie

    Kiedy rozpoczęły się obliczenia (RFC 3339), albo null.

    finished_atstring | null
    string | null
    Nie

    Kiedy zadanie się zakończyło (RFC 3339), albo null.

    progressJobProgress
    JobProgress
    Nie

    Bieżący postęp, gdy zadanie czeka w kolejce lub jest w toku.

    summaryJobSummary
    JobSummary
    Nie

    Liczniki i czasy.

    costJobCost
    JobCost
    Nie

    Pobrane kredyty (ostateczne po zakończeniu zadania) i rezerwacja utrzymywana w trakcie jego trwania.

    errorJobError | null
    JobError | null
    Nie

    Dlaczego zadanie zakończyło się błędem lub zostało anulowane; w przeciwnym razie null.

    warningsWarning[]
    Warning[]
    Nie

    Uwagi do zapytania, które nie blokują zadania (powtórzone także w wyniku).

    result_urlstring
    string
    Nie

    Wywołaj GET na ten URL, aby pobrać pełny wynik, gdy status ma wartość succeeded.

    pdf_urlstring
    string
    Nie

    Link otwierany w przeglądarce, który generuje plan załadunku jako PDF (widoki 3D + kroki załadunku). Ważny do expires_at. Po wygaśnięciu pusty.

    expires_atstring
    string
    Nie

    Kiedy treści zapytania i wyniku oraz link do PDF zostaną usunięte (RFC 3339). Metadane zadania i opłaty są zachowywane.

    resultResult
    Result
    Nie

    Pełny wynik, dołączany tylko na żądanie (?include=result) lub gdy POST /v1/pack?wait= zakończy się na czas.

  • 202AcceptedZadanie przyjęte (w kolejce lub w toku).
    NazwaTypWymaganyOpis
    idstringwymagane
    string
    Tak

    ID zadania (job_…).

    objectstringwymagane
    string
    Tak

    Zawsze job.

    job
    statusstringwymagane
    string
    Tak

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Nie

    Twój numer referencyjny z zapytania.

    sourcestring
    string
    Nie

    Gdzie utworzono zadanie.

    apiplayground
    project_idstring
    string
    Nie

    Projekt (prj_…), w którym zadanie POST /v1/projects/{id}/pack zapisuje swój plan. Brak w innych zadaniach.

    created_atstringwymagane
    string
    Tak

    Znacznik czasu RFC 3339.

    started_atstring | null
    string | null
    Nie

    Kiedy rozpoczęły się obliczenia (RFC 3339), albo null.

    finished_atstring | null
    string | null
    Nie

    Kiedy zadanie się zakończyło (RFC 3339), albo null.

    progressJobProgress
    JobProgress
    Nie

    Bieżący postęp, gdy zadanie czeka w kolejce lub jest w toku.

    summaryJobSummary
    JobSummary
    Nie

    Liczniki i czasy.

    costJobCost
    JobCost
    Nie

    Pobrane kredyty (ostateczne po zakończeniu zadania) i rezerwacja utrzymywana w trakcie jego trwania.

    errorJobError | null
    JobError | null
    Nie

    Dlaczego zadanie zakończyło się błędem lub zostało anulowane; w przeciwnym razie null.

    warningsWarning[]
    Warning[]
    Nie

    Uwagi do zapytania, które nie blokują zadania (powtórzone także w wyniku).

    result_urlstring
    string
    Nie

    Wywołaj GET na ten URL, aby pobrać pełny wynik, gdy status ma wartość succeeded.

    pdf_urlstring
    string
    Nie

    Link otwierany w przeglądarce, który generuje plan załadunku jako PDF (widoki 3D + kroki załadunku). Ważny do expires_at. Po wygaśnięciu pusty.

    expires_atstring
    string
    Nie

    Kiedy treści zapytania i wyniku oraz link do PDF zostaną usunięte (RFC 3339). Metadane zadania i opłaty są zachowywane.

    resultResult
    Result
    Nie

    Pełny wynik, dołączany tylko na żądanie (?include=result) lub gdy POST /v1/pack?wait= zakończy się na czas.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonTreść nie jest prawidłowym JSON-em lub pole ma niewłaściwy typ.
    • idempotency_key_invalidNagłówek Idempotency-Key jest dłuższy niż 128 zn.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedBrak klucza API, nieprawidłowy format klucza lub nieznany klucz.
    • key_revokedKlucz został unieważniony.
    • key_expiredKlucz utracił ważność.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsDostępne kredyty nie pokrywają najtańszego możliwego przebiegu tego zadania.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • ip_not_allowedAdresu IP, z którego przyszło wywołanie, nie ma na liście dozwolonych adresów klucza.
    • subscription_inactiveOrganizacja nie ma aktywnej subskrypcji obejmującej API.
    • account_inactiveOrganizacja jest zawieszona albo nie ma właściciela z aktywnym kontem.
    • scope_missingKlucz nie ma zakresu wymaganego przez ten endpoint.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 404Not foundproject_not_found
    • project_not_foundW Twojej organizacji nie ma projektu o tym ID.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 409Conflictproject_busy
    • project_busyDla projektu właśnie trwa planowanie załadunku (w aplikacji lub w innym zadaniu).
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 413Payload too largepayload_too_large
    • payload_too_largeTreść zapytania przekracza 10 MB.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 422Unprocessable entityvalidation_failed
    • validation_failedZapytanie to poprawny składniowo JSON, ale opisuje nieprawidłowe zadanie. details[] zawiera wszystkie problemy.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 429Too many requeststoo_many_jobsrate_limited
    • too_many_jobsOrganizacja ma już maksymalną liczbę zadań w kolejce i w toku.
    • rate_limitedZa dużo zapytań w bieżącej minucie, godzinie lub dobie (na klucz lub na organizację) albo przekroczony limit nieudanych uwierzytelnień z Twojego adresu IP (60 na minutę).
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 500Internal server errorinternal_error
    • internal_errorWystąpił błąd po naszej stronie.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów
  • 503Service unavailableapi_disabled
    • api_disabledAPI jest tymczasowo wyłączone (prace konserwacyjne) lub wyłączone dla organizacji.
    NazwaTypWymaganyOpis
    errorErrorBodywymagane
    ErrorBody
    Tak
    Wszystkie kody błędów