От ключа до PDF - без второго контура

Три сценария: первый расчёт, работа со справочником, рендер отчёта. Контракт - OpenAPI. Примеры ниже можно скопировать.

Ключ и права

Все запросы к REST v1 идут с заголовком X-Api-Key. Ключ выпускается в настройках организации. Секрет показывается один раз.

packing:compute
POST /api/v1/packing/compute - запуск расчёта и сохранение плана.
packing:read
Чтение планов и генерация PDF.
catalog:read
Чтение справочников контейнеров и грузов организации.
catalog:write
Создание и обновление грузов в каталоге через API.

Первый расчёт

POST /api/v1/packing/compute. В каждом грузе обязательно temperatureMode: для сухой отгрузки укажите NONE. В ответе - planId, placements и unplacedItems.

POST /api/v1/packing/compute

curl -sS -X POST "https://app.loadflow.ru/api/v1/packing/compute" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originCity": "Москва",
    "destinationCity": "Казань",
    "cargos": [
      {
        "id": "box-1",
        "name": "Коробка",
        "lengthCm": 60,
        "widthCm": 40,
        "heightCm": 35,
        "weightKg": 12,
        "quantity": 4,
        "temperatureMode": "NONE"
      }
    ]
  }'

Справочник

Справочники контейнеров и каталог грузов организации доступны через GET /api/v1/catalog/*. В compute можно ссылаться на SKU организации.

GET /api/v1/catalog/containers
Типы тары организации: габариты, грузоподъёмность, сторона загрузки.
GET /api/v1/catalog/cargo-items
SKU организации. После записи в каталог в расчёте достаточно сослаться на позицию.

PDF

POST /api/v1/packing/plans/{id}/render-pdf собирает отчёт на нашей стороне. Рисовать 3D самим не нужно.

summary
Краткий PDF с таблицами - для согласования.
full
Полный PDF с 3D-схемами раскладки - для склада.

Ошибки HTTP

401
Когда
Нет или неверный X-Api-Key
Что делать
Проверьте заголовок и секрет ключа.
402
Когда
Исчерпана квота расчётов тарифа
Что делать
Дождитесь нового периода или смените тариф.
403
Когда
У ключа нет нужного scope
Что делать
Выпустите ключ с packing:compute, packing:read или catalog:read / catalog:write.
422
Когда
Ошибка валидации полей
Что делать
Смотрите fieldErrors в теле ответа.
429
Когда
Превышен rate limit по ключу
Что делать
Повторите запрос через retryAfterSec.
503
Когда
Очередь расчётов занята
Что делать
Повторите запрос через retryAfterSec.

Критерий	Когда	Что делать
401	Нет или неверный X-Api-Key	Проверьте заголовок и секрет ключа.
402	Исчерпана квота расчётов тарифа	Дождитесь нового периода или смените тариф.
403	У ключа нет нужного scope	Выпустите ключ с packing:compute, packing:read или catalog:read / catalog:write.
422	Ошибка валидации полей	Смотрите fieldErrors в теле ответа.
429	Превышен rate limit по ключу	Повторите запрос через retryAfterSec.
503	Очередь расчётов занята	Повторите запрос через retryAfterSec.

Если план посчитался, но часть мест не встала, причины будут в unplacedItems - это не HTTP-ошибка.

Соберите первый план сегодня

Выпустите ключ в настройках организации. Подставьте его в пример из песочницы или откройте OpenAPI.

Выпустить ключ OpenAPI

Вопросы

Где взять ключ?

В настройках организации, если есть право управлять ключами. Иначе попросите администратора.

Почему в примере есть temperatureMode?

Поле обязано быть у каждого груза. Для отгрузки без режима укажите NONE.

Нужно ли самим рисовать 3D?

Нет. PDF рендерится у нас. Для своего рендера в placements есть координаты и повороты.