GUIDES
Интеграция пошагово
Scopes, форматы запросов, типичные ошибки движка и fail-closed поведение термоданных.
Аутентификация: X-Api-Key
Все запросы к REST v1 идут с заголовком X-Api-Key. Ключ выдаётся в настройках организации и привязан к organizationId.
Формат ключа: prefix.secret. Revoke по prefix не затрагивает другие ключи той же org.
curl -H "X-Api-Key: lf_live_abc123.secret_part_here" \
-H "Content-Type: application/json" \
$BASE/api/v1/packing/computeScopes
packing:compute
POST /api/v1/packing/compute. Без этого scope расчёт вернёт 403.
packing:read
GET планов, render-pdf, история. Для UI и отчётов без права пересчёта.
catalog:read
GET /api/v1/catalog/containers и media. Справочник tenant для подстановки slug/id.
Создание ключа: настройки организации → API. Для интеграции ЛК AVINEX также есть internal for-packing с LK_INTERNAL_API_SECRET - см. статью про интеграцию.
Коды ошибок
NO_ELIGIBLE_CONTAINERS
После термофильтра не осталось типов с достаточной ёмкостью °C·ч.
THERMAL_DATA_MISSING
В prod нет thermal map по сегменту. Fail-closed - расчёт останавливается.
AXLE_OVERLOAD
Перегруз оси при PALLET_LOAD. Проверьте ContainerAxleProfile и CoG.
WEIGHT_EXCEEDED
Суммарный вес превышает допуск контейнера или транспорта.
PACKING_FAILED
Геометрия не сходится в time budget. Упростите груз или смените контейнеры.
UNSUPPORTED_MODE
Режим расчёта не поддержан в v1. Проверьте mode: THERMO | PLAIN | PALLET | PALLET_LOAD.
В UI обрабатывайте errorCode явно - пользователю нужен перевод, а не «что-то пошло не так». NO_ELIGIBLE_CONTAINERS лучше, чем отгрузка с неподходящим боксом.
Rate limits
На POST /api/v1/packing/compute действует PACKING_RATE_LIMIT_PER_MIN на API-ключ. При превышении - HTTP 429 и Retry-After.
Чтение планов и catalog:read обычно не попадают под тот же лимит compute - уточняйте в договоре для enterprise.
HTTP/1.1 429 Too Many Requests
Retry-After: 42
{
"error": "RATE_LIMIT_EXCEEDED",
"message": "PACKING_RATE_LIMIT_PER_MIN exceeded for this API key"
}Термофильтр и fail-closed
Термофильтр считает нагрузку маршрута в degree-hours по RouteThermalMap и профилям городов. Контейнеры с недостаточной thermalCapacityDegreeHours отсекаются до 3D-packing.
В production при LOGISTICS_USE_MOCK_THERMAL=0 отсутствие данных - THERMAL_DATA_MISSING. Mock ambient только в dev - не полагайтесь на него в интеграционных тестах prod.
Режимы v1: PLUS_2_8 (+2…+8), PLUS_15_25, MINUS_25_15. В ответе compute смотрите loadDegreeHours, thermalCapacityDegreeHours, transitHoursUsed.