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

Utwórz projekt

Tworzy projekt, który otwiera się w aplikacji. Podajesz nazwę oraz opcjonalnie pojazdy (zapisane pojazdy wskazane przez vehicle_id), pozycje i grupy w formacie /v1/pack, a także zapisywane opcje.

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

Plan załadunku obliczysz przez POST /v1/projects/{id}/pack. Bezpłatnie: nie pobieramy kredytów.

Uwierzytelnianie

Klucz API (Bearer) z zakresemresources:writeWięcej informacji

Parametry treści

application/json
NazwaTypWymaganyOpis
namestringwymagane
string
Tak
≤ 255 chars
vehiclesProjectVehicle[]
ProjectVehicle[]
Nie

Sloty pojazdów.

itemsItem[]
Item[]
Nie

Pozycje ładunku (maks. 500 definicji).

groupsGroup[]
Group[]
Nie

Grupy wraz z kolejnością załadunku.

optionsProjectOptions
ProjectOptions
Nie

Opcje załadunku zapisane w projekcie.

Przykładowe zapytanie

curl -X POST "https://runner.cargoduo.com/v1/projects" \
  -H "Authorization: Bearer $CARGODUO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order 1042",
    "vehicles": [
      {
        "vehicle_id": "standard-trailer-13-6m"
      }
    ],
    "items": [
      {
        "template_id": "tpl_42",
        "quantity": 18
      },
      {
        "template_id": "tpl_43",
        "quantity": 40
      }
    ]
  }'

Przykładowa odpowiedź

201 · Project
{
  "id": "prj_3051",
  "object": "project",
  "name": "Order 1042",
  "status": "draft",
  "item_count": 58,
  "vehicle_count": 1,
  "app_url": "https://app.cargoduo.com/projects/3051",
  "created_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "updated_by": {
    "id": "usr_7",
    "name": "Elif Kaya"
  },
  "created_at": "2026-10-19T09:10:03Z",
  "updated_at": "2026-10-19T09:10:03Z",
  "options": {
    "packing_mode": "auto",
    "group_routing": "none",
    "allow_overweight": false
  },
  "vehicles": [
    {
      "id": "pv_5120",
      "vehicle_id": "standard-trailer-13-6m",
      "name": "Standard Trailer (13.6m)",
      "type": "trailer",
      "quantity": 1,
      "length": 1362,
      "width": 248,
      "height": 270,
      "max_weight": 24000
    }
  ],
  "items": [
    {
      "id": "item_88410",
      "label": "Euro pallet",
      "shape": "box",
      "length": 120,
      "width": 80,
      "height": 140,
      "weight": 450,
      "quantity": 18,
      "stackable": false,
      "rotation": "all",
      "color": "#3b82f6"
    },
    {
      "id": "item_88411",
      "label": "Carton A",
      "shape": "box",
      "length": 60,
      "width": 40,
      "height": 40,
      "weight": 12,
      "quantity": 40,
      "stackable": true,
      "rotation": "upright",
      "color": "#f59e0b"
    }
  ],
  "groups": [],
  "plan": null
}

Odpowiedzi

  • 201Nowy projekt.
    NazwaTypWymaganyOpis
    idstring
    string
    Nie

    ID projektu (prj_…).

    objectstring
    string
    Nie
    project
    namestring
    string
    Nie
    statusstring
    string
    Nie

    draft = załadunku nigdy nie zaplanowano lub zastąpiono dane wejściowe; calculated = ma bieżący plan; stale = od utworzenia planu zmieniono ustawienie.

    draftcalculatedstaleerror
    item_countinteger
    integer
    Nie

    Liczba sztuk (suma ilości).

    vehicle_countinteger
    integer
    Nie

    Liczba pojazdów (suma ilości).

    app_urlstring
    string
    Nie

    Otwiera projekt w edytorze 3D aplikacji.

    created_byUserRef | null
    UserRef | null
    Nie

    Członek organizacji, który go utworzył (przy wywołaniach API: twórca klucza). null, gdy nieznany.

    updated_byUserRef | null
    UserRef | null
    Nie

    Członek organizacji, który ostatnio go zmienił.

    created_atstring
    string
    Nie

    RFC 3339.

    updated_atstring
    string
    Nie

    RFC 3339.

    optionsProjectOptions
    ProjectOptions
    Nie

    Opcje załadunku zapisane w projekcie.

    vehiclesProjectVehicle[]
    ProjectVehicle[]
    Nie
    itemsItem[]
    Item[]
    Nie

    Ładunek w formacie Item z /v1/pack; ID mają postać item_….

    groupsGroup[]
    Group[]
    Nie
    planProjectPlan | null
    ProjectPlan | null
    Nie

    Bieżący plan; null, gdy projekt go nie ma.

  • 400Bad requestinvalid_json
    • invalid_jsonTreść nie jest prawidłowym JSON-em lub pole ma niewłaściwy typ.
    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
  • 403Forbiddenplan_limit_reachedip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • plan_limit_reachedPakiet organizacji nie pozwala na więcej projektów ani pozycji ładunku.
    • 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
  • 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 requestsrate_limited
    • 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