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

Создать задание на расчёт загрузки

Проверяет запрос, резервирует кредиты по максимально возможной стоимости и ставит задание в очередь.

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

Отвечает 202 с заданием; затем опрашивайте GET /v1/jobs/{id} или передайте ?wait=, чтобы ответ пришёл после завершения задания. Ошибки валидации (422) бесплатны и не создают задание.

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

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

Параметры запроса

ИмяТипОбязательноОписание
waitinteger
integer
Нет

Сколько секунд ждать завершения задания, прежде чем ответить. Если задание успело завершиться — 200 с результатом в теле ответа, иначе — 202.

По умолчанию 00–60

Параметры заголовков

ИмяТипОбязательноОписание
Idempotency-Keystring
string
Нет

Любая уникальная строка, например UUID или номер вашего заказа. Повторный запрос с тем же ключом в течение 24 ч вернёт исходное задание — новое не создаётся и не оплачивается.

≤ 128 chars

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

application/json
ИмяТипОбязательноОписание
referencestring
string
Нет

Ваш собственный идентификатор (номер заказа, ID отправки…). Возвращается в задании.

≤ 128 chars
vehiclesVehicle[]обязательно
Vehicle[]
Да

Описания транспортных средств. У каждого может быть quantity > 1. Минимум одно.

itemsItem[]обязательно
Item[]
Да

Описания позиций. У каждой может быть quantity > 1. Минимум одна.

groupsGroup[]
Group[]
Нет

Необязательные группы (клиенты, точки доставки, заказы). Если options.group_routing не "none", они обязательны для каждой группы, указанной в позициях; иначе группы создаются из названий групп в позициях в порядке появления.

optionsOptions
Options
Нет

Параметры расчёта загрузки. Все поля необязательны.

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

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

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

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"
}

Ответы

  • 200OKЗадание завершилось в пределах ?wait, результат встроен в ответ. Так же отвечает идемпотентный повтор завершённого задания.
    ИмяТипОбязательноОписание
    idstringобязательно
    string
    Да

    ID задания (job_…).

    objectstringобязательно
    string
    Да

    Всегда job.

    job
    statusstringобязательно
    string
    Да

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Нет

    Ваш идентификатор из запроса.

    sourcestring
    string
    Нет

    Где создано задание.

    apiplayground
    project_idstring
    string
    Нет

    Проект (prj_…), в который задание POST /v1/projects/{id}/pack сохраняет свой план. У других заданий отсутствует.

    created_atstringобязательно
    string
    Да

    Метка времени RFC 3339.

    started_atstring | null
    string | null
    Нет

    Когда начались вычисления (RFC 3339), или null.

    finished_atstring | null
    string | null
    Нет

    Когда задание завершилось (RFC 3339), или null.

    progressJobProgress
    JobProgress
    Нет

    Текущий прогресс, пока задание в очереди или выполняется.

    summaryJobSummary
    JobSummary
    Нет

    Счётчики и время.

    costJobCost
    JobCost
    Нет

    Списанные кредиты (окончательные после завершения задания) и резерв, удерживаемый во время выполнения.

    errorJobError | null
    JobError | null
    Нет

    Почему задание завершилось ошибкой или было отменено; иначе null.

    warningsWarning[]
    Warning[]
    Нет

    Некритичные замечания к запросу (дублируются в результате).

    result_urlstring
    string
    Нет

    Выполните GET по этому URL, чтобы получить полный результат, когда status станет succeeded.

    pdf_urlstring
    string
    Нет

    Ссылка, по которой браузер формирует PDF с планом загрузки (3D-виды + шаги загрузки). Действует до expires_at. После истечения срока пустая.

    expires_atstring
    string
    Нет

    Когда удаляются тела запроса и результата и ссылка на PDF (RFC 3339). Метаданные задания и списания сохраняются.

    resultResult
    Result
    Нет

    Полный результат; встраивается, только если запрошен (?include=result) или если POST /v1/pack?wait= успел завершиться.

  • 202AcceptedЗадание принято (в очереди или выполняется).
    ИмяТипОбязательноОписание
    idstringобязательно
    string
    Да

    ID задания (job_…).

    objectstringобязательно
    string
    Да

    Всегда job.

    job
    statusstringобязательно
    string
    Да

    queued → running → succeeded | failed | canceled.

    queuedrunningsucceededfailedcanceled
    referencestring
    string
    Нет

    Ваш идентификатор из запроса.

    sourcestring
    string
    Нет

    Где создано задание.

    apiplayground
    project_idstring
    string
    Нет

    Проект (prj_…), в который задание POST /v1/projects/{id}/pack сохраняет свой план. У других заданий отсутствует.

    created_atstringобязательно
    string
    Да

    Метка времени RFC 3339.

    started_atstring | null
    string | null
    Нет

    Когда начались вычисления (RFC 3339), или null.

    finished_atstring | null
    string | null
    Нет

    Когда задание завершилось (RFC 3339), или null.

    progressJobProgress
    JobProgress
    Нет

    Текущий прогресс, пока задание в очереди или выполняется.

    summaryJobSummary
    JobSummary
    Нет

    Счётчики и время.

    costJobCost
    JobCost
    Нет

    Списанные кредиты (окончательные после завершения задания) и резерв, удерживаемый во время выполнения.

    errorJobError | null
    JobError | null
    Нет

    Почему задание завершилось ошибкой или было отменено; иначе null.

    warningsWarning[]
    Warning[]
    Нет

    Некритичные замечания к запросу (дублируются в результате).

    result_urlstring
    string
    Нет

    Выполните GET по этому URL, чтобы получить полный результат, когда status станет succeeded.

    pdf_urlstring
    string
    Нет

    Ссылка, по которой браузер формирует PDF с планом загрузки (3D-виды + шаги загрузки). Действует до expires_at. После истечения срока пустая.

    expires_atstring
    string
    Нет

    Когда удаляются тела запроса и результата и ссылка на PDF (RFC 3339). Метаданные задания и списания сохраняются.

    resultResult
    Result
    Нет

    Полный результат; встраивается, только если запрошен (?include=result) или если POST /v1/pack?wait= успел завершиться.

  • 400Bad requestinvalid_jsonidempotency_key_invalid
    • invalid_jsonТело запроса — невалидный JSON, или у поля неверный тип.
    • idempotency_key_invalidДлина заголовка Idempotency-Key превышает 128 симв.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 401Unauthorizedunauthorizedkey_revokedkey_expired
    • unauthorizedAPI-ключ отсутствует, имеет неверный формат или неизвестен.
    • key_revokedКлюч отозван.
    • key_expiredСрок действия ключа истёк.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 402Payment requiredinsufficient_credits
    • insufficient_creditsДоступных кредитов не хватает даже на минимально возможный расчёт этого задания.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 403Forbiddenip_not_allowedsubscription_inactiveaccount_inactivescope_missing
    • 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 requeststoo_many_jobsrate_limited
    • too_many_jobsУ организации уже максимальное число заданий в очереди и в работе.
    • rate_limitedСлишком много запросов за текущую минуту, час или сутки (на ключ или на организацию) либо число неудачных попыток аутентификации с вашего IP-адреса превысило 60 в минуту.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 500Internal server errorinternal_error
    • internal_errorСбой на нашей стороне.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок
  • 503Service unavailableapi_disabled
    • api_disabledAPI временно отключён (техническое обслуживание) или выключен для организации.
    ИмяТипОбязательноОписание
    errorErrorBodyобязательно
    ErrorBody
    Да
    Все коды ошибок