Перейти к содержимому
CargoDuo logoCargoDuo
Цены
Документация для разработчиковСправочник APIПроекты

Создать проект

Создаёт проект, который открывается в приложении: название и, опционально, транспортные средства (сохранённые, по vehicle_id), позиции и группы в формате /v1/pack, а также сохраняемые параметры.

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

Рассчитайте загрузку через POST /v1/projects/{id}/pack. Бесплатно: кредиты не списываются.

Аутентификация

Bearer-ключ API с правомresources:writeПодробнее

Параметры тела

application/json
ИмяТипОбязательноОписание
namestringобязательно
string
Да
≤ 255 chars
vehiclesProjectVehicle[]
ProjectVehicle[]
Нет

Слоты транспортных средств.

itemsItem[]
Item[]
Нет

Позиции груза (не более 500 описаний).

groupsGroup[]
Group[]
Нет

Группы с порядком загрузки.

optionsProjectOptions
ProjectOptions
Нет

Параметры расчёта, которые хранит проект.

Пример запроса

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
      }
    ]
  }'

Пример ответа

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
}

Ответы

  • 201Новый проект.
    ИмяТипОбязательноОписание
    idstring
    string
    Нет

    ID проекта (prj_…).

    objectstring
    string
    Нет
    project
    namestring
    string
    Нет
    statusstring
    string
    Нет

    draft = ещё не рассчитывался или входные данные заменены; calculated = есть текущий план; stale = после расчёта плана изменились настройки.

    draftcalculatedstaleerror
    item_countinteger
    integer
    Нет

    Единиц груза (сумма количеств).

    vehicle_countinteger
    integer
    Нет

    Транспортных средств (сумма количеств).

    app_urlstring
    string
    Нет

    Открывает проект в 3D-редакторе приложения.

    created_byUserRef | null
    UserRef | null
    Нет

    Участник, создавший проект (для вызовов API — участник, создавший ключ). null, если неизвестно.

    updated_byUserRef | null
    UserRef | null
    Нет

    Участник, последним изменивший проект.

    created_atstring
    string
    Нет

    RFC 3339.

    updated_atstring
    string
    Нет

    RFC 3339.

    optionsProjectOptions
    ProjectOptions
    Нет

    Параметры расчёта, которые хранит проект.

    vehiclesProjectVehicle[]
    ProjectVehicle[]
    Нет
    itemsItem[]
    Item[]
    Нет

    Груз в формате Item из /v1/pack; ID вида item_….

    groupsGroup[]
    Group[]
    Нет
    planProjectPlan | null
    ProjectPlan | null
    Нет

    Текущий план; null, если у проекта его нет.

  • 400Bad requestinvalid_json
    • invalid_jsonТело запроса — невалидный JSON, или у поля неверный тип.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI-ключ отсутствует, имеет неверный формат или неизвестен.
    • key_revokedКлюч отозван.
    • key_expiredСрок действия ключа истёк.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 403Forbiddenplan_limit_reachedip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • plan_limit_reachedТариф организации не позволяет создать больше проектов или позиций груза.
    • ip_not_allowedIP-адреса вызывающей стороны нет в списке разрешённых IP для этого ключа.
    • subscription_inactiveУ организации нет активной подписки, включающей API.
    • account_inactiveРабота организации приостановлена, или у неё нет владельца с активной учётной записью.
    • scope_missingУ ключа нет области доступа, необходимой для этого endpoint.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 413Payload too largepayload_too_large
    • payload_too_largeТело запроса превышает 10 MB.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 422Unprocessable entityvalidation_failed
    • validation_failedЗапрос — корректный JSON, но описывает недопустимое задание. В details[] перечислены все проблемы.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 429Too many requestsrate_limited
    • rate_limitedСлишком много запросов за текущую минуту, час или сутки (на ключ или на организацию) либо число неудачных попыток аутентификации с вашего IP-адреса превысило 60 в минуту.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 500Internal server errorinternal_error
    • internal_errorСбой на нашей стороне.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 503Service unavailableapi_disabled
    • api_disabledAPI временно отключён (техническое обслуживание) или выключен для организации.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок