План загрузки за один POST-запрос
Отправьте список мест - получите план: какие контейнеры, 3D-координаты каждого места, порядок погрузки и заполнение. Это 3D bin packing: один POST /api/v1/packing/compute. JSON внутрь, JSON наружу. PDF рендерится на нашей стороне.
curl -X POST "https://app.loadflow.ru/api/v1/packing/compute" \
-H "Content-Type: application/json" \
-H "X-Api-Key: tbp_<your-key>" \
-d '{
"orderRef": "ORD-2026-00142",
"scenario": "TRANSPORT",
"originCity": "Москва",
"destinationCity": "Хабаровск",
"cargos": [{
"id": "cargo-1",
"name": "Короб 600x400",
"lengthCm": 60, "widthCm": 40, "heightCm": 35,
"weightKg": 18,
"quantity": 42,
"temperatureMode": "NONE"
}]
}'Весь контракт - четыре группы endpoint-ов
POST /api/v1/packing/compute
- Что делает
- Считает план и сохраняет его. Возвращает planId + полный результат
- Scope
- packing:compute
GET /api/v1/packing/plans/{id}
- Что делает
- Отдаёт сохранённый план: вход, результат, метаданные
- Scope
- packing:read
GET /api/v1/packing/plans?orderRef=
- Что делает
- Находит последний план по номеру заявки
- Scope
- packing:read
POST /api/v1/packing/plans/{id}/share
- Что делает
- Создаёт ссылку на 3D без логина
- Scope
- packing:compute
POST /api/v1/packing/plans/{id}/render-pdf
- Что делает
- Рендерит PDF на сервере: summary или full с 3D-схемами
- Scope
- packing:read
GET /api/v1/catalog/*
- Что делает
- Справочники: контейнеры, каталог грузов организации
- Scope
- catalog:read / catalog:write
| Критерий | Что делает | Scope |
|---|---|---|
| POST /api/v1/packing/compute | Считает план и сохраняет его. Возвращает planId + полный результат | packing:compute |
| GET /api/v1/packing/plans/{id} | Отдаёт сохранённый план: вход, результат, метаданные | packing:read |
| GET /api/v1/packing/plans?orderRef= | Находит последний план по номеру заявки | packing:read |
| POST /api/v1/packing/plans/{id}/share | Создаёт ссылку на 3D без логина | packing:compute |
| POST /api/v1/packing/plans/{id}/render-pdf | Рендерит PDF на сервере: summary или full с 3D-схемами | packing:read |
| GET /api/v1/catalog/* | Справочники: контейнеры, каталог грузов организации | catalog:read / catalog:write |
Полная спецификация - в OpenAPI: схемы запросов и ответов, коды ошибок, справочные значения. Скачивается по /api/v1/openapi.json, смотрится в Swagger-вью на странице документации.
Ключи со scopes, журнал - из коробки
Ключ выпускается в настройках организации и получает только те права, которые вы выберете. Секрет показывается один раз, в базе хранится хеш. Передаётся в заголовке X-Api-Key.
packing:compute
Запуск расчётов
packing:read
Чтение планов и генерация PDF
catalog:read
Чтение справочников контейнеров и грузов
catalog:write
Создание и обновление грузов в каталоге через API
Каждый запрос попадает в журнал: endpoint, ключ, статус, время ответа. Ключ можно отозвать в один клик - без смены конфигов на вашей стороне.
Предсказуемые лимиты и коды ошибок
401
- Когда
- Нет или неверный X-Api-Key
- В ответе
- error
402
- Когда
- Исчерпана квота расчётов тарифа
- В ответе
- error
403
- Когда
- У ключа нет нужного scope
- В ответе
- error
422
- Когда
- Ошибка валидации
- В ответе
- error + fieldErrors
429
- Когда
- Rate limit по ключу
- В ответе
- error + retryAfterSec
503
- Когда
- Очередь расчётов занята (compute_capacity_exceeded)
- В ответе
- error + retryAfterSec
| Критерий | Когда | В ответе |
|---|---|---|
| 401 | Нет или неверный X-Api-Key | error |
| 402 | Исчерпана квота расчётов тарифа | error |
| 403 | У ключа нет нужного scope | error |
| 422 | Ошибка валидации | error + fieldErrors |
| 429 | Rate limit по ключу | error + retryAfterSec |
| 503 | Очередь расчётов занята (compute_capacity_exceeded) | error + retryAfterSec |
Rate limit на compute-запросы считается по ключу. При превышении вернём 429 с полем retryAfterSec - ретраить можно ровно через указанное время. Если движок занят другими расчётами, ответим 503 compute_capacity_exceeded, тоже с retryAfterSec. Конкретные значения лимитов для прототипа и прод-тарифов - в документации ключа. Все ошибки - JSON с полем error.
Sandbox → организация → прод
- 01
Sandbox-ключ
Зарегистрируйтесь и выпустите ключ с ограниченными лимитами. Достаточно, чтобы собрать прототип и погонять реальные данные.
- 02
Организация
Прод-ключи живут в организации: команда, роли, каталог грузов, квоты тарифа. Ключей можно выпустить несколько - под каждый сервис свой, с минимальными scopes.
- 03
Прод
Поднимаете лимиты под ваш поток на платном тарифе. Для встройки в свой продукт - white-label и тенант: обсудите с нами формат.
White-label и тенант под ваш продукт обсуждаются отдельно.
Дальше по документации
Guides
Пошаговые сценарии: первый расчёт, работа с каталогом, генерация PDF.
Открыть гайдыChangelog
Версии API и что изменилось. Контракт v1 стабилен, ломающие изменения - только с новой версией.
Смотреть changelogSandbox
Два готовых curl: сухая отгрузка и режим +2...+8. Ключ подставляете сами.
Открыть примеры
Соберите первый план сегодня
Sandbox-ключ, OpenAPI и один POST-запрос - этого хватит для прототипа.
Вопросы
Что нужно, чтобы сделать первый запрос?
Sandbox-ключ и curl. Регистрируетесь, выпускаете ключ, копируете пример с этой страницы, подставляете свои габариты - ответ приходит тем же запросом, план уже сохранён.
В каком виде приходит план?
JSON: контейнеры с метриками заполнения, placements с координатами в мм, поворотом и порядком погрузки loadStep, список неразмещённых мест с причинами. По planId тот же план можно забрать позже или отрендерить в PDF.
Как устроена авторизация?
Ключ организации в заголовке X-Api-Key. Права режутся по scopes (packing:compute, packing:read, catalog:read, catalog:write). Секрет хранится хешом и показывается один раз при выпуске.
Что будет при превышении лимитов?
429 с retryAfterSec при rate limit по ключу, 402 при исчерпании квоты тарифа, 503 с retryAfterSec, если очередь расчётов занята. Все ошибки - JSON с полем error.
Нужно ли самим рисовать 3D или PDF?
Нет. PDF (summary или full с 3D-схемами) рендерится на нашем сервере через render-pdf. Если хотите свою визуализацию - в placements есть всё для собственного рендера: координаты, габариты, повороты, цвета.
Чем sandbox отличается от прода?
Sandbox-ключ ограничен по лимитам и нужен для прототипа. Прод-ключи выпускаются в организации на платном тарифе - с квотами под ваш поток, ролями и журналом запросов.