Logistivo CLI: управляйте логистикой из терминала и из своей ERP
Один каталог команд питает три поверхности: терминальный клиент lg, ИИ-ассистента в панели управления и канал, к которому подключаются внешние ИИ-ассистенты. Возможность пишется один раз и появляется во всех трёх — и теперь у каждого действия записи в панели есть команда, так что ваши скрипты и ваши собственные ИИ-агенты могут выполнять ту же работу, которую ваши сотрудники выполняют на экране. Платежи, юридические согласия и закрытие аккаунта намеренно остаются в браузере. Эта страница — контракт. Таблица команд ниже не написана вручную: она генерируется из живого реестра команд при каждом запросе.
Что такое Logistivo CLI?
Logistivo CLI (lg) — это клиент командной строки, который выполняет работу вашего аккаунта Logistivo — грузы и рейсы, заявки, ставки и тендеры, автопарк и водители, документы, контакты и взаиморасчёты, счета и бухгалтерия, склад и запасы, сотрудники и таможенные тарифы — из терминала, из скрипта или из вашего собственного ИИ-агента. Команды не зашиты в клиент: клиент получает каталог команд с сервера и строит себя по нему. Те же команды можно вызывать по HTTP, ничего не устанавливая, — этим путём идут интеграции с ERP и CRM, — а также через канал MCP, к которому подключаются внешние ИИ-ассистенты.
Единая форма команды: lg --parameter=value. Сейчас в каталоге команд — 721, доменов — 175; самый широкий список, который видит одна роль: команд — 646, доменов — 165.
У каждого действия записи в панели есть команда: по замеру относительно эндпоинтов записи панели покрыто 100% эндпоинтов, входящих в охват. Платежи (3D Secure), юридические согласия и закрытие аккаунта намеренно остаются в браузере; для них команда вместо выполнения возвращает ссылку.
Команды, принимающие документ или фото, работают и вне браузера: напишите --attachment_uuid=@./cmr.pdf, и lg сначала загрузит файл; по HTTP вы загружаете файл на /api/common/commands:upload и передаёте полученный attachment_uuid.
Ключи интеграции имеют уровень доступа: employee (по умолчанию для новых ключей) — для повседневных операций, manager — для управления сотрудниками, настройками, ключами и деньгами. Ключ никогда не получает больше прав, чем человек, от имени которого он действует.
Флаги никогда не выдумываются: каждый флаг — это имя параметра из собственной JSON Schema команды, и оттуда же берутся его тип и обязательность.
Команды записи запрашивают подтверждение; необратимые никогда не выполняются без него (HTTP 409, код выхода CLI 4).
Повтор не создаёт дубликатов: вызов с idempotency_key выполняется не более одного раза.
Каждое выполнение попадает в единый журнал аудита — в записи зафиксировано, пришло ли оно из терминала, из чата или от ассистента.
Что работает сегодня, а что на подходе
Этот раздел намеренно стоит в начале страницы. Самая дорогая ошибка, которую может допустить интеграционная документация, — описать ещё не открытый эндпоинт так, будто он уже работает: интегратор пишет код, эндпоинт возвращает 404, и доверие уже не восстанавливается.
Поскольку контракт заморожен, код интеграции, который вы пишете сегодня, продолжит работать по мере открытия оставшихся частей. Неизвестные вам поля нужно игнорировать; именно это правило позволяет нам добавлять новое, ничего не ломая.
Каталог команд и таблица идентификаторов — Публичный идентификатор domain/verb каждой команды заморожен, а версия контракта публикуется как 1 в каждом ответе каталога и в заголовке X-Contract-Version. Таблица на этой странице генерируется из живого реестра: команда, добавленная на сервере, появляется здесь сама, а удалённая — исчезает.
Эндпоинт обнаружения без аутентификации — GET /api/public/cli/catalog — имена команд, идентификатор domain/verb, описание, параметры JSON Schema, флаги шлюзов и поля версионирования (since, deprecated_at, replaced_by, aliases). Без аутентификации: выпуск токена — это шаг, который идёт ПОСЛЕ решения об интеграции, а не до него. Ответ не содержит никаких данных тенантов.
Эндпоинты каталога и выполнения с аутентификацией — GET /api/common/commands, GET /api/common/commands/{name} и POST /api/common/commands/{name}. Шлюз ролей, шлюз подтверждения, идемпотентность и журнал аудита находятся в единой точке контроля, через которую проходят также чат и терминал.
Покрытие панели: у каждого действия записи есть команда — Команд — 721, доменов — 175; проверено по эндпоинтам записи панели: каждый эндпоинт в охвате обеспечен командой (зеркалом эндпоинта или тем же общим сервисом), и ни один не остался недоказанным. Намеренно вне охвата: платежи с 3D Secure, юридические согласия, закрытие аккаунта и вход — они остаются в браузере; управление ключами, вебхуками и песочницей — это встроенные команды lg; а также собственные эндпоинты приложения водителя.
Предварительная проверка (dry_run): увидеть результат, не выполняя — Если в теле запроса передать dry_run: true, команда не выполняется: валидация, шлюз ролей и областей доступа, разрешение цели и расчёт кредитов отрабатывают, и возвращается предварительный просмотр; ничего не записывается, кредиты не списываются, а ключ идемпотентности не расходуется. Эндпоинт пакетного выполнения (batch) тоже его принимает — для пакета целиком. Предварительная проверка никогда не входит в обработчик команды; когда функция вышла, 178 предварительных проверок по всем командам записи, существовавшим тогда в каталоге, не породили ни одного оператора записи.
Ключи интеграции — API-ключи, действующие от имени реального сотрудника, выпускаются в панели или командой lg keys create: область доступа (scope) read/write, уровень доступа (по умолчанию employee или manager), срок действия, последнее использование, ротация, передача и отзыв. На них построены lg login --api-key, lg whoami и lg logout, отзывающий ключ на стороне сервера.
Песочница (sandbox) — репетиция записи без затрагивания продакшена — Отдельный тенант-песочница для каждой компании с тем же каталогом команд; открывается самостоятельно (self-service) и выпускает собственный ключ. Кредиты, маркетплейс и маршрутизация вебхуков разделены между двумя средами; среда определяется по компании, которой принадлежит ключ, и не может быть передана вместе с запросом.
Версионирование, таксономия ошибок, идемпотентность и ограничения частоты запросов — Команды несут since / deprecated_at / replaced_by / aliases, а устаревшая команда отвечает с заголовком X-Deprecated. Бизнес-ошибки содержат стабильный error_key рядом с транспортным error_code, а словарь ключей публикуется в каталоге. Ключи идемпотентности ограничены вашей компанией, привязаны к одной команде и блокируются на 24 часа. Ограничения частоты запросов (rate limits) действуют на уровне токена, в трёх корзинах, и каждый ответ 429 содержит Retry-After.
Исходящие вебхуки: POST, когда что-то происходит — Подписанная push-доставка работает для событий, их число — 13. Подписками управляют из панели или командой lg webhooks; подпись содержит собственную метку времени, интервалы повторов — 60 · 300 · 1800 · 7200 · 21600 с, а причина приостановки (muting) всегда записывается. За каждым именем события стоит класс события, который действительно отправляется, — ничего не анонсируется, чтобы потом так и не быть отправленным. Pull-канал (updated_since + cursor) не удалён: push добавлен рядом с ним, а не вместо него.
Команды, принимающие файлы — Команд, принимающих документ или фото — CMR, счёт, свидетельство о регистрации транспортного средства, фото паллет, — 38. Загрузите файл один раз на POST /api/common/commands:upload или позвольте lg сделать это через --attachment_uuid=@./file.pdf и передайте полученный attachment_uuid; MCP-клиенты используют инструмент upload_attachment. Тип файла определяется по содержимому, а загрузка остаётся пригодной к использованию 24 ч.
Терминальный клиент lg — Опубликован в npm под лицензией MIT: установите его командой `npm install -g @lgstv/lg` или запустите без установки через `npx @lgstv/lg`. Это один файл без зависимостей, и поскольку HTTP-поверхность открыта, интегрироваться можно и без него. Клиент входит по коду одобрения, который вы подтверждаете в браузере, а затем остаётся в системе, сам продлевая свою сессию; он загружает за вас локальные файлы (@path, --file, lg upload), управляет ключами интеграции (lg keys), никогда не принимает секрет в командной строке, соблюдает Retry-After, повторяет запросы при 5xx с тем же ключом идемпотентности и предупреждает об устаревших командах и более новых версиях контракта.
Инкрементальная синхронизация: курсорная пагинация и updated_since — Контракт ниже (limit + непрозрачный подписанный cursor, next_cursor, updated_since) зафиксирован и постепенно внедряется в команды списков. Пока конкретная команда списка не объявит cursor и updated_since в своей JSON Schema, считайте её небольшим окном: максимум 20 строк, без курсора.
В чём отличие: клиент не знает команд — он строит их по каталогу
Это единственное решение, которое придаёт смысл всему остальному на этой странице. В обычном CLI команды живут внутри клиента; в Logistivo они живут на сервере.
В классической схеме, когда сервер получает новую возможность, клиенту нужен новый релиз, а пользователю — установить его. В промежутке две стороны знают разное — и это самый незаметный вид сбоя в интеграциях: скрипт работает, код выхода равен 0, а команда просто не описывает того, что умеет сервер.
В Logistivo определение команды — это одна запись: её имя, что она делает, её параметры JSON Schema, каким ролям она видна, требует ли она подтверждения и обратим ли её эффект. При запуске lg получает этот каталог и генерирует из него текст справки, флаги и проверку ввода. В тот момент, когда команда добавляется на сервере, lg уже знает о ней — без обновления клиента.
Тот же каталог питает ИИ-ассистента в панели и канал, к которому подключаются внешние ИИ-ассистенты. Возможность пишется один раз и появляется в трёх местах — и все три проходят через один и тот же шлюз ролей, один и тот же шлюз подтверждения и один и тот же журнал аудита. Отдельного перечня команд CLI не существует; если бы он был, три поверхности незаметно разошлись бы в течение полугода.
Никакого расхождения версий — Список команд, известный клиенту, по построению совпадает со списком на сервере. Вопроса «В какой версии lg есть эта команда?» просто не существует.
Имена флагов никогда не угадываются — Флаги команды — это в точности имена параметров в её JSON Schema. Чтобы узнать, что принимает команда, нужно читать не документ, а каталог — а каталог всегда актуален.
Ваш CLI ровно такого размера, как ваш аккаунт — Каталог фильтруется по роли: команда, которую ваша роль не может видеть, никогда не появится в вашем списке. Число команд для аккаунта перевозчика — 621, для грузоотправителя — 646, для таможенного брокера — 392, а у аккаунта аффилиата (реферального партнёра) собственный набор: команд — 55.
Документация не может отстать — Таблица команд на этой странице берётся из того же реестра. Нигде нет списка, который человеку приходилось бы синхронизировать с реальностью.
Правило именования — как растут имена команд
Каталог будет расти. Новые команды не называют как придётся — применяются шесть правил. Мы публикуем их здесь, потому что именно эти имена ваша интеграция будет писать годами, и их предсказуемость для вас кое-чего стоит.
Домен — это сущность во множественном числе — loads, demands, invoices, export-documents. Домены из двух слов пишутся в kebab-case. Единственное исключение — неисчисляемое существительное: stock никогда не ставится во множественное число, потому что «stocks» означает другое (акции).
Все глаголы одной сущности живут в одном домене — loads содержит все глаголы, действующие на груз: create, list, get, update, set-status, assign-driver, list-problems, archive и другие. Если открывать новый домен под каждый глагол (load-statuses, load-drivers), пользователю пришлось бы искать одну и ту же сущность в трёх местах.
Глагол никогда не просачивается в домен; домен — это то, что ИЗМЕНЯЕТСЯ — Назначение водителя изменяет груз, а не водителя, поэтому команда называется lg loads assign-driver. Косвенное дополнение (-driver) присоединяется к глаголу, а не к домену.
Подресурс никогда не получает собственного домена — Строку счёта и позицию документа нельзя вывести списком сами по себе; к ним обращаются через их владельца — lg invoices add-line, lg export-documents add-item. Всё решает один тест: если сущность нельзя независимо получить списком (list) или по отдельности (get), это не домен.
Сужение — это флаг, а не новый глагол — lg fleet-documents list --days=30 — правильно; отдельного глагола «list-expiring» нет, потому что окно уже является параметром. Уточнённый глагол используется только тогда, когда возвращаемые им строки — не сущность домена: loads list-problems возвращает флаги проблем, а не грузы.
Пара (domain, verb) уникальна во всём каталоге — Даже для двух команд, роли которых никогда не пересекаются. Если бы одна и та же пара была присвоена двум командам, ваш код интеграции видел бы одно имя, а CLI выполнял бы разные вещи в зависимости от того, кто его вызвал.
Покрытие: всё, что есть в панели, — через команду
Многие компании подключают Logistivo к собственному ИИ-агенту или среде автоматизации, а агент полезен только тогда, когда может довести работу до конца. Поэтому правило простое: всё, что офисный пользователь может изменить в панели, может изменить и команда — за тем же шлюзом ролей, тем же шлюзом подтверждения и с тем же журналом аудита.
Это измерено, а не заявлено. Каждый эндпоинт записи, стоящий за панелью, сверяется с реестром команд, и эндпоинт считается покрытым, только если какая-либо команда объявляет его своим HTTP-зеркалом или вызывает тот же общий сервис. Из эндпоинтов записи, входящих в охват, покрыто 100%, и ни один не остался недоказанным. У каждого исключённого эндпоинта есть письменно зафиксированная причина — шаги, связанные с идентичностью и платежами, плоскость управления интеграциями, собственные эндпоинты приложения водителя, клиентская телеметрия, мёртвые копии без вызывающих, — а те, что важны интегратору, перечислены ниже.
Команды, принимающие файл, подчиняются тому же правилу: команд в таблице, принимающих документ или фото, — 38, и все они работают из lg, по HTTP и через MCP (см. «Команды, принимающие файлы»).
Управленческая работа тоже покрыта, но за более сильным ключом: командам в таблице, касающимся сотрудников и ролей, настроек компании, банковских счетов, сохранённых карт и ключей интеграции (их 87), нужен ключ интеграции уровня manager. Ключ уровня employee, используемый по умолчанию, выполняет повседневные операции, а в этих командах получает отказ с INSUFFICIENT_KEY_LEVEL.
У аккаунтов аффилиатов (реферальных партнёров) собственный каталог: команд — 55, доменов — 20; это рефералы, лиды, заметки и задачи CRM, презентации для продаж, доходы и выплаты, а также команды аккаунта и управления сотрудниками, которые есть у каждой роли. Команды только для аффилиатов не входят в публичную таблицу ниже, где перечислены три роли панели; аккаунт аффилиата видит их в GET /api/common/commands и в lg commands. Компания, которая одновременно является аффилиатом и грузоотправителем, перевозчиком или таможенным брокером, видит оба набора.
Агенту следует начинать с lg users get (API-имя get_current_user): команда возвращает роль, уровень доступа используемого ключа, фактические разрешения и то, не блокирует ли сейчас запись ожидающее юридическое согласие или неподтверждённый номер телефона, — так агент может предсказать отказ, а не собирать отказы.
Покрытие измеряется отчётом, который сравнивает реестр команд с эндпоинтами записи панели; эндпоинт панели, добавленный без команды, появляется в нём как недоказанный. Если вы нашли в панели действие, недоступное через команду, сообщите об этом в поддержку.
1. Запросите ссылку — Работа, которая должна происходить в собственной браузерной сессии человека, — это не команда, но командная поверхность о ней знает. lg handoff-links generate (API-имя get_browser_handoff_link) возвращает ссылку на logistivo.com для целей, разрешённых вашей роли: package_purchase, payment_cards, legal_documents, integration_keys, affiliate_demo_accounts и account_close. Это бесплатно, ничего не записывает, и ссылка не содержит секрета — человек входит в систему как обычно.
2. Передайте её человеку — Покажите ссылку пользователю или отправьте её по своему каналу. Он завершит шаг там: принятие договора и оплата пакета через 3D Secure, добавление карты, принятие ожидающих юридических текстов, выпуск API-ключа, секрет которого показывается один раз, или закрытие собственного аккаунта.
3. Прочитайте результат командой — Когда шаг выполнен, его результат снова виден командам: пакет и баланс кредитов, сохранённая карта (в маскированном виде, только последние четыре цифры), новый ключ в списке ключей. Агент никогда не принимает в чате номер карты, платёж или согласие.
Платежи и 3D Secure — Покупка или повышение пакета и добавление карты требуют 3D Secure в браузере. Команды выводят список пакетов и цен, читают баланс и его историю, перечисляют сохранённые карты (в маскированном виде), назначают карту по умолчанию и удаляют карту; сама покупка проходит через ссылку передачи (handoff).
Юридические согласия — Юридические тексты принимает человек, в браузере. lg users get сообщает, что принятие ожидается; ни одна команда не может его дать.
Закрытие аккаунта, вход и пароль — Закрытие собственного аккаунта, вход и смена пароля — шаги, связанные с идентичностью, и они остаются в браузере. lg user-accounts preview показывает, что означало бы закрытие аккаунта, не выполняя его.
Ключи интеграции, вебхуки и песочница — Управление ими возвращает секреты, которые должны быть показаны один раз, в вашем терминале, поэтому это встроенные команды lg (lg keys, lg webhooks, lg sandbox), работающие через собственные HTTP-эндпоинты, а не команды каталога. В каталоге есть только две команды для ключей, не возвращающие секретов: integration-keys list и integration-keys revoke.
Чат ассистента в панели — Ключи интеграции не могут управлять чатом ИИ-ассистента в панели; на запуск или продолжение работы с ключом приходит ответ 403. Вместо этого агент подключается через эндпоинты команд, lg или канал MCP — там каждая команда выполняется на уровне доступа ключа, а её записи регистрируются как записи интеграции.
Приложение водителя — У аккаунтов водителей нет каталога команд, а приложение водителя использует собственные эндпоинты. Офисные пользователи управляют водителями, их документами, расходами и рейсами через команды.
Установка и идентификация
lg — это Node-скрипт из одного файла без зависимостей (Node 18+), опубликованный в npm как @lgstv/lg. Пакет устанавливает две одинаковые команды, lg и logistivo, — используйте logistivo, если имя lg на вашей машине уже занято алиасом. Поскольку это один файл, можно и просто скопировать lg.mjs на ERP-сервер клиента. Для интеграции с ERP/CRM клиент не нужен — те же команды доступны по HTTP.
1. Установка — Нужен только Node 18 или новее; других зависимостей нет. Установите клиент глобально или запускайте его без установки через npx.
2. Вход по коду одобрения — lg login показывает короткий код одобрения и открывает logistivo.com/connect в вашем браузере; по SSH, в CI или с --no-browser он только выводит адрес, который можно открыть на любом устройстве, в том числе на телефоне. Войдите там как обычно, убедитесь, что код на странице совпадает с кодом в вашем терминале, выберите доступ «только чтение» или «чтение и действия» и одобрите. В терминал не вводится ничего секретного: ни пароля, ни ключа, ни одноразового кода. После этого сессия остаётся активной на этом компьютере — закрытие терминала не завершает её, а lg сам продлевает токен доступа до истечения его срока. lg logout завершает сессию и на сервере, а удалить её можно в панели в разделе Settings › Integration keys › AI and CLI connections. lg login --password (email и пароль) остаётся запасным вариантом. Требуется lg 0.11 или новее.
3. Для серверов и CI: ключ, а не код одобрения — На сервере или в задании CI некому одобрить код в браузере. Выпустите ключ в панели (Settings › Integration keys) или командой lg keys create — при желании от имени отдельного сотрудника с узкими правами — и поместите его в LOGISTIVO_TOKEN или сохраните командой lg login --api-key. Пока переменная задана, файл конфигурации никогда не читается. Подробности — в разделе «Подключение с API-ключом».
4. Проверьте установку и изучите каталог — lg commands выводит все команды, которые видит ваша роль, сгруппированные по доменам; lg help выводит глаголы этого домена, а lg help — полный список параметров одной команды с типами и признаком обязательности. Ни один из этих текстов не хранится в клиенте — всё приходит из каталога. Помните, что список зависит от вашей роли: глаголы одного домена у перевозчика и у грузоотправителя не совпадают (например, loads set-status есть только в каталоге перевозчика). Если какого-то глагола нет, сначала проверьте роль, а уже потом установку.
Никогда не помещайте ключ в систему контроля версий, журнал CI или окно чата. Если вы вошли по коду одобрения или с ключом интеграции, lg logout завершает доступ и на сервере; в сессии с паролем (lg login --password) команда удаляет только ЛОКАЛЬНУЮ копию и прямо об этом сообщает. Журнал аудита хранит ваши аргументы, но маскирует как *** любое поле, в имени которого есть token, password, IBAN, card или OTP, а также каждый параметр, который команда объявляет секретным.
LOGISTIVO_TOKEN — Персональный токен доступа. Пока он задан, файл конфигурации никогда не читается — это предпочтительный путь в CI и на серверах.
LOGISTIVO_BASE_URL — Корень сервера. По умолчанию https://logistivo.com. Меняйте его, только если направляете клиент на собственную среду; флаг --base-url делает то же самое для отдельной команды.
LOGISTIVO_HOME — Директория для файла конфигурации и кэша каталога. По умолчанию ~/.logistivo. Разделяйте её, если работаете с двумя аккаунтами на одной машине.
LOGISTIVO_PROFILE — Профиль, от имени которого выполняется команда. `lg profile use` — постоянный выбор; эта переменная действует на один запуск и является самым коротким способом переключаться в CI между боевым профилем и профилем песочницы. Неизвестное имя профиля не игнорируется молча — возникает ошибка.
NO_COLOR — Если переменная задана, цвета ANSI не выводятся (постоянная форма флага `--no-color`). Включайте её для моста, который пишет в файл журнала или в вывод CI: управляющие последовательности цвета ломают инструменты, которые потом читают эти журналы.
Эргономика клиента
Эти возможности упрощают повседневную работу с клиентом `lg`. Ни одна из них не меняет HTTP-контракт — если вы интегрируетесь напрямую по HTTP, этот раздел можно пропустить.
Несколько сред и ключей — Держите тестовую и боевую среды (staging и production) или мосты для роли клиента и роли перевозчика в отдельных профилях. Список профилей никогда не выводит токен; в каждой строке показан отпечаток токена sha256. Каталог команд кэшируется отдельно для каждого профиля, хоста и токена, поэтому две роли никогда не увидят списки команд друг друга.
Инкрементальная синхронизация: lg sync — Запускает цикл синхронизации из руководства одной командой: отметка (watermark) для каждой сущности, updated_since с курсором, вывод в JSONL и пятиминутный запас. Для первичной загрузки используйте --full. Команда только читает данные; флага --write нет. lg sync --list определяет по каталогу сущности, доступные вашей роли для синхронизации.
Сообщения об ошибках и автодополнение в оболочке — При 422 клиент называет отклонённое поле в виде флага, который вы ввели, и показывает стабильный error_key вместе с пояснением к нему из самого каталога. При 409 он выводит готовую командную строку с --yes; при 429 выжидает время из Retry-After. Автодополнение в оболочке охватывает домены, глаголы, флаги и значения enum и работает офлайн.
Секретные параметры никогда не попадают в командную строку — Несколько команд принимают секрет — например, подключение бухгалтерской интеграции Paraşüt требует клиентских учётных данных и пароля этой системы. lg никогда не принимает такое значение в виде флага, потому что оно попало бы в историю оболочки и в вывод ps: клиент запрашивает его без отображения ввода или читает из ---file=PATH либо из stdin (---file=-) и хранит только в памяти. Команда, обязательный параметр которой секретен, выполняется только из lg: при вызове из чата, через MCP или внутри lg batch она отклоняется с SECRET_REQUIRES_CLI. Журнал аудита всегда записывает значение как ***.
Подключение с API-ключом
ERP, CRM, скрипт или ИИ-агент подключается к Logistivo с ключом интеграции, выпущенным в панели или командой lg keys create. Ключ действует от имени реального сотрудника: роль этого человека определяет список команд, уровень доступа ключа — насколько серьёзной может быть работа, а когда этот человек уходит из компании, ключ прекращает действовать вместе с ним. Синтетического «сервисного аккаунта» нет и не будет — мультитенантная изоляция привязана к пользователю, а мост без владельца — это как раз тот, что годами молча продолжает записывать данные.
1. Выпустите ключ в панели — Settings › Integration keys › New key. Дайте ему имя («ERP nightly sync»), выберите область доступа и уровень доступа и при желании сократите срок действия. Ключ показывается один раз и только на этом экране; сервер его не хранит. Если вы его потеряете, Rotate выпустит новый — старый сразу станет недействительным.
2. Подключитесь из терминала — lg login --api-key проверяет ключ, выводит идентичность и область доступа и загружает каталог команд. lg whoami спрашивает у сервера, от имени какого пользователя, компании и роли и с какой областью доступа вы работаете. lg logout также отзывает ключ на сервере — точно так же, как завершает там сессию, открытую по коду одобрения (этого не может сделать только lg logout в сессии с паролем).
3. Или чистый HTTP — Ключ — это токен доступа, передаваемый в заголовке Authorization: Bearer, и он напрямую работает с тремя эндпоинтами команд. На сервере или в CI поместите его в LOGISTIVO_TOKEN; пока эта переменная задана, файл конфигурации никогда не читается.
4. Или управляйте ключами из терминала: lg keys — lg keys — терминальный двойник экрана панели: те же эндпоинты, тот же шлюз (разрешение на управление сотрудниками, а при вызове с ключом — ключ уровня manager). create, rotate и transfer однократно возвращают новый токен: с --save-profile=NAME он сразу попадает в локальный профиль и никогда не выводится; иначе lg выводит его один раз. В режиме --json токен включается, только если добавить --show-secret, а вызов --json без обоих флагов отклоняется ещё до отправки запроса, чтобы токен не мог молча оказаться в выводе скрипта. rotate, transfer и revoke запрашивают подтверждение (--yes); ключ адресуется по точному имени или uuid, никогда по догадке. Уровень доступа переносится без изменений на ротированный или переданный ключ.
Область доступа применяется ко всей поверхности API, а не только к каталогу команд: ключ только для чтения пропускает запросы на чтение (GET/HEAD/OPTIONS), а на любой другой запрос записи приходит ответ 403 forbidden. Есть два намеренных исключения, и оба защищены более тонким шлюзом: эндпоинт выполнения команд (решение принимается по собственному флагу read_only команды, потому что команды без записи тоже вызываются через POST) и отзыв ключом самого себя (lg logout, разрешён и для ключа только для чтения). Область доступа, доступы к доменам и уровень доступа — три независимые оси, и все они должны быть пройдены: ключ read не может записывать даже на уровне manager, ключ write уровня employee не может управлять сотрудниками, а доступ к домену loads:write не открывает управленческую работу. Выпускайте ключ от имени сотрудника с наименьшими правами, которых достаточно для ваших задач: роль определяет, какие записи вы вообще можете видеть.
read — Каталог команд и команды без записи (list, search, preview). Команда записи возвращает 403 forbidden — ещё до шлюза подтверждения; ключ только для чтения никогда даже не видит 409. Правильный выбор для ночной синхронизации и отчётности.
write — Все команды. Команды, требующие подтверждения, по-прежнему запрашивают его ответом 409; confirm: true (--yes в CLI) работает точно так же, как раньше. Область доступа никогда не ослабляет шлюз подтверждения.
employee — По умолчанию для каждого нового ключа. Повседневные операции: грузы, заявки, ставки, рейсы, автопарк и документы автопарка, документы, контакты — все команды, которым не нужно управленческое разрешение, плюс разрешения автопарка. Команда, которой нужно больше, отвечает 422 с error_key INSUFFICIENT_KEY_LEVEL и required_key_level: manager; соответствующий REST-эндпоинт отвечает 403 с тем же ключом ошибки. Правильный уровень для ночной синхронизации ERP, моста телематики или операционного скрипта.
manager — Всё, что может делать человек, от имени которого действует ключ, включая управление: сотрудники и роли, настройки компании, ключи интеграции, банковские счета и их проверка, сохранённые карты, связи между компаниями, выплаты аффилиатам. Ключ manager никогда не добавляет права, которого нет у человека: без разрешения на управление сотрудниками он всё равно не может управлять командой. Ключи, существовавшие до появления уровней доступа, являются ключами manager, поэтому ведут себя в точности как раньше.
Один ключ на интеграцию — Если CRM и ERP делят ключ, отключение одной системы означает отключение другой. Дайте каждому мосту собственный ключ; в списке они всё равно отображаются по именам.
Ротация — Выпускает новый токен и сразу отзывает старый; оставшийся срок действия сохраняется. Используйте её при подозрении на утечку и через регулярные интервалы. Интеграция получает 401, пока её не обновят новым токеном.
Отзыв — Ключ закрывается навсегда; это нельзя отменить — при необходимости выпустите новый ключ. Если сотрудник, от имени которого действует ключ, удалён из команды или деактивирован, ключ отключается сам.
Срок действия и лимит — Срок действия по умолчанию — 180 дней; при создании его можно сократить, но не продлить. У пользователя может быть не более 10 активных ключей. Время последнего использования видно в списке; о ключе, который ни разу не использовался, это сказано явно.
Кто управляет — Выпуск, ротация, передача и отзыв доступны менеджерам с разрешением на управление сотрудниками — тот же шлюз, что и для добавления или удаления сотрудников, — а при выполнении с ключом интеграции этот ключ должен быть уровня manager. Менеджер может выпустить ключ от имени другого сотрудника; для моста рекомендуется отдельный сотрудник с узкими правами.
Первые десять минут: от панели до первого вызова
Самые дорогие минуты интеграции — первые десять. Четыре шага ниже выстраивают этот путь по порядку; тот же порядок есть в панели в виде мастера (Settings › Integration › Setup wizard), и мастер вызывает ровно те эндпоинты, что описаны здесь. Разработчик без доступа к мастеру придёт в ту же точку, прочитав этот раздел.
Ни один из четырёх шагов не заканчивается словами «я отправил». На вопрос, действительно ли ключ работает, отвечает журнал запросов; на вопрос, действительно ли доходит вебхук, — журнал доставок. Оба открыты в панели и в lg. Настройка, которую никто не измерял, — это настройка, в работоспособность которой просто верят.
1. Решите, что вы будете делать, — сначала задайте область доступа — Решить потом, что может видеть ключ, не получится: область доступа выбирается при выпуске. Осей две. Грубая область (read / write) отвечает только на вопрос «может ли он записывать». Тонкая область (доступы к доменам: loads:read, invoices:write) определяет, каких доменов он может касаться, и с момента её задания ключ работает по принципу fail-closed (всё, что не разрешено явно, запрещено): каждый невыбранный домен и каждый эндпоинт, не сопоставленный ни с одним доменом, возвращает 403. Список доменов в панели не написан вручную; он выводится из живого каталога команд вашей роли и показывает, сколько команд и REST-эндпоинтов открывает каждый домен. Эндпоинты каталога команд, «кто я» (current) и «выход» всегда освобождены от ограничения областью: ключ всегда должен иметь возможность описать и закрыть самого себя. Третья ось — уровень доступа: employee (по умолчанию) выполняет повседневные операции, manager — также работу с сотрудниками, настройками, ключами и деньгами. Выбирайте employee, если мост не выполняет управленческую работу.
2. Выпустите ключ — токен показывается один раз — Settings › Integration › New key. Дайте ему имя («ERP nightly sync»), выберите пользователя, от имени которого он работает, и уровень доступа, а при желании сократите срок действия. Сырой токен возвращается только в этом ответе; сервер его не хранит, и функции «показать ещё раз» в панели нет. Если вы его потеряете, выполните ротацию, чтобы получить новый, — старый перестаёт действовать мгновенно. Никогда не помещайте токен в систему контроля версий, журнал CI или окно чата; храните его в хранилище секретов целевой системы.
3. Сделайте первый вызов — и убедитесь, что он ДЕЙСТВИТЕЛЬНО дошёл — Достаточно двух запросов. Первый подтверждает вашу идентичность (он освобождён от ограничения областью и работает с любым ключом): та ли область доступа, что вы ожидали, активен ли статус, не приближается ли expires_at. Второй читает реальные данные из выбранного вами домена. Если он проходит, значит, идентичность, область доступа, шлюз e-mail и сетевой путь — всё в порядке. Если нет, не гадайте: собственный журнал запросов ключа показывает строку за строкой, какой эндпоинт был отклонён, с каким кодом и каким стабильным ключом ошибки (INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, KEY_ACTOR_BLOCKED …). В панели этот журнал — окно «Recent requests», в терминале — lg logs. Мастер следит именно за этим журналом и не отмечает шаг зелёным, пока не увидит реальный успешный вызов.
4. Настройте вебхук — и прежде всего проверяйте подпись — Ждать событий дешевле, чем спрашивать каждую минуту. Зарегистрируйте https-адрес, выберите интересующие вас события и привяжите подписку к своему ключу: если ключ будет отозван, доставка тоже прекратится. Секрет показывается только один раз — при создании. Ваш принимающий эндпоинт должен первым делом проверять подпись: подписываемая строка — "{t}.{raw body}", алгоритм — HMAC-SHA256; метка времени находится ВНУТРИ подписи, поэтому отбрасывайте любой запрос старше 300 секунд, даже если подпись верна. Сравнивайте за постоянное время и никогда не сериализуйте тело заново — в тот момент, когда вы разбираете JSON и печатаете его снова, подпись перестаёт совпадать. В панели кнопка «Send test» отправляет настоящий подписанный ping, и вы можете следить за доставкой попытка за попыткой.
Песочница: практикуйтесь в записи, не затрагивая продакшен
Предварительная проверка (dry_run) говорит, что команда СДЕЛАЛА БЫ; но действительно ли идемпотентность воспроизводит результат, действительно ли вебхук доставляется, как выглядят ветки ошибок и откуда берутся кредиты, можно увидеть только при РЕАЛЬНОЙ записи. Для этого и существует песочница: отдельный тенант, зеркалирующий вашу компанию, — тот же код, тот же каталог команд, — который никогда не касается вашего боевого учёта.
Песочница — это не флаг запроса, а ТЕНАНТ. Отдельная компания Logistivo, открытая для вашей: собственный пользователь, собственный пакет, собственный журнал кредитов, собственные подписки на вебхуки. Среда ВЫВОДИТСЯ из компании ключа и не может быть передана вызывающей стороной, поэтому, даже если вы выберете не тот профиль, запрос остановится на сервере с 403 ENVIRONMENT_MISMATCH. Ситуация «я думал, что пишу в песочницу, а записал в продакшен» невозможна по построению.
Поверхность идентична — это измерено: каталог, который получает ключ песочницы, — тот же, что получает ваш боевой ключ (для ключа грузоотправителя число команд с обеих сторон — 646). Мост, который работает в песочнице, работает и в продакшене; ничему не придётся учиться дважды.
Песочница открывается не пустой: в ней есть сгенерированные (НЕ скопированные) начальные данные — контакты, грузы в обоих направлениях и заявки. Имена откровенно вымышлены, а e-mail-адреса находятся в домене @sandbox.invalid; ни одна строка реального тенанта никогда не читается, не клонируется и не используется как шаблон.
Кнопки сброса намеренно НЕТ, и никакие записи, файлы или документы никогда не удаляются. Если вам нужен чистый старт, обновление открывает новое поколение, а старое остаётся — выведенным из работы. Несколько сотен накопившихся репетиционных строк ничего не стоят по сравнению с процедурой удаления, направленной не на тот тенант.
1. Откройте песочницу — Одна песочница на компанию. Эндпоинт требует разрешения на управление сотрудниками (team.manage), поэтому это делает администратор вашей компании. Если песочница уже существует, тот же эндпоинт по GET отвечает её состоянием: id компании, остаток кредитов, число активных ключей, подписки, история поколений и потолки.
2. Выпустите ключ песочницы и сохраните его как второй профиль — Ключ выпускается от имени собственного пользователя-моста песочницы и возвращается с отметкой environment: sandbox; сырой токен появляется только в этом одном ответе. На стороне lg не заменяйте боевой ключ — храните ОБА как отдельные профили; --sandbox и --live выбирают профиль для одного запуска.
3. Записывайте по-настоящему — Никакого --dry-run здесь: запись — в этом весь смысл. Отправьте один и тот же ключ идемпотентности дважды и посмотрите, как второй ответ возвращается со status: replayed, — это измеренный результат в песочнице. Намеренно вызовите команду со шлюзом без подтверждения и прочитайте тело 409; попробуйте команду вне вашей области доступа и прочитайте отказ. Ничто из этого не оставляет следа в вашем боевом учёте: на протяжении того же прогона ваш боевой баланс не меняется.
4. Перед переходом в боевой режим прочитайте чек-лист — Эндпоинт go-live отвечает на основе того, что вы ДЕЙСТВИТЕЛЬНО сделали в песочнице: записывали ли вы данные, видели ли ветки ошибок, был ли доставлен вебхук, перевели ли вы приёмник с репетиционного адреса, задали ли срок действия ключа. Каждый пункт возвращается как pass / todo / unknown. Тот же ответ содержит и ПРЕДЛОЖЕНИЕ ОБЛАСТИ ДОСТУПА, выведенное из команд, которые вы действительно вызывали, — используйте его, чтобы выпустить боевой ключ не шире, чем нужно.
Кредиты и выставление счетов — У песочницы собственный журнал кредитов, и ваш боевой баланс не меняется. Это свойство структуры, а не проверка: кредиты считаются по компаниям, а песочница — отдельная компания. Она открывается на бесплатном пакете, не имеет способа оплаты и находится вне окна ежемесячного списания — ни одним путём она не может дойти до счёта.
Маркетплейс — Заявка, открытая в песочнице, НЕ появляется на экранах реальных перевозчиков и НЕ доходит до их e-mail или push-уведомлений; и реальных заявок вы тоже не видите. Разделение симметрично и обеспечивается двумя отдельными запросами: кому заявка ВИДНА и кому она ОТПРАВЛЯЕТСЯ — разные вопросы.
Вебхуки — Подписки тоже несут отметку среды. Событие песочницы никогда не доставляется в боевую подписку, а боевое событие никогда не доходит до подписки песочницы; для подписки, отметка которой разошлась со средой, доставка вообще не открывается. Поскольку потолок подписок считается на компанию, ваши репетиционные подписки не съедают боевую квоту.
Начальные данные — Образцы записей внутри песочницы СГЕНЕРИРОВАНЫ и никогда не копируются у реальных тенантов. Заполнение идемпотентно: повторный вызов не накладывает второй набор начальных данных поверх ваших собственных записей.
Тот же каталог — Ваша роль остаётся вашей ролью и в песочнице, а список команд идентичен — измерено: число команд с обеих сторон — 646. Песочница — не урезанная демоверсия, а двойник вашей компании.
Сегодняшнее ограничение: подписками на вебхуки нельзя управлять ключом песочницы — Эндпоинты подписок требуют разрешения на управление сотрудниками (team.manage), а у пользователя-моста песочницы нет роли в команде, поэтому `lg --sandbox webhooks …` сегодня отвечает 403. Вся командная поверхность работает — ограничение касается только реестра подписок. Если вы хотите отрепетировать вебхуки в песочнице, обратитесь в поддержку; это измерено и зафиксировано как открытый пробел.
GET /api/common/integration-sandbox — Состояние: существует ли песочница, какая компания, остаток кредитов, число активных ключей и подписок, история поколений, потолки и справочник триггеров, показывающий, какая команда порождает какое событие.
POST /api/common/integration-sandbox — Открывает песочницу (одна на компанию, идемпотентно). Требует разрешения team.manage.
POST /api/common/integration-sandbox/keys — 201 + ключ и сырой токен (только здесь и только один раз). Отметка environment: sandbox выводится из компании; вызывающая сторона не может её передать.
GET /api/common/integration-sandbox/go-live — Чек-лист перехода в боевой режим и предложение области доступа — рассчитанные по вашему реальному трафику в песочнице.
POST /api/common/integration-sandbox/renew — Открывает новое ПОКОЛЕНИЕ песочницы и выводит предыдущее из работы.
Модель команд
Грамматика одна, и исключений у неё нет. Чтобы знать, как вызвать команду, достаточно того, что о ней говорит каталог.
lg loads list --status=in_transport --limit=20 --json
Имена флагов — это имена параметров схемы, и lg принимает оба написания: --load_code и --load-code попадают в одно и то же поле (lg help выводит форму в kebab-case). Поэтому по флагу сразу видно, в какое поле JSON он попадёт, и переход от CLI к HTTP не требует перевода имён. Булев параметр, записанный без значения, равен true (--only_open); противоположное значение — --no-only_open. Аргумент, значение которого начинается с дефиса, пишите как --flag=value, иначе забытый флаг молча проглотит следующий как своё значение. В команде, принимающей файл, ставьте @ перед локальным путём (--attachment_uuid=@./cmr.pdf) — см. «Команды, принимающие файлы».
lg — Клиент.
loads — Домен — сущность, с которой вы работаете, во множественном числе.
list — Глагол — то, что вы делаете с этой сущностью; он берётся из закрытого словаря, который пополняется только по осознанному решению: простые глаголы (list, get, create, update, delete, search, preview, generate, extract …) и составные глаголы, называющие то, что присоединяется или изменяется (add-document, set-status, assign-driver). lg help выводит глаголы домена.
--status=in_transport — Параметр — его имя в точности совпадает с именем параметра в JSON Schema, а значение должно соответствовать типу схемы. Недопустимое значение для поля enum никогда не доходит до сервера.
--limit=20 — Число строк в командах списков. Верхний предел указан в описании параметра каждой команды — обычно 20 при простом вызове списка и до 100 в режиме синхронизации (с cursor или updated_since).
--json — Вывод в виде сырого JSON.
--json — Выводит сырой JSON. Это единственный корректный формат для скриптов: выровненная таблица по умолчанию предназначена для людей, подбирает колонки по данным и может менять раскладку без предупреждения. Никогда не пишите скрипт, который разбирает табличный вывод.
--yes, -y — Проходит шлюз подтверждения (confirm: true по HTTP). Используйте его только в скрипте, который знает, что собирается сделать; в необратимой команде этот флаг означает «отменить будет нельзя».
--idempotency-key= — Делает повтор команды записи безопасным. Второй вызов с тем же ключом не выполняет команду заново, а возвращает первый результат. Если вы строите цикл повторов, генерируйте ключ САМИ и отправляйте один и тот же ключ при каждой попытке.
--dry-run — Вместо команды выполняет предварительную проверку: отрабатывают валидация, шлюзы и расчёт кредитов, но ничего не записывается (см. раздел о предварительной проверке). Действует для любой команды и для lg batch.
--refresh — Принудительно обновляет каталог. lg кэширует каталог на час; если вы знаете, что команда только что добавлена на сервере, используйте этот флаг вместо ожидания.
--help, -h — Выводит описание команды из каталога, все параметры, их типы, значения enum и обязательность. Файла справки внутри клиента нет.
--profile=, --sandbox, --live — От имени какого профиля выполнить этот один вызов. --sandbox и --live выбирают профиль, в котором хранится ключ песочницы или боевой ключ; среда определяется на сервере по ключу, поэтому при несоответствии выполнение останавливается с 403 ENVIRONMENT_MISMATCH, а не записывает данные не туда.
--base-url, --timeout, --verbose, --no-color, --version — Соответственно: направить одну команду на другой сервер, тайм-аут в секундах, подробности запроса и ответа, отключение цветов ANSI и версия клиента.
Реальные примеры
Каждая команда ниже уже сегодня существует в каталоге; ни одно имя или параметр здесь не выдуманы. Вывод сокращён. В выводе показан уровень `data.result`; по HTTP тот же объект приходит внутри конверта `{success, data:{…}}` (см. HTTP API команд).
Грузы, которые сейчас в пути — lg loads list --status=in_transport --limit=20
Один груз целиком, сырой JSON — lg loads get --load_code=FSK2158 --json
Открытые флаги согласованности документов — lg loads list-problems --only_open=true --limit=10
Определить страну — lg countries search --query=Germany --json
Отфильтровать по найденному id — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
Найти код HS по названию товара — lg tariffs search --query="aluminium profile"
Перевести груз на следующий статус (только для роли перевозчика) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
Черновик — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
Сгенерировать (со шлюзом) — lg export-documents generate --document_id=8412 --yes
Без клиента: HTTP API команд
lg — это удобство, а не единственный вход. И каталог, и выполнение проходят через три HTTP-эндпоинта (у файлов есть четвёртый — эндпоинт загрузки, см. «Команды, принимающие файлы»); интеграция с ERP или CRM подключается сюда напрямую. Идентификация — персональный токен доступа в заголовке Authorization: Bearer. КАЖДЫЙ ответ приходит в одном и том же конверте: `{ "success": bool, "data": { … }, "code": "…", "message": { … } }`. Весь контракт находится внутри `data` — `contract_version`, `command`, `status` и, как результат работы команды, `result`; при сбое — `error_code`, `error_key` и `error`. Примеры ответов на этой странице для экономии места показывают объект `data`, а не конверт; не забудьте развернуть `data` в своём коде. `lg --json` тоже выводит конверт ЦЕЛИКОМ, поэтому пути jq начинаются с `.data.result…`. Единственное исключение — `/api/public/status`: этот эндпоинт отвечает без конверта, чтобы сторожевые скрипты могли поднимать тревогу, не разбирая ответ.
Запрашивать подтверждение ответом 200 + ok:false запрещено, и так никогда не будет. Причина проста: клиенты считают 200 успехом, поэтому запрос подтверждения, возвращённый как 200, молча оборвал бы поток, и никто бы этого не заметил. Подтверждение — это всегда 409.
GET /api/common/commands — Весь каталог, который видит ваша роль: contract_version; для каждой команды — name, domain, verb, description, JSON Schema, read_only, confirmation_needed, irreversible, credit_cost, since, deprecated_at, replaced_by, aliases и поля доступа key_level, permission, file_params, secret_parameters и cli_only; на верхнем уровне — словарь error_keys, rate_limits, idempotency_ttl_hours, роли вашего каталога, контракт вложений (upload) и уровень доступа ключа, с которым вы делаете вызов. Отправляет ETag; на If-None-Match отвечает 304. ?domain= совпадает и со старым доменом (алиасом). Стройте свой клиент на этой основе; не зашивайте список команд в код.
GET /api/common/commands/{name} — Одна команда целиком. name — замороженное имя команды из каталога (list_loads), а не её идентификатор в CLI. Устаревшая команда отвечает с заголовком X-Deprecated.
POST /api/common/commands/{name} — Выполнение. Тело: { args, confirm?, idempotency_key? }. HTTP-статус ответа — это и есть результат: всё, кроме 200, — информация, а не шум. Ошибки содержат error_code (транспортный уровень) и, при бизнес-отказах, error_key.
Команды, принимающие файлы
Команд в таблице, принимающих документ или фото, — 38: прикрепить CMR к грузу, прочитать коды HS из счёта, создать транспортное средство по его регистрационному документу, оценить паллету по фото, загрузить документ компании, сверить счёт с упаковочным листом. В браузере вы перетаскиваете файл в форму; во всех остальных местах нужны два шага — загрузить файл, а затем передать его id команде.
Параметр принимает файл, если его имя оканчивается на attachment_uuid или attachment_uuids — photos[].attachment_uuid внутри списка, front_attachment_uuid у банковского чека. Запоминать это не нужно: каждая строка каталога содержит file_params с точными путями, схема помечает эти поля (format: uuid, x-logistivo-file: true), а ответ каталога содержит блок attachments с адресом загрузки, допустимыми типами, ограничениями размера и временем жизни. lg help тоже их показывает.
Загрузка — это запись, поэтому ключ с областью read загружать не может; любой ключ с областью write может — на любом уровне доступа. Загрузки принадлежат пользователю, а не ключу: два ключа одного пользователя видят одни и те же загрузки, и никто не может использовать чужие. id, который неизвестен, истёк или вам не принадлежит, просто не находится, а причина не раскрывается.
Вложения чата в панели и загрузки для команд — отдельные пространства: файл, прикреплённый в чате ассистента, нельзя передать команде по id, а загрузка для команды никогда не появляется в ветке чата.
Загрузка — это не команда, и сама по себе она не имеет бизнес-эффекта: с вашими данными ничего не происходит, пока команда не использует id. Поэтому загрузка никогда и не запрашивает подтверждения — шлюз несёт команда, которая использует файл.
1. lg: поставьте @ перед локальным путём — lg сначала загружает файл, а затем выполняет команду с полученным id; значение без @ — это id файла, загруженного ранее. Списки принимают пути через запятую или повторяющийся флаг, вложенные поля — JSON, а --file — сокращение для команды ровно с одним файловым полем верхнего уровня. lg проверяет каждый файл локально (существование, размер, тип) ещё до отправки чего-либо, а lg batch загружает каждый уникальный файл один раз перед запуском пакета.
2. HTTP: загрузите, затем передайте attachment_uuid — Отправьте файл как multipart/form-data в поле с именем file. Новая загрузка отвечает 201; тот же файл, повторно загруженный тем же пользователем, отвечает 200 со статусом replayed и тем же id, и ничего не записывается. Как и везде на этой странице, пример показывает объект data внутри конверта.
3. MCP: инструмент upload_attachment — MCP-клиент не может отправлять multipart, поэтому канал предлагает один дополнительный инструмент, которого нет в каталоге: upload_attachment принимает имя файла и содержимое в base64 и возвращает тот же attachment_uuid. Он вызывает тот же сервис, что и загрузка по HTTP, по тем же правилам.
Тип определяется по содержимому — Имя файла и заявленный тип игнорируются; сохраняемое расширение — то, что определено по содержимому. Для загрузки принимаются: jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip. Затем каждая команда ещё до выполнения применяет собственный, более узкий список и отвечает UNSUPPORTED_FILE_TYPE с перечнем допустимых типов или FILE_TOO_LARGE.
Размер — Изображения — до 10 МБ, прочие файлы — до 15 МБ.
Время жизни — Загрузку можно использовать в течение 24 ч. После этого она больше не разрешается (ATTACHMENT_NOT_FOUND), но не удаляется. Если команда завершилась ошибкой по этой причине, загрузите файл снова.
Тот же файл — тот же id — Повторная загрузка того же файла (то же имя, размер и содержимое) возвращает существующий id вместо записи нового, если до истечения срока остаётся не менее часа, и не расходует ваш дневной потолок.
Дневные потолки — Загрузок на пользователя в день — не более 300 (TOO_MANY_FILES), объём на компанию в день — не более 2 ГБ (DAILY_LIMIT_REACHED); оба ограничения отвечают 429 с retry_after.
POST /api/common/commands:upload — Загрузка multipart в поле file. 201 — для новой загрузки, 200 со статусом replayed — для того же файла. Возвращает data.attachment: attachment_uuid, filename, mime_type, size_bytes, sha256, extraction_status, expires_at и reused.
Шлюз подтверждения и необратимые команды
Каждая команда в каталоге несёт два флага: confirmation_needed (требует ли она явного одобрения перед запуском) и irreversible (можно ли отменить её эффект). Это разные вопросы, и оба контролируются на сервере, а не оставлены на добросовестность клиента.
Шлюз — это вопрос ответственности, а не бизнес-правил. Ставка — первый шаг к договору перевозки; выставление счёта создаёт бухгалтерскую проводку; движение запасов меняет учётный регистр. Ничто из этого никогда не должно случайно выполняться дважды.
Шлюз определяется по ФАКТИЧЕСКИ выполняемой команде. Когда одна команда оборачивает другую — как это делает универсальный исполнитель в чате, — шлюз берётся из флагов той команды, которая реально будет выполнена, а не из обёртки. При фиксированном флаге один из двух сбоев был бы неизбежен: либо команда выставления счёта выполнялась бы без подтверждения, либо каждый поиск страны вызывал бы карточку подтверждения.
read_only и отсутствие шлюза — не одно и то же. Есть три разных состояния: invoices preview не имеет шлюза и ничего не записывает; loads create имеет шлюз и записывает; invoices create не имеет шлюза, но записывает — появляется черновик. Всё решает один тест: когда команда вернула результат, изменилась ли какая-нибудь строка в базе данных?
Некоторые действия находятся не за этим шлюзом, потому что они вообще не являются командами: покупка пакета, добавление карты с 3D Secure, принятие юридических текстов и закрытие аккаунта происходят в собственном браузере человека. Для них lg handoff-links generate возвращает ссылку на logistivo.com — бесплатно, ничего не записывая и не содержа секрета, — и человек завершает шаг там. Никакой флаг, как бы он ни был выставлен, не превращает платёж или согласие в вызов API.
Технически интеграция может автоматически проходить шлюз при каждом вызове, но делать так не рекомендуется. Правильный подход — автоматизировать шлюз только для команд, о которых известно, что они обратимы, а необратимые направлять в очередь к человеку.
1. Вызовите — Вызовите команду со шлюзом без confirm. Ничего не меняется.
2. Прочитайте сводку — Вы получаете 409; confirmation.summary в теле — это предложение, написанное для человека («About to issue an invoice: X Ltd, 1,200.00 TRY»), а не дамп сырых аргументов. Денежные команды несут также структурированный предварительный просмотр: позиции, итоги, предупреждения.
3. Подтвердите — Повторите тот же вызов с confirm: true (--yes в CLI). Необратимые команды помечены так, чтобы они выполнялись не более одного раза.
Предварительная проверка: что сделала бы команда записи — без её выполнения
Самый дорогой шаг при подключении моста к ERP — выяснять, правильно ли составлено тело запроса, ДЕЙСТВИТЕЛЬНО выполняя команду: черновик счёта в боевом учёте, сожжённый кредит, ручная уборка. dry_run положил этому конец: вы добавляете в запрос одно поле, команда не выполняется, и вы читаете, что произошло бы.
Сейчас в реестре команд — 721; из них только для чтения (ничего не записывают) — 327. Из оставшихся команд записи — их 394 — шлюз есть у 346: при вызове без confirm они уже отвечают 409 и описывают, что сделали бы. Пробел составляли остальные — их 48: черновики счетов, черновики экспортных документов, строки позиций — ровно та цепочка, которую мост подключает первой. Для них вызвать значило выполнить.
Был и второй пробел, даже в командах со шлюзом: валидация схемы выполняется ПОСЛЕ шлюза. Поэтому вызов с отсутствующим аргументом сначала получал карточку подтверждения, подтверждал её и только потом слышал «этого поля не хватает». Предварительная проверка отвечает на оба вопроса за один обмен запросом и ответом.
А самая частая — и обнаруживаемая позже всех — ошибка моста такова: вы отправляете поле, которого нет в схеме (customer_id там, где ожидается recipient_contact_id), сервер молча его отбрасывает, команда возвращает 200, и запись оказывается не там. Ответ предварительной проверки перечисляет такие поля по именам в arguments.ignored; никакое сообщение об ошибке этого никогда не сделает.
Предварительная проверка ничего не записывает, и это прежде всего свойство архитектуры, а уже потом результат измерения: путь предварительной проверки никогда не входит в обработчик команды, поэтому это верно для каждой команды, включая добавленные позже. При выпуске это ещё и измерили: был перехвачен каждый SQL-оператор, выданный при предварительной проверке каждой команды записи, существовавшей тогда в каталоге (два набора аргументов, две роли, 178 предварительных проверок). Ни одного INSERT/UPDATE/DELETE, ни одного поставленного в очередь задания, ни одного письма; количество строк в 31 таблице и баланс кредитов не изменились.
Код выхода тот же, что дал бы реальный вызов: выполнилась бы — 0, шлюз подтверждения — 4, конфликт идемпотентности — 2, всё остальное — 1, поэтому «lg … --dry-run || exit» — осмысленный шлюз в шаге CI.
1. Вызовите с dry_run — Добавьте "dry_run": true в тело запроса. Валидация, шлюз ролей и областей доступа, разрешение цели и расчёт кредитов выполняются; сама команда — нет.
2. Прочитайте would_execute — Это единственный флаг, по которому стоит строить ветвление. Если он равен false, would_stop.at указывает, где остановился бы реальный вызов: idempotency, target_precheck, confirmation_gate или arguments.
3. Исправьте тело запроса — arguments.ignored называет поля, которые были бы молча отброшены, missing_required — пропущенные обязательные поля, а would_charge — сколько кредитов будет списано и покрывает ли их баланс.
4. Уберите dry_run — Повторяйте, пока would_execute не станет true, затем уберите флаг и выполните реальный вызов. Ключ идемпотентности, отправленный во время предварительной проверки, не был израсходован, поэтому реальный вызов выполнится как обычно.
HTTP всегда 200 — «Команда завершилась бы ошибкой» никогда не приходит как 4xx — сама предварительная проверка прошла успешно, а прогноз находится в теле. Исключение — отказ на транспортном уровне, и тут поведение в точности как у реального вызова: 404 — неизвестная команда, 403 — роль/область доступа, 429 — rate limit.
Ключ с областью read не может выполнить предварительную проверку команды записи — Он получает 403. Предварительная проверка отвечает на вопрос «что произойдёт, если я вызову это С ЭТИМ КЛЮЧОМ прямо сейчас»; дать ключу для чтения зелёный свет, а потом 403 на реальном вызове — это ровно тот сюрприз, ради предотвращения которого предварительная проверка и существует.
Ключ идемпотентности не расходуется — Ключ, отправленный во время предварительной проверки, не создаёт строку в журнале, а истёкшая блокировка не освобождается. Поэтому отправляйте тот ключ, который собираетесь использовать по-настоящему: предварительная проверка скажет, свободен ли он ещё, приведёт ли к воспроизведению (replay) более раннего выполнения или конфликтует с другой командой.
Сочетается с confirm — Отправьте dry_run и confirm вместе, и вопрос станет таким: «что произойдёт, если я подтвержу?». По-прежнему ничего не выполняется.
Предварительная проверка пакета — на уровне пакета — commands:batch тоже принимает dry_run, но флаг относится к пакету, а не к элементу (отправка его в элементе даёт 422). Вы получаете отчёт по каждому элементу плюс общую стоимость пакета в кредитах; о недостаточном балансе сообщается, но запрос не отклоняется.
Это не бесплатно — Каждая предварительная проверка выполняет реальные запросы (предварительный просмотр, баланс) и учитывается в rate limit. Не прогоняйте предварительную проверку всего каталога при каждом деплое; проверяйте те команды, которые вы изменили.
Идемпотентность: почему повтор не создаёт дубликатов
ERP не читает ваше сообщение об ошибке, не видит ваш экран и повторно отправит тот же запрос после тайм-аута. Этот раздел существует именно из-за такого поведения.
Вызов с idempotency_key выполняется не более одного раза. Второй вызов не выполняет команду заново, а возвращает записанный результат со статусом replayed. Когда обрывается сеть, когда запрос завершается по тайм-ауту или когда очередь дважды забирает одно и то же задание, вы получаете первый результат, а не дубликат счёта.
Используйте ключ в каждой команде записи. Поле каталога read_only даёт вам это различие даром: каждая команда с read_only: false заслуживает ключа идемпотентности.
Ваша стратегия повторов должна использовать экспоненциальную задержку (exponential backoff) и передавать ОДИН И ТОТ ЖЕ ключ при каждой попытке. Генерировать новый ключ для каждой попытки — всё равно что вообще не использовать идемпотентность. Не отправляйте один и тот же ключ параллельно: «не более одного раза» гарантируется для последовательных повторов, а не для двух запросов, соревнующихся друг с другом.
Ловушка 1 — неудача тоже фиксируется — Если первое выполнение было отклонено бизнес-правилом (failed), второй вызов с тем же ключом возвращает ту же ошибку и тот же error_key и не повторяет попытку. Чтобы исправить аргумент и попробовать снова, нужен НОВЫЙ ключ. Ключ представляет попытку, а не намерение.
Ловушка 2 — большой результат воспроизводится без тела — Журнал хранит результат, только если он меньше 64 КБ. Больший результат воспроизводится со статусом replayed, но с пустым телом. Ваша интеграция должна опираться на сигнал «replayed», а не на тело, и получать данные соответствующей командой get.
Ловушка 3 — ключ принадлежит одной команде — Отправка того же ключа с другой командой возвращает 409 idempotency_conflict с conflicting_command; ничего не выполняется и ничего не воспроизводится. Клиент, использующий один ключ для двух глаголов, неисправен — и узнаёт об этом из ошибки, а не из молчаливого воспроизведения.
Ловушка 4 — блокировка длится 24 часа, а не вечно — Через 24 часа тот же ключ означает новое выполнение. Сетевые повторы приходят в течение минут; ежегодно повторяющиеся номера документов ERP не должны навсегда оставаться «replayed». Каталог публикует это окно как idempotency_ttl_hours.
Ловушка 5 — ошибка сервера не блокирует ключ — 5xx server_error — не бизнес-отказ: ключ не привязывается, поэтому повтор с тем же ключом действительно выполняет команду. Блокирует только failed (ловушка 1).
Область и формат — ваша компания, любая строка, лучше всего UUID — Уникальность обеспечивается по паре (ваша компания, ключ): INV-1001 другого тенанта никогда не столкнётся с вашим и никогда не сможет воспроизвести ваш результат. Используйте обычный UUID или составной ключ, уникальный по построению, например {ERP-document-no}:{verb}.
Инкрементальная синхронизация и пагинация
Мост ERP/CRM должен забирать то, что изменилось, а не всё подряд каждый час. Каждая команда списка — loads list, demands list-own, contacts list, invoices list, teammates list, load-groups list, reservations list, drivers list, tenders list, products search, warehouses search — принимает два общих параметра и возвращает одно общее поле.
Почему нет offset: на живой таблице смещение «плывёт». Строка, вставленная между двумя страницами, заставляет вас пропустить запись или учесть её дважды — молча. Курсор движется только вперёд, поэтому запись, вставленная или обновлённая посреди обхода, попадает в конец списка: ничего не теряется и ничего не дублируется.
Полная начальная загрузка работает по тому же механизму: начните с updated_since=1970-01-01T00:00:00Z и следуйте по next_cursor, пока он не станет null. Отдельного эндпоинта «export» нет, потому что он не нужен.
То же самое с lg: lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json, затем lg loads list --cursor= --json.
Для следующей синхронизации установите updated_since равным наибольшему updated_at, который вы видели. Метки времени имеют точность до секунды, поэтому запись на границе может прийти дважды — это безвредно, если на своей стороне вы делаете upsert по external_ref или коду. Без updated_since или cursor команда работает в режиме чата: порядок, удобный человеку, не более 20 строк, next_cursor равен null, а truncated сообщает, что «есть ещё». Не используйте этот режим для синхронизации.
Машиночитаемые ключи ошибок для этого раздела: INVALID_CURSOR, INVALID_UPDATED_SINCE, DUPLICATE_EXTERNAL_REF, EXTERNAL_REF_TOO_LONG, EXTERNAL_REF_INVALID. Все они отвечают HTTP 422 с error_code: "failed" и result.error_key в теле. Стройте ветвление по ключу, а не по тексту.
updated_since — Метка времени ISO-8601 (рекомендуется UTC, например 2026-09-01T00:00:00Z). Строки, обновлённые в этот момент или позже. Переводит команду в режим синхронизации: фиксированный порядок (updated_at, id) по возрастанию, limit не больше 100.
cursor — next_cursor из предыдущего ответа, без изменений. Курсор непрозрачен и подписан: никогда не собирайте и не редактируйте его сами, никогда не используйте курсор другой компании или другой команды; всё это отклоняется с INVALID_CURSOR.
limit — Размер страницы. 1-100 в режиме синхронизации (по умолчанию 10).
next_cursor (ответ) — Курсор следующей страницы. null означает, что список получен полностью; это единственный корректный ответ на вопрос «есть ли ещё».
total (ответ) — Число строк, соответствующих фильтрам, независимо от страницы, — для отображения прогресса.
Ваш собственный ключ: external_ref
Не делайте наши автоинкрементные id (invoice_id, contact_id) бизнес-ключом в своей ERP: они непрозрачны и существуют только в пределах вашей компании. Вместо этого грузы, заявки, контакты, счета, товары и склады хранят ваш ключ.
Задавайте его при записи — loads create, demands create, contacts create и contacts update, invoices create принимают необязательный external_ref (не более 120 символов) и возвращают его без изменений.
Используйте его при чтении — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... — всё это работает; в командах списков и поиска --external_ref= — фильтр точного совпадения.
Уникален в пределах компании — Вторая запись с тем же ключом отклоняется с 422 и result.error_key = DUPLICATE_EXTERNAL_REF; на ключ другой компании вам отвечают «не найдено». Сравнение выполняется без учёта регистра (ord-1 = ORD-1). Архивированная запись сохраняет свой ключ; восстановите её, прежде чем использовать ключ повторно.
Отправляйте также idempotency_key — Повтор после сетевого тайм-аута возвращает первый результат, а не создаёт дубликат. Эти два ключа не взаимозаменяемы: external_ref — ваш бизнес-ключ, а idempotency_key идентифицирует одну попытку.
Исходящие вебхуки: мы отправляем вам POST, когда что-то происходит
Всё до этого места было pull-моделью: вы спрашиваете, мы отвечаем. Мосту ERP приходилось спрашивать раз в минуту, чтобы узнать, что груз сменил статус, выставлен счёт или пришла ставка. Теперь это не нужно: зарегистрируйте https-адрес, выберите интересующие вас события — и когда они происходят, приходит подписанный POST.
Push добавлен РЯДОМ с pull, а не вместо него. Инкрементальная синхронизация (updated_since + cursor) не тронута и по-прежнему остаётся правильным инструментом: первая полная загрузка, дозагрузка истории и ответ на вопрос «не пропустил ли я что-нибудь» — всё это там. Вебхуки сокращают задержку с минут до секунд. Здоровый мост использует и то и другое: вебхук — как триггер, синхронизацию — как страховочную сеть.
Payload — это СИГНАЛ, а не копия записи. Он несёт идентификаторы (id, ваш собственный external_ref, статус, время); подробности вы получаете своим ключом через GET, и этот вызов уже проходит ваши собственные шлюзы авторизации. Поэтому поверхность раскрытия данных остаётся на уровне идентификаторов. Два поля намеренно отсутствуют: сведения о том, какая компания сделала ставку (слепые ставки отображаются в панели под псевдонимом; передача этих сведений в вебхуке нарушила бы эту конфиденциальность через второй канал), и контактные данные бронирования (незачем передавать персональные данные через дополнительный канал).
Имена событий ЗАМОРОЖЕНЫ. Если смысл имени меняется, открывается новое имя, а старое доживает период вывода из употребления (deprecation). Добавление нового поля в payload НЕ повышает версию контракта — потребитель обязан игнорировать неизвестные ему поля.
GET /api/common/integration-webhooks — Реестр плюс каталог событий, лимиты и имена заголовков. Каждая строка содержит причину приостановки и сводку доставок за 7 дней.
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }. Секрет появляется только здесь.
PATCH /api/common/integration-webhooks/{uuid} — Имя / адрес / события / флаг активности. Секрет НЕ затрагивается.
DELETE /api/common/integration-webhooks/{uuid} — Удаляет подписку: строка удаляется мягко (soft delete — история остаётся доступной для запросов), а ожидающие доставки отменяются.
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + новый секрет. Старое значение перестаёт работать в тот же момент.
POST /api/common/integration-webhooks/{uuid}/test — Событие ping — настоящая подпись, настоящий путь, настоящий график повторов.
GET /api/common/integration-webhooks/{uuid}/deliveries — Последние доставки: статус, номер попытки, HTTP-код, длительность, метка ошибки.
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — Повторно отправляет одну доставку: event_id СОХРАНЯЕТСЯ, id доставки новый, payload копируется дословно.
Каталог событий
За каждым из событий ниже (их 13) стоит класс события, который ДЕЙСТВИТЕЛЬНО отправляется. В каталоге нет имён из разряда «было бы неплохо»: событие, которое анонсировано, но никогда не срабатывает, — это событие, которого интегратор ждёт вечно, и такой сбой незаметен. Эта таблица тоже не написана вручную — она строится из живого каталога при каждой загрузке страницы.
invoice.payment_recorded намеренно ОТСУТСТВУЕТ: класс этого события существует в коде, но нигде не отправляется. Событие оплаты будет добавлено в тот день, когда класс действительно начнёт срабатывать, — не раньше. Анонсировать событие заранее хуже, чем не добавлять его вовсе.
load.created — A load became visible to your company (created by you or shared with you). (load)
load.status_changed — A load moved to a new status (pending, in_transport, transit, done). (load)
load.driver_assigned — A driver was assigned to a load. (load)
demand.created — A freight demand was created by your company. (demand)
demand.status_changed — A freight demand changed status. (demand)
demand_bid.created — A bid was placed on a demand you are party to. (demand_bid)
demand_bid.revised — A bid was revised (a new revision replaced the previous one). (demand_bid)
demand_bid.accepted — A bid was accepted. (demand_bid)
invoice.created — An invoice draft was created. (invoice)
invoice.issued — An invoice was issued (it now carries an invoice number). (invoice)
invoice.cancelled — An invoice was cancelled. (invoice)
warehouse_reservation.created — A warehouse dock/area reservation was created. (warehouse)
warehouse_reservation.status_changed — A warehouse reservation was approved, rejected or otherwise moved. (warehouse)
Проверка подписи
Каждый запрос содержит заголовок X-Logistivo-Signature: t=,v1=. Подписываемая строка — "." (метка времени, точка и сырое тело), алгоритм — HMAC-SHA256. Префикс v1 позволяет версионировать схему: если когда-нибудь появится вторая схема, заголовок будет содержать t=…,v1=…,v2=…, и вы выберете ту, которую знаете.
Мы публикуем два эталонных приёмника без зависимостей — для Node и для чистого PHP. Оба применяют четыре правила выше и проверяют себя флагом --selftest: корректная подпись, подменённое тело, неверный секрет, метка времени вне окна, некорректный заголовок, ловушка повторной сериализации и оба вида повторения (та же доставка / тот же факт). Верификатор — точный аналог кода, который используем мы сами: мы потребляем тот же контракт, который публикуем.
Проверяйте СЫРОЕ тело — Подпись вычисляется над байтами. Декодирование и повторная сериализация тела (JSON.stringify(req.body), json_encode($request->all())) превращают те же ДАННЫЕ в другие БАЙТЫ, и подпись перестаёт совпадать. В Node ловушка — форматирование чисел (1.50 при передаче становится 1.5; большие целые числа теряют точность), в PHP — экранирование символов (/ становится \/, İ становится \u0130). Используйте express.raw в Express и $request->getContent() в Laravel. Это самая распространённая ошибка при написании приёмника.
Проверяйте метку времени — t находится ВНУТРИ подписи. Если проверять только подпись, любой, кто перехватил корректный запрос, сможет воспроизвести его через несколько часов, и приёмник засчитает его как проверенное событие. Отбрасывайте любой запрос, где |now − t| > tolerance, даже если подпись верна. Рекомендуемое окно — 300 с.
Сравнивайте за постоянное время — hash_equals / timingSafeEqual. Сравнение через == позволяет атакующему подбирать подпись байт за байтом.
Устраняйте дубликаты по event_id, а не по id — event_id идентифицирует ФАКТ: он одинаков для двух подписчиков, получающих одно и то же событие, и СОХРАНЯЕТСЯ при повторной отправке (replay). id (= X-Logistivo-Delivery) идентифицирует ДОСТАВКУ и при replay меняется. На вопрос «обработал ли я это уже» отвечайте по event_id; если отвечать по id, replay заставит выполнить одну и ту же работу дважды.
Доставка, повторы и приостановка
Ваш приёмник не всегда будет доступен. Канал доставки исходит из этого: временный сбой попадает в график повторов, постоянный — приостанавливает подписку (muting), и ПРИЧИНА приостановки всегда записывается.
Причина приостановки машиночитаема и стабильна (delivery_failures, endpoint_gone, unsafe_target, key_revoked, by_user) и отображается как в панели, так и в `lg webhooks list`. Приостановка без причины оставила бы вопрос «почему ничего не приходит» без ответа. Повторное включение сбрасывает счётчик и отметку.
Адрес пишете вы; запрос делает НАШ сервер. Без шлюза тенант, указавший адрес облачных метаданных, мог бы заставить нас отправлять запросы изнутри нашей собственной сети. Поэтому адрес проверяется и при регистрации, и при КАЖДОЙ доставке:
Тайм-ауты — 8 с всего, 4 с на подключение — медленный приёмник не должен занимать воркер. Поставьте работу в очередь и сразу верните 2xx.
График повторов — 60 · 300 · 1800 · 7200 · 21600 с → попыток: 6, окно примерно 8,6 ч.
Единственный постоянный сбой: 410 Gone — Означает «удалите меня»: без повторов, подписка приостанавливается сразу. НИКОГДА не возвращайте 410 при ошибке проверки подписи.
Любой другой сбой — Повторяются ВСЕ, включая 4xx. Потеря бизнес-события стоит дороже, чем несколько лишних запросов: приёмник, возвращающий 403, пока обновляется правило WAF, на канале, который считает 4xx постоянными сбоями, молча потерял бы событие «счёт выставлен».
Retry-After — Учитывается при 429 и 503 (не более 6 часов).
Перенаправления — НЕ выполняются. Переход на внутренний адрес через 302 пробил бы шлюз адресов вторым путём.
Автоматическая приостановка — После серии подряд исчерпанных доставок (порог — 10). Ответ 410, небезопасная цель и отзыв связанного ключа интеграции приостанавливают подписку НЕМЕДЛЕННО.
только https, только порты 443/8443, встроенные учётные данные (https://user:pass@…) отклоняются;
localhost, однокомпонентные имена и внутренние суффиксы вроде .internal / .local / .svc отклоняются — отклоняется само намерение, ещё до того, как смотрится результат разрешения имени, поэтому split-horizon DNS не может пробить шлюз;
IP-литералы и ВСЕ записи DNS-разрешения должны быть публичными. Если имя разрешается и в публичный, и в частный адрес, никто не спрашивает нас, какой выбрать → имя сразу отклоняется;
в момент доставки адрес разрешается один раз, и соединение привязывается к проверенному адресу: окно для DNS rebinding закрыто;
ТЕЛО ответа приёмника нигде не сохраняется (только код статуса, длительность и короткая метка ошибки), поэтому путь «чтения» — а именно в нём и состоит реальная ценность дыры в шлюзе адресов — остаётся закрытым.
Переключателя конфигурации «разрешить частные адреса» намеренно НЕТ: такой переключатель однажды по ошибке остаётся включённым.
Возвращается ОДИН раз — только при создании подписки и при rotate-secret. Хранится на сервере в зашифрованном виде и не может быть прочитан снова; функции «показать ещё раз» нет.
lg выводит его на экран и оставляет там — ни в какой файл конфигурации или кэша он его не записывает.
Если секрет утерян, вы выполняете его ротацию; старое значение перестаёт работать В ТОТ ЖЕ МОМЕНТ. Для бесшовного перехода ваш приёмник должен на время перехода проверять оба секрета.
Смена адреса НЕ затрагивает секрет: рутинное обслуживание вроде «URL переехал» не должно ломать проверку на принимающей стороне.
Работоспособность и статус: никто не должен заметить замолчавший мост раньше вас
Интеграционный мост редко умирает громко. Обычно он затихает глубокой ночью: истекает токен, человек, от имени которого работает ключ, увольняется, область доступа сужается или принимающий эндпоинт начинает возвращать 403. Первым это почти всегда замечает клиент. lg status существует, чтобы изменить этот порядок.
Одна команда отвечает сразу на два вопроса, потому что во время сбоя оба задаются одновременно: работает ли платформа и здоров ли мой мост. Строка о платформе работает без токена — во время сбоя первым подозреваемым становится сам токен, и если привязать к нему вопрос о статусе, вы останетесь без ответа именно тогда, когда он нужен.
Сводка работоспособности не ведёт нового журнала; она сводит три существующих источника в одно предложение: дневной счётчик использования (сколько вы вызывали и сколько вызовов завершилось ошибкой), журнал запросов (какой запрос, когда и почему был отклонён) и журнал доставок исходящих вебхуков (дошло ли событие до приёмника). Доля ошибок всегда берётся из дневного счётчика; детальный журнал ограничен по объёму и прямо сообщает, когда предел достигнут.
Та же сводка показывается в панели: в разделе Settings › Integration › Keys у каждой строки есть значок, а под ним — причина. Пороги не вычисляются на стороне клиента; какой уровень назначил сервер, тот и отображают и панель, и lg status, поэтому два экрана никогда не скажут об одном и том же ключе разное.
Вашему сторожевому скрипту не нужен токен. Эндпоинт возвращает только слова статуса; он не содержит ни версии, ни имени хоста, ни имени очереди, ни числа заданий, ни текста ошибок, ни данных клиентов — и не может их содержать.
Сводка работоспособности формируется постоянным числом запросов к базе на один HTTP-запрос; это число не растёт с количеством ключей. За подробностями читайте последние запросы конкретного ключа через lg logs, а исходящий мост — через lg webhooks list.
ИСПРАВЕН — Измеренных неисправностей нет, и у нас есть доказательство успеха: успешный вызов в журнале или трафик, который прошёл по счётчику без ошибок.
ВНИМАНИЕ — Что-то начало ломаться: доля ошибок или серия неудач подряд превысила порог, запросы отклоняются на шлюзе, срок действия ключа подходит к концу или мост, который регулярно выходил на связь, замолчал.
СБОЙ — Мост сейчас не работает: токен был отозван непреднамеренно, закрытый ключ всё ещё вызывается, пять неудач подряд, доля ошибок выше пятидесяти процентов или подписка на вебхук была приостановлена.
ЗАКРЫТ — Ключ был закрыт сознательно, и никто его не вызывает. Это решение, а не неисправность, — и красным оно не окрашивается.
НЕТ ДАННЫХ — Измерений нет: ключ ни разу не вызывался или само измерение не удалось. Ни то ни другое не считается зелёным.
Никакого ложного зелёного. Значок «исправен» требует измеренного доказательства успеха; ключ, который ни разу не вызывался, никогда не становится зелёным, потому что ни одно измерение не показывает, что он работает.
Никакого ложного красного. Ключи, которые вы закрыли намеренно, отображаются как «закрыт». Если красить всё в красный, красный теряет смысл; закрытый ключ становится красным, только если его всё ещё вызывают после закрытия, — и тогда мост действительно сломан.
«Не удалось измерить» — не то же самое, что «нет данных». Если запрос на стороне сервера завершается ошибкой, строка не показывает молча ноль; она сообщает, что измерение выполнить не удалось.
О тишине всегда сообщается, но она никогда не превращается в предупреждение вслепую. Мост, работающий в конце месяца, замолкает на тридцать часов — это нормально; замолчал мост, который выходил на связь как минимум пять дней из последних семи, — это неисправность. Ритм измеряется, а не предполагается.
Сам запрос статуса не загрязняет показатели работоспособности. Вызовы, сделанные lg status, появляются в журнале запросов, но исключаются из расчёта работоспособности — иначе ваш собственный успешный запрос статуса сбрасывал бы серию неудач и скрывал бы ту самую неисправность, ради показа которой существует этот экран.
Каждая строка измеряется: к базе данных выполняется реальный запрос, каталог команд действительно строится, живая запись воркера очереди действительно считывается. Ничего не предполагается.
Сам ответ — тоже измерение: если вы можете прочитать тело, веб-уровень работает.
Верхний уровень выводится только из обязательных компонентов. Когда очередь останавливается, ответ — degraded, а не down: синхронному вызову API очередь не нужна, и объявление платформы неработающей было бы ложной тревогой.
Когда состояние очереди измерить невозможно, верхний уровень остаётся нетронутым: незнание — не то же самое, что измеренная неисправность.
Если платформа не работает, эндпоинт возвращает HTTP 503. Тело отдаётся без конверта, чтобы инструменты мониторинга могли поднимать тревогу, не разбирая его, а ответ никогда не сохраняется ни в каком кэше.
Ошибки и коды выхода
Машина ветвится по стабильной строке. Текст в поле error предназначен для человека, локализован и меняется без предупреждения — интеграция, которая ветвится по тексту сообщения, не поддерживается, и её поломка не считается багом.
Две таксономии, два поля. error_code — транспортный уровень (таблица выше), и ветвиться в первую очередь нужно по нему. error_key — стабильный ключ бизнес-правила внутри failed (INSUFFICIENT_CREDITS, NOT_FOUND, DUPLICATE_CONTACT, INSUFFICIENT_STOCK), публикуемый в виде словаря в каталоге (error_keys) и ниже. Команда, которая ещё не выдаёт ключ, возвращает error_key: null; ключ, отсутствующий в словаре, считайте общей ошибкой.
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · Идемпотентное воспроизведение; работа НЕ выполнялась повторно.
failed — HTTP 422 · error_code failed · CLI 1 · Нет — отклонено бизнес-правилом (см. error_key). Бессмысленно, пока аргумент не изменится.
needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · Да, с confirm: true.
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · Нет — ключ впервые был использован для другой команды (conflicting_command). Создайте новый ключ.
forbidden — HTTP 403 · error_code forbidden · CLI 3 · Нет — шлюз ролей или ключ с областью read в команде записи.
not_found — HTTP 404 · error_code not_found · CLI 2 · Нет — неверное или удалённое имя команды.
(схема) — HTTP 422 · error_code invalid_request · CLI 2 · Нет — тело запроса или аргумент не прошли валидацию схемы (errors{}); это не бизнес-правило.
server_error — HTTP 500 · error_code server_error · CLI 6 · Да — с экспоненциальной задержкой и ТЕМ ЖЕ ключом идемпотентности; ключ не был заблокирован.
401 unauthenticated — Токен истёк или был отозван. Повтор не поможет; токен нужно заменить.
429 rate_limited — Превышен лимит частоты запросов для этого токена. Ответ всегда содержит Retry-After и тело с retry_after, limit и bucket; соблюдайте его, а не придумывайте фиксированную задержку. lg ждёт и повторяет до трёх раз, затем завершается с кодом 5.
5xx server_error / сетевая ошибка — Повторяйте с экспоненциальной задержкой и ТЕМ ЖЕ ключом идемпотентности. Смена ключа заново запускает работу, которую сервер, возможно, уже выполнил. lg повторяет три раза (1 с, 2 с, 4 с), затем завершается с кодом 6 и error_code network_error или server_error.
Обещание стабильности
Самый дорогой вопрос в интеграционном контракте — «будет ли код, который я пишу сегодня, работать завтра?». На него отвечает одно число: contract_version в каталоге и заголовок X-Contract-Version в каждом ответе. Оно отвечает ровно на один вопрос: работает ли ранее написанный код без изменений? Если число не выросло — да. Если выросло — нет: что-то, на что вы опирались, было удалено или сужено.
Потому что объявление ничего не удаляет: на следующий день ваш существующий код работает в точности как прежде. Повышение версии при объявлении дало бы два сигнала на одно изменение и приучило бы вас игнорировать первый — ослабляя тот сигнал, который действительно важен. Объявление и так приходит вместе с вызовом, который вы делаете: deprecated_at и replaced_by в строке каталога, заголовок X-Deprecated плюс блок deprecated в ответе этой команды и однострочное предупреждение в stderr, если вы используете lg. Вам не нужно ничего делать, чтобы узнать, что что-то уходит; это уже есть в вашем журнале.
Между объявлением и удалением проходит не менее двух календарных кварталов. Всё это время старая команда по-прежнему отвечает и предупреждает при каждом вызове. Когда имя CLI выводится из употребления, его преемник забирает это имя как алиас: в течение окна старое имя ведёт к старой команде, а в день удаления тот же вызов попадает в новую — без того, чтобы вы выпускали новую версию клиента.
preview_invoice → get_invoice (объявлено 3 сентября 2026 г.). get_invoice возвращает тот же блок предварительного просмотра и добавляет позиции, разбивку налогов, зарегистрированные платежи, остаток к оплате и обращение по вашему собственному ключу ERP (external_ref). preview_invoice продолжает работать, как и lg invoices preview, — оба предупреждают.
без изменений — Новая команда · новый НЕОБЯЗАТЕЛЬНЫЙ параметр · новое поле ответа · новый ключ ошибки · новый эндпоинт — Ничего не делайте. Вы обязаны игнорировать неизвестные вам поля; парсер, который падает на неизвестном поле, не соответствует контракту.
без изменений — ОБЪЯВЛЕНИЕ об устаревании: уведомление о том, что команда уходит — Ваш код продолжает работать. Поставьте задачу в календарь — окно составляет не менее 6 месяцев.
повышается — Удаление команды · вывод из употребления старого имени CLI · удаление поля ответа · превращение необязательного параметра в обязательный · сужение enum — Это значит, что вы пропустили окно; уведомление доходило до вас в трёх разных местах.
API-имя команды (например, list_loads) заморожено навсегда; именно его вы используете в HTTP-вызовах.
error_code (транспорт) и error_key (бизнес-правило) — стабильные строки. Могут появляться новые: ключ, которого вы не нашли в словаре, считайте общей ошибкой, а не поломкой.
Соответствие между HTTP-статусом и полем status в теле фиксировано.
Номер версии никогда не уменьшается и читается в каждом ответе — включая 304 и 429 без тела.
ТЕКСТ ошибок и описаний. Он локализован и меняется без предупреждения; ветвление по тексту сообщения не поддерживается.
Отсутствие неизвестных вам полей. Добавление поля не повышает версию.
Автоинкрементные id в качестве бизнес-ключей. Передавайте собственный ключ через external_ref.
Динамические ключи ошибок, полученные из имён классов; они не являются частью контракта.
Таблица идентификаторов команд
Таблица ниже не написана вручную: она генерируется из живого реестра команд при каждой отдаче этой страницы. Команда, добавленная на сервере, появляется здесь сама. Колонка «Шлюз» показывает, запрашивает ли команда подтверждение и можно ли отменить её эффект; колонка «Роли» — в каталоге каких типов аккаунтов её можно найти. Значки отмечают команды, которым нужен ключ уровня manager, команды, принимающие файл, и команды, которые выполняются только из lg.
Команды сгруппированы по функциям, у каждой своя страница. Выберите функцию, чтобы открыть её таблицу команд.
API-имя (list_loads) заморожено и не изменится; именно его вы используете в HTTP-вызовах. Идентификатор CLI (loads list) подчиняется политике версионирования: после объявления он меняется только с повышением версии и переходным окном, в течение которого каталог отдаёт старую пару как алиас. Описания здесь взяты из собственной записи каждой команды и сокращены — полный текст, типы параметров и значения enum смотрите в эндпоинте каталога или запустите lg help . Команды только для аффилиатов здесь не перечислены; аккаунт аффилиата видит их в собственном каталоге.
Грузы и отслеживание — Создание грузов, участники, документы, ссылки для отслеживания, подпись при доставке, ETA и исключения. Команд: 115 — /ru/developers/cli/loads
Граница и таможня — Проверка готовности к границе, ожидание на границах и в портах, экспортные документы, уведомление U-ETDS. Команд: 42 — /ru/developers/cli/border
Заявки и предложения — Открытие заявок на перевозку, запрос и подача предложений, тендеры, перевозчики в сети. Команд: 42 — /ru/developers/cli/quotes
Тарифы и коммерческие предложения — Согласованные тарифы, каскад предложений и коммерческие предложения клиентам. Команд: 57 — /ru/developers/cli/pricing
Автопарк и водители — Водители, транспорт, чеки расходов, расчёты с водителями, планирование рейсов и дни Шенгена. Команд: 115 — /ru/developers/cli/fleet
Склад и запасы — Склады, бронирования, слоты на рампе, экран ворот, товары, запасы и паллеты. Команд: 69 — /ru/developers/cli/warehouse
Учёт и счета — Счета, проверка входящих счетов, Paraşüt, проводки, поступления и платежи, маржинальность. Команд: 95 — /ru/developers/cli/finance
Сообщения и почта — Чаты по грузам, личные сообщения, черновики и почтовые ящики, уведомления. Команд: 58 — /ru/developers/cli/messages
Тариф и торговые меры — Поиск кодов ТН ВЭД, ввозные пошлины, антидемпинговые меры, отчёты по выбросам. Команд: 20 — /ru/developers/cli/tariffs
Компании и команда — Справочник компаний, связи и документы, дочерние компании, сотрудники и приглашения. Команд: 65 — /ru/developers/cli/contacts
Автоматизация и отчёты — Правила автоматизации, собственные отчёты, файлы Excel и PDF, планы работ. Команд: 27 — /ru/developers/cli/automation
Аккаунт и интеграция — Настройки аккаунта и языка, ключи интеграции, пакет, кредиты и кошелёк. Команд: 16 — /ru/developers/cli/account
Интеграция с ERP и CRM — Идентичность: никаких сервисных аккаунтов — вместо них реальный пользователь
ERP или CRM подключается к Logistivo как реальный пользователь компании с персональным токеном доступа, выпущенным в панели. Синтетический сервисный аккаунт — без компании, освобождённый от ограничения областью видимости, без ответственного лица — никогда не создаётся.
Это архитектура, а не предпочтение. Мультитенантная изоляция целиком опирается на компанию пользователя; для идентичности без компании область изоляции перестаёт действовать, и один неверный запрос с таким токеном прочитает данные, которые ему не принадлежат. Вторая причина — аудит: колонка пользователя в журнале связывает «кто это выполнил» с человеком; сервисный аккаунт лишает эту колонку смысла и оставляет интеграцию, выставляющую счета, без владельца. Третья — отзыв: если токен принадлежит человеку, интеграция замолкает, когда этот человек уходит. Мост без владельца — это мост, который годами тихо продолжает записывать данные.
На практике: компания создаёт в панели обычного пользователя (например, «ERP Bridge», за которого отвечает конкретный сотрудник), выдаёт ему узкую роль, выпускает токен из сессии этого пользователя и помещает его в ERP.
Этот пользователь виден в системе разрешений, его права можно урезать, а его токен можно отозвать отдельно. Запрещено не создание аккаунта, а создание аккаунта, не привязанного к тенанту.
Одна интеграция — один токен. Если две системы делят токен, гранулярность отзыва пропадает: отключить CRM значит отключить и ERP.
Интеграция с ERP и CRM — Версионирование и устаревание
Ответ каталога содержит целое число contract_version; строки команд содержат since, deprecated_at и replaced_by. Версия контракта растёт только при ломающих изменениях.
Версия НЕ растёт при появлении новой команды, нового необязательного параметра или нового поля в ответе. Потребитель обязан игнорировать неизвестные ему поля; клиент, выдающий ошибку на неизвестное поле, не соответствует контракту.
Версия РАСТЁТ при удалении или переименовании команды, удалении поля ответа, превращении необязательного параметра в обязательный, сужении enum. Старая форма остаётся в силе не менее двух календарных кварталов (6 месяцев) с deprecated_at и replaced_by.
Об устаревании объявляется в каталоге, а не только в changelog. Поскольку клиент строит себя по каталогу, команда с заданным deprecated_at выводит предупреждение без всякого релиза клиента, и интегратор видит его в своих журналах.
API-имя заморожено навсегда. Идентификатор CLI (domain/verb) можно было свободно перекраивать до его объявления; после объявления он меняется только с повышением версии и переходным окном, в течение которого старая пара отдаётся как алиас.
На практике: версию несут ответ каталога и заголовок X-Contract-Version; каждая строка команды содержит since, deprecated_at, replaced_by и aliases (старые пары domain/verb). Вызов устаревшей команды по-прежнему работает и отвечает с заголовком X-Deprecated: name; deprecated_at=…; replaced_by=… плюс объектом deprecated в теле. ?domain= в каталоге сопоставляет старый домен-алиас с текущей командой.
Клиент, который понимает версию 1 и встречает большее число, должен записать предупреждение в журнал и продолжить работу; lg делает именно так. Действующие выводы из употребления перечислены выше, в обещании стабильности.
Интеграция с ERP и CRM — Стабильные идентификаторы: никогда не отдавайте своей ERP автоинкрементный id в качестве ключа
Внутренние автоинкрементные id непрозрачны и ограничены тенантом: корректный id другой компании возвращает вам «не найдено», а не данные. Но непрозрачность не делает их бизнес-ключами. То, что ERP хранит в собственной записи, должно быть бизнес-ключом.
Груз: code (код клиента, например FSK2158). loads get уже работает по коду.
Страна: ISO 3166-1 alpha-2. countries search возвращает этот код.
HS / тариф: сам код — номенклатура и так универсальна.
Счёт: номер счёта после выставления. У черновика есть только surface id, и id черновика НЕ является бизнес-ключом — ERP должна хранить собственную ссылку и никогда не сохранять id черновика.
Товар, склад, контакт: сегодня только surface id. Правило для новых команд явное: любая команда, возвращающая surface id, возвращает также собственный бизнес-ключ тенанта (SKU, код, налоговый номер), чтобы ERP могла сопоставлять записи на своей стороне.
Интеграция с ERP и CRM — Пагинация, фильтрация и инкрементальная синхронизация
Команды списков принимают limit и возвращают count. Для ночной синхронизации контракт обязуется соблюдать следующее; команда списка, которая это внедрила, объявляет cursor и updated_since в своей JSON Schema, а пока этого нет, считайте её небольшим окном (максимум 20 строк, без курсора).
Запрос: limit (от 1 до предела конкретной команды) плюс cursor (непрозрачный, только вперёд, подписан сервером). offset НЕ используется — в живой таблице смещение сдвигается; запись, вставленная между двумя страницами, заставляет ERP пропустить строку или учесть её дважды, и происходит это молча.
Ответ: { count, total?, next_cursor|null }. count — число строк в этом ответе; когда next_cursor равен null, список получен полностью. Передавайте next_cursor обратно без изменений — это не номер страницы, и собирать его не вам.
Подделанный или чужой курсор отклоняется с 422 invalid_request; курсор привязан к компании, которая его получила, и не может листать данные другого тенанта.
Фильтрация: именованные параметры из JSON Schema, объединяемые через AND. Свободного языка запросов нет — DSL стал бы второй поверхностью запросов, которую нам пришлось бы защищать.
Инкрементальная синхронизация: updated_since (ISO-8601, UTC) плюс курсор. Сохраняйте самый новый updated_at, который вы видели, и передавайте его при следующем запуске; без этого каждая ERP каждый час заново скачивает всё.
Внешняя ссылка: команды записи принимают external_ref (ваш собственный ключ документа), уникальный в пределах компании; повторное создание с тем же external_ref отклоняется, а не дублируется, а list/get возвращают его, чтобы вы могли сопоставлять записи на своей стороне.
Интеграция с ERP и CRM — Ограничения частоты запросов
Ключ лимита — токен, а не IP: ERP приходит из-за одного NAT, и лимит по IP считал бы всю компанию одним пользователем. Две интеграции с двумя ключами никогда не съедают квоту друг друга — это вторая причина правила «одна интеграция — один ключ».
Обнаружение без аутентификации (public/cli/catalog): 30 в минуту. Это справочник, а не источник данных; прочитайте его один раз, пока пишете мост, и никогда не вызывайте в рабочем цикле.
Эндпоинты каталога (GET common/commands, GET common/commands/{name}): 120 в минуту на токен. Каталог меняется редко и отвечает 304 на If-None-Match; не запрашивайте его заново перед каждой командой — lg кэширует его на час.
Команды чтения (POST common/commands/{name} с read_only: true): 120 в минуту на токен.
Команды записи (POST common/commands/{name} с read_only: false; неизвестное имя тоже учитывается здесь): 30 в минуту на токен. У записи есть побочные эффекты; за вышедший из-под контроля цикл придётся платить.
Команды, расходующие кредиты (credit_cost в строке каталога не равен нулю — например, tariffs inquiry и export-documents generate): реальный лимит — КРЕДИТЫ, а не число запросов. Ответ 200 может означать, что кредит уже потрачен.
Дневные потолки на компанию, общие с панелью: команды, отправляющие e-mail или push людям за пределами вашей компании, расходуют лимит в 300 исходящих уведомлений в день, а запуск платного отслеживания контейнеров или судов — 100 в день. Сверх потолка команда отвечает DAILY_LIMIT_REACHED с retry_after; у загрузки файлов свои потолки (см. «Команды, принимающие файлы»).
429 всегда содержит Retry-After и тело { error_code: "rate_limited", retry_after, limit, bucket }; соблюдайте его, а не придумывайте фиксированную задержку. Каталог публикует текущие значения в rate_limits.
Интеграция с ERP и CRM — Чего мы делать не будем
Часто это самая полезная часть контракта: зная, что не появится никогда, вы можете заранее спроектировать обходной путь.
Никакого сервисного аккаунта и никакого субъекта доступа, не привязанного к тенанту.
Никаких платежей, номеров карт или юридических согласий через API или чат. Эти шаги остаются в браузере человека; команда выдаёт вам ссылку.
Никакого второго пути: нет прямого доступа к базе данных, нет доступа к оболочке и нет массового эндпоинта в обход единой точки контроля. Шлюз ролей, шлюз подтверждения, идемпотентность и журнал аудита обеспечиваются только там.
Ветвление по тексту сообщения об ошибке не поддерживается; текст локализован и меняется без предупреждения.
Никакой пагинации через offset.
Использование surface id в качестве бизнес-ключа в вашей ERP не поддерживается.
Исходящие вебхуки не втиснуты в этот контракт — но теперь они СУЩЕСТВУЮТ и описаны на этой странице (раздел о вебхуках выше). Каталог — это поверхность PULL, а поток событий — ОТДЕЛЬНЫЙ контракт: имена событий и схема payload версионируются по собственным правилам и не привязаны к версии контракта каталога команд.
Машиночитаемый каталог
Эта страница написана для людей. Для ИИ-ассистента или автоматизированного клиента та же информация существует в виде структурированной копии, не требующей аутентификации.
GET /api/public/cli/catalog не требует аутентификации и возвращает публичную идентичность команд: замороженное API-имя, идентификатор CLI domain/verb, описание, параметры JSON Schema, флаги read_only, confirmation_needed и irreversible, credit_cost, а также поля доступа key_level, permission, file_params, secret_parameters и cli_only. Он не возвращает ни персональных данных, ни данных тенантов, ни образцов записей — только то, из чего состоит поверхность.
Правильный способ использования для внешнего агента: прочитать каталог, объяснить СВОИМИ словами, какие задачи возможны, а когда нужно выполнение — предложить пользователю запустить его в собственной среде с собственным токеном. Агент никогда не запрашивает, не генерирует и не передаёт токен пользователя.
Подключение Logistivo к ИИ-ассистенту для регистрации и заявок на перевозку — это отдельный канал со своей страницей:
Каталог не требует аутентификации; выполнение — требует. Запустить команду от имени агента невозможно — выполнение всегда идёт от собственной идентичности пользователя.
Пароль Logistivo, код подтверждения или токен доступа никогда не проходят через чат. Не стройте поток, который запрашивает, генерирует или передаёт их.
Необратима ли команда, указано в каталоге. Никогда не предлагайте «давайте попробуем» для команды с irreversible: true.
Команды с ненулевым credit_cost (например, tariffs inquiry и export-documents generate) имеют денежный результат; не вызывайте их в автоматическом цикле.
Платежи, номера карт и юридические согласия никогда не проходят через чат или агента. Вместо этого предложите ссылку из handoff-links generate; человек завершит шаг в собственном браузере.
Агент, действующий с ключом пользователя, должен сначала вызвать users get: команда возвращает роль, уровень доступа ключа, фактические разрешения и то, не блокирует ли запись ожидающее согласие или подтверждение телефона, — предсказывайте отказы, а не собирайте их.
Текстовый двойник этой страницы находится по адресу /cli.md; используйте его, если markdown вы разбираете надёжнее, чем HTML.
Машиночитаемое описание: OpenAPI 3.1 и Postman
Каталог выше — собственный формат Logistivo. Та же информация публикуется и в двух отраслевых стандартных форматах, которые уже понимают ваши инструменты: описание OpenAPI 3.1 и коллекция Postman. Ни одно из них не написано вручную — оба генерируются из живого реестра команд при каждом запросе, поэтому устареть не могут.
Описание — это и ЕСТЬ каталог, а не вторая реальность. Каждая команда представлена как операция POST /api/common/commands/; схема тела — собственная JSON Schema команды (байт в байт то, что видит ассистент), схема ответа — общий конверт, флаги шлюзов (read_only, confirmation_needed, irreversible и значок кредитов) находятся в расширении x-logistivo, а ключи бизнес-ошибок — в x-error-keys. Выведенная из употребления команда помечается deprecated: true и остаётся вызываемой в течение своего шестимесячного окна.
Помимо командной поверхности, в описание входят и REST-эндпоинты, несущие интеграционный контракт: 10 (эндпоинты списков с инкрементальной синхронизацией: updated_since + cursor + limit) и 7 (эндпоинты записи, принимающие ваш собственный ключ external_ref). REST-поверхность Logistivo гораздо больше; всё остальное исключено НАМЕРЕННО. Эти payload — собственный контракт продукта, и схема, написанная наугад, сломала бы ваш сгенерированный клиент на первом же вызове — а ошибку вы искали бы в своём коде, а не в нашем.
Описание генерируется для РОЛИ того, кто запрашивает: команда другой роли никогда не попадает в документ, потому что описание — это контракт, а не словарь, и всё внутри него должно быть вызываемым с этим токеном. Версия без аутентификации — объединение трёх ролей, и там каждая операция указывает в x-logistivo.roles, каким ролям она видна.
Не верьте нам на слово — проверьте: npx @redocly/cli lint logistivo-openapi.json проходит без единого предупреждения.
GET /api/common/spec/openapi.json — Описание OpenAPI 3.1 для роли вашего токена. Отдаётся с ETag; If-None-Match даёт вам 304, так что вы не скачиваете его заново при каждой сборке.
GET /api/common/spec/postman.json — Тот же охват в виде коллекции Postman v2.1 с переменными base_url и token и папками, уже сгруппированными по доменам команд.
GET /api/public/cli/openapi.json — Версия без аутентификации — объединение трёх ролей. Для проектирования моста и оценки его стоимости ещё до получения токена.
GET /api/public/cli/postman.json — Коллекция Postman без аутентификации: один файл, который можно передать коллегам.
Операций: 761 — 721 (команды) + 36 (REST-операции и операции плоскости управления) + 4 (эндпоинты каталога и идентификации). Числа на этой странице не набраны вручную; они подсчитываются по живому документу при каждом запросе, поэтому в день выхода команды они растут и здесь — и сходятся в сумме.
Схема безопасности — bearerAuth: токен Passport, выданный реальному пользователю. Ключ с областью read может вызывать только операции с флагом x-logistivo.read_only: true; попытка записи возвращает 403 ДО шлюза подтверждения, поэтому ключ только для чтения никогда не видит 409.
Каждая ветка ошибок расписана — Каждая операция описывает 401/403/404/409/422/429/500 по отдельности. Два значения 409 (требуется подтверждение / конфликт идемпотентности) и два значения 422 (ошибка схемы / бизнес-отказ) в документе различаются, поэтому ваш генератор не сливает их в одну ветку.
Без метки времени — Документ не содержит времени генерации. Один и тот же каталог даёт одни и те же байты, поэтому ETag действительно работает, а описание, которое вы закоммитили в систему контроля версий, не выглядит «изменённым» после каждого скачивания.
Мы не выдумывали payload продукта — В REST-эндпоинтах записи описано только контрактное поле (external_ref); остальная часть тела остаётся открытой как additionalProperties: true, а читатель направляется к документации продукта. Неполное, но правдивое описание лучше полного, но выдуманного.
Список ключей ошибок для операции НЕ исчерпывающий — x-error-keys перечисляет только ключи, которые с уверенностью следуют из собственной записи команды, и прямо сообщает об этом через x-error-keys-exhaustive: false. Полный словарь находится в корне документа; любой незнакомый ключ считайте общей ошибкой. Выдуманный «полный список» подтолкнул бы вас никогда не писать ветку default.
Инструментов обнаружения в описании нет — search_commands, run_command и list_capabilities существуют только внутри цикла чата и не могут вызываться по HTTP. Если бы их включили, ваш генератор написал бы три метода, которые никогда не смогли бы работать.
Генерация кода: типизированный клиент из описания
Описание у вас есть; теперь сгенерируйте из него работающий код. `lg codegen` читает документ OpenAPI и записывает однофайловый клиент без зависимостей — на TypeScript (объявления типов плюс тонкая обёртка вызовов) или на PHP (класс клиента с формами массивов в PHPDoc). Никакого `npm install`, никакого composer: `fetch` на стороне TypeScript, `ext-curl` на стороне PHP.
Генерация происходит на ВАШЕЙ машине, а не на нашем сервере. Это не вопрос вкуса: закрепите описание в своём репозитории один раз (`lg spec --out=...`), и одна и та же команда будет выполняться при каждой сборке без сети и без токена, так что ваш CI никогда не зависит от доступности наших серверов. А поскольку сгенерированный код — это код, который РАБОТАЕТ в вашей ERP, хранение его в вашем репозитории, а не получение через API, означает, что каждое изменение видно в `git diff`.
Сгенерированный клиент правильно обрабатывает все три канала Logistivo и узнаёт, какой из них какой, из документа, а не угадывает: каждая операция объявляет свой канал в `x-logistivo.surface`. Командный канал разворачивает конверт `{success, data:{…}}`; REST-список синхронизации НЕ обёрнут в конверт и возвращается как есть (если его развернуть, потеряется `next_cursor`); REST-запись возвращает собственное продуктовое тело эндпоинта. Генератор общего назначения этого различия не знает — наш знает.
Типы не угаданы: интерфейс аргументов каждой команды генерируется из той самой JSON Schema, которую видит ассистент. Обязательное остаётся обязательным, enum становятся объединёнными типами (union), вложенные объекты — вложенными типами. На практике: если сервер требует поле, вызов, в котором оно забыто, падает не с 422 в продакшене, а на этапе компиляции.
Метка времени генерации в файл не записывается: одно и то же описание с одними и теми же флагами даёт одни и те же байты. Поэтому повторная генерация не создаёт шума в `git diff`, а единственное, что действительно изменилось, — контракт — остаётся на виду.
1. Закрепите описание — Описание генерируется для вашей роли; каждую операцию в нём можно вызвать с этим токеном. Закоммитьте файл. lg login --api-key= lg spec --out=logistivo-openapi.json
2. Сгенерируйте клиент — На выходе получается один файл, в котором КАЖДАЯ операция закреплённого вами описания представлена методом: команды, которые может вызывать ваша роль, REST-эндпоинты, несущие интеграционный контракт, и эндпоинты обнаружения. Количество — для ВАШЕЙ роли, а не общее по платформе: сегодня ключ грузоотправителя даёт методов команд — 646, перевозчика — 621, таможенного брокера — 392. Если генерировать из публичного описания без аутентификации, максимум операций — 761. lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # or straight from the server, without downloading first: lg codegen ts --out=logistivo-client.ts
3. Проверьте, затем используйте — Если сгенерированный код не компилируется, виноваты мы, а не вы: целостность описания охраняется исполняемой проверкой на сервере. npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
Один метод на операцию — Каждая команда в документе, каждый REST-эндпоинт, несущий интеграционный контракт, и эндпоинты обнаружения. Генерируйте из описания своей роли — и получите только то, что можете вызвать (для грузоотправителя команд — 646); генерируйте из публичного описания — и получите все операции (761). В день, когда на сервере добавляется команда, повторная генерация приносит её; ждать релиза клиента не нужно.
Типы аргументов — Схема `args` каждой команды становится интерфейсом (формой массива в PHP). Обязательные поля остаются обязательными, enum становятся union-типами. В TypeScript забытое обязательное поле — ошибка компиляции; в PHP ту же форму видят ваша IDE и PHPStan.
Классы ошибок — Транспортная таксономия (`error_code`) и бизнес-таксономия (`error_key`) — отдельные поля; шлюз подтверждения и rate limit — отдельные типы ошибок. Объединение ключей ошибок остаётся открытым для неизвестных значений: когда сервер объявляет новый ключ, ваш код не перестаёт компилироваться, а попадает в ветку `default`.
Правильная политика повторов — Автоматические повторы применяются только к безопасным вызовам: чтению и записи с ключом идемпотентности. Запись без ключа, завершившаяся по тайм-ауту, не означает, что «ничего не записано», поэтому клиент никогда не повторяет её вслепую. При 429 он ждёт серверный `Retry-After`, а не придумывает задержку.
Тела результатов не типизированы — Результаты команд возвращаются как `unknown` (`mixed` в PHP) по той же причине, что и в самом описании: форма результата — это бизнес-вывод команды, а не часть контракта. Угаданный тип результата начал бы лгать при первом же перемещении поля.
Сгенерированный файл не правят вручную — Это результат, а не исходник. Если вам нужно дополнительное поведение, оберните сгенерированный класс; всё, что вы напишете внутри него, пропадёт при следующей генерации.
Инструменты обнаружения не генерируются — `search_commands`, `run_command` и `list_capabilities` живут только внутри цикла чата и не могут вызываться по HTTP; их нет в описании, а значит, и в клиенте. Включить их означало бы написать три метода, которые никогда не работают.
Честные границы
Мы скорее расширим этот раздел, чем сократим его. Ценность интеграционного контракта не столько в том, что он обещает, сколько в том, насколько ясно он говорит, чего не делает.
CLI работает в контексте пользователя тенанта — Каждая команда выполняется от имени компании и роли пользователя, чей токен предъявлен. Режим оператора платформы — административный режим, читающий данные разных компаний, — находится вне этой поверхности и отсюда открыт не будет.
Ваш список команд зависит от роли — Число команд для аккаунта грузоотправителя — 646, перевозчика — 621, таможенного брокера — 392, аффилиата — 55. Если команды нет в вашем каталоге, сначала проверьте роль; если она в списке, но вызов отклоняется, проверьте область доступа и уровень доступа ключа. У аккаунтов водителей доступа к этой поверхности нет вовсе.
Некоторые команды расходуют кредиты — Запросы по таможенным тарифам, генерация документов и несколько других команд на базе ИИ расходуют баланс кредитов вашего плана подписки. Каждая строка каталога содержит credit_cost {mode, credits}: fixed — точная плата за вызов, read_only никогда не списывает кредиты, а computed означает, что плата зависит от вызова, — тогда credits равно null, а реальная сумма показывается на карточке подтверждения. Предварительная проверка (dry_run) сообщает, сколько спишет один вызов и покрывает ли это ваш баланс.
Ключи интеграции не могут управлять чатом панели — ИИ-ассистент в панели предназначен для людей. Запуск или продолжение работы ассистента с ключом интеграции отклоняется с 403; агенты используют эндпоинты команд, lg или канал MCP, где каждая команда выполняется на уровне доступа ключа, а её записи регистрируются как записи интеграции.
Каталог не заменяет существующий REST API — REST-поверхность, на которой работают веб- и мобильные приложения Logistivo, остаётся на месте и по-прежнему подчиняется правилу обратной совместимости. Каталог команд не заменяет CRUD ресурсов; это уровень ГЛАГОЛОВ — единый, проходящий аудит способ что-либо сделать.
Команды списков сегодня возвращают небольшие окна — Пока команда списка не объявит cursor и updated_since в своей схеме, её предел — 20 строк без курсора. Она не предназначена для выгрузки полной копии ваших данных; инкрементальная синхронизация внедряется команда за командой.
Часто задаваемые вопросы
Для чего используется Logistivo CLI?
Он выполняет работу вашего аккаунта Logistivo из терминала, скрипта или вашего собственного ИИ-агента: грузы и рейсы, заявки, ставки и тендеры, автопарк, водители и их расходы, документы, контакты и взаиморасчёты, счета и бухгалтерия, склад и запасы, сотрудники, тарифы HS и антидемпинговые пошлины. У каждого действия записи в панели есть команда; платежи, юридические согласия и закрытие аккаунта намеренно остаются в браузере. Те же команды можно вызывать по HTTP для интеграций с ERP/CRM и через канал MCP.
Как называются команды в Logistivo CLI?
Форма такая: lg --parameter=value. Домен — сущность во множественном числе (loads, demands, invoices, export-documents), а глагол берётся из закрытого словаря, который пополняется только по осознанному решению (list, get, create, update, search, set-status, generate и так далее). Все глаголы одной сущности живут в одном домене, а пара (domain, verb) уникальна во всём каталоге.
Как пройти аутентификацию в CLI?
В интерактивном режиме lg login показывает код одобрения, который вы подтверждаете в браузере после входа в Logistivo, — ни пароль, ни ключ в терминал не вводятся, а сессия остаётся активной и сама продлевается, пока вы не выполните lg logout. lg login --password (email и пароль) остаётся запасным вариантом. На серверах и в CI используйте ключ интеграции, выпущенный в панели или командой lg keys create: lg login --api-key сохраняет его в локальный профиль; либо поместите его в переменную окружения LOGISTIVO_TOKEN. По HTTP токен передаётся в заголовке Authorization: Bearer.
Можно ли создать сервисный аккаунт для интеграции с ERP?
Нет. Интеграция подключается с токеном реального пользователя компании, созданного в панели. Синтетическая идентичность без компании выводит из строя мультитенантную изоляцию, лишает смысла колонку «кто это выполнил» в журнале аудита и оставляет мост, который не замолкает, когда его владелец уходит. Правильный подход — отдельный пользователь с узкой ролью и названным ответственным.
Есть ли у Logistivo тестовая среда (песочница)?
Да, и она открывается самостоятельно: для вашей компании создаётся отдельный тенант-песочница — тот же код, тот же каталог команд, собственный журнал кредитов. Среда определяется по компании ключа и не может быть передана в запросе; вызов с неверным профилем останавливается на сервере с 403 ENVIRONMENT_MISMATCH. Заявка, открытая в песочнице, никогда не доходит до реальных перевозчиков, событие песочницы никогда не доставляется в вашу боевую подписку на вебхуки, а ваш боевой баланс не меняется. Эндпоинты: POST /api/common/integration-sandbox (открыть), POST /api/common/integration-sandbox/keys (ключ), GET /api/common/integration-sandbox/go-live (чек-лист перехода в боевой режим). На стороне lg флаги lg --sandbox и lg --live выбирают профиль для одного запуска.
Как читать вывод lg --json в скрипте?
Вывод — это весь HTTP-конверт: { "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }. Бизнес-данные лежат в .data.result; в командах списков строки — это .data.result., количество — .data.result.count, а следующая страница — .data.result.next_cursor. Поэтому правильный путь jq выглядит так: lg loads list --json | jq -r '.data.result.loads[].load_code'. Путь, пропускающий конверт, не выдаёт ошибку, а молча возвращает null — в сторожевом скрипте это превращается в тревогу, которая никогда не перестаёт срабатывать. Единственное исключение — /api/public/status, тело которого намеренно отдаётся без конверта.
Если отправить один и тот же запрос дважды, появятся ли дубликаты записей?
Нет, если вы отправили idempotency_key. Второй вызов с тем же ключом не выполняет команду заново, а возвращает первый результат со статусом replayed. Ключ должен быть UUID и обязан оставаться ОДНИМ И ТЕМ ЖЕ во всех повторах — генерировать новый ключ для каждой попытки всё равно что не использовать идемпотентность.
Что делает --yes?
Проходит шлюз подтверждения. Когда команда со шлюзом вызывается без --yes, ничего не меняется: сервер одним предложением описывает, что собирается сделать, сообщает, необратимо ли это, и останавливается (HTTP 409, код выхода CLI 4). Повтор команды с --yes выполняет работу.
Как обнаружить неудачную команду в скрипте?
Читайте код выхода, а не текст сообщения: 0 — успех, 1 — отказ по бизнес-правилу, 2 — ошибка команды или аргумента, 3 — ошибка аутентификации или роли, 4 — требуется подтверждение. По HTTP эквиваленты — 200, 422, 404, 403 и 409, а поле error_code в теле стабильно. СООБЩЕНИЕ об ошибке локализовано и меняется без предупреждения.
Как программно узнать доступные команды?
GET /api/public/cli/catalog — для обнаружения без аутентификации, и GET /api/common/commands — для списка, который действительно видит ваш аккаунт. Оба возвращают параметры JSON Schema каждой команды; стройте клиент на их основе, а не зашивайте список команд в код.
Нужно ли обновлять клиент при добавлении новой команды?
Нет. Клиент получает список команд из каталога, поэтому команда, добавленная на сервере, появляется без нового релиза клиента. Обновление нужно только при ломающем изменении, которое повышает версию контракта, и в этом случае старая форма остаётся в силе не менее шести месяцев.
Заменяет ли CLI существующий REST API?
Нет. REST-поверхность, на которой работают веб- и мобильные приложения, остаётся на месте. Каталог команд не заменяет CRUD ресурсов; это уровень глаголов — единый способ выполнить действие, проходящий через шлюз ролей, шлюз подтверждения и аудит.
Как получить API-ключ Logistivo и что он может?
Менеджер с разрешением на управление сотрудниками выпускает его в панели в разделе Settings › Integration keys или из терминала командой lg keys create. Ключ действует от имени реального сотрудника и имеет три независимые настройки: область доступа (read открывает каталог и команды без записи, write открывает все команды — шлюз подтверждения остаётся прежним), необязательные доступы к доменам (domain grants) и уровень доступа — employee, по умолчанию, для повседневных операций или manager — для управления сотрудниками, настройками, ключами и деньгами. Ключ показывается один раз и не хранится на сервере; его можно ротировать, передавать и отзывать. Когда сотрудник, от имени которого он действует, уходит, ключ тоже закрывается. Сервисного аккаунта нет.
Что будет, если повторно использовать ключ идемпотентности для другой команды?
Сервер отвечает 409 idempotency_conflict и называет команду, для которой ключ был использован впервые; ничего не выполняется и ничего не воспроизводится. Ключи ограничены вашей компанией, привязаны к одной команде и блокируются на 24 часа — после этого тот же ключ запускает новое выполнение.
Как к моей интеграции применяются ограничения частоты запросов?
На уровне токена, в минуту, в трёх корзинах: чтение каталога — 120, команды чтения — 120, команды записи — 30. Ответ 429 всегда содержит Retry-After и тело с retry_after, limit и bucket; подождите указанное время и повторите. Каталог публикует текущие значения в rate_limits.
Как отличить бизнес-отказ от транспортной ошибки?
Сначала ветвитесь по error_code: failed (422) — бизнес-отказ со стабильным error_key, например INSUFFICIENT_CREDITS или NOT_FOUND; server_error (5xx) и сетевые ошибки повторяются с тем же ключом идемпотентности; rate_limited (429) нужно переждать. Никогда не ветвитесь по тексту ошибки.
Отправляет ли Logistivo вебхуки? Для каких событий?
Да. Вы регистрируете https-адрес и выбираете интересующие вас события; когда они происходят, приходит подписанный POST. Число событий, доступных для подписки сегодня, — 13: груз создан / статус изменён / водитель назначен, заявка создана и её статус изменён, ставка размещена / пересмотрена / принята, черновик счёта / счёт выставлен / отменён, а также складское бронирование создано / статус изменён. За каждым именем стоит класс события, который действительно отправляется, — ничего не анонсируется, чтобы потом так и не сработать, потому что такое событие — незаметный сбой, которого интегратор ждёт вечно. Подписки создаются в разделе Settings › Integration › Webhooks или из терминала командой lg webhooks create.
Как проверить подпись вебхука Logistivo?
Каждый запрос содержит заголовок X-Logistivo-Signature: t=,v1=. Подписываемая строка — ".", алгоритм — HMAC-SHA256, ключ — секрет подписки. Четыре правила: (1) проверяйте СЫРЫЕ байты — декодирование и повторная сериализация тела (JSON.stringify / json_encode) превращают те же данные в другие байты, и подпись перестаёт совпадать; это самая распространённая ошибка; (2) проверяйте метку времени и отбрасывайте всё, где |now − t| > 300 с, даже если подпись верна; (3) сравнивайте за постоянное время с помощью hash_equals / timingSafeEqual; (4) устраняйте дубликаты по event_id, а не по id доставки — event_id сохраняется при replay, а id доставки меняется. Рабочие приёмники на Node и PHP лежат в репозитории в examples/webhook-receiver/ и проверяют себя флагом --selftest.
Что происходит, если вебхук не удаётся доставить? Я теряю событие?
Нет. Если ваш приёмник не возвращает 2xx, доставка попадает в график повторов: интервалы — 60 · 300 · 1800 · 7200 · 21600 с, всего попыток — 6, окно примерно 8,6 ч. Повторяется КАЖДЫЙ сбой, кроме 410 Gone, включая 4xx: потеря бизнес-события стоит дороже, чем несколько лишних запросов. После серии подряд исчерпанных доставок (порог — 10) подписка приостанавливается, а причина записывается, так что на вопрос «почему ничего не приходит» всегда есть ответ. Журнал доставок хранит каждую попытку (код статуса, длительность, ошибку), и вы можете повторно отправить отдельную доставку из панели или командой lg webhooks replay. Инкрементальная синхронизация (updated_since + cursor) по-прежнему остаётся страховочной сетью.
Может ли мой ИИ-агент делать всё, что пользователь может делать в панели?
Почти всё. У каждого действия записи в панели есть команда — по замеру относительно эндпоинтов записи панели покрыто 100% эндпоинтов, входящих в охват, — и те же команды открыты для lg, HTTP и канала MCP. Намеренные исключения — шаги, связанные с идентичностью и деньгами: вход, покупка пакета, добавление карты с 3D Secure, принятие юридических текстов и закрытие аккаунта остаются в браузере человека, а lg handoff-links generate возвращает для них ссылку. Ключи интеграции, вебхуки и песочница управляются встроенными командами lg, потому что они однократно возвращают секреты.
Можно ли передавать командам файлы — например, PDF или фото — из CLI или через API?
Да. В lg поставьте @ перед локальным путём (--attachment_uuid=@./cmr.pdf), и lg сначала загрузит файл; --file — сокращение для команды с единственным файловым полем, а lg upload только загружает файл. По HTTP отправьте файл как multipart на POST /api/common/commands:upload и передайте полученный attachment_uuid команде; MCP-клиенты используют инструмент upload_attachment. Тип определяется по содержимому, загрузки принадлежат пользователю и остаются пригодными к использованию 24 ч, а повторная загрузка того же файла возвращает тот же id.
Чем ключ интеграции уровня employee отличается от ключа уровня manager?
Уровень доступа определяет, насколько серьёзную работу может выполнять ключ. Ключ employee — по умолчанию для новых ключей — выполняет повседневные операции: грузы, заявки, ставки, рейсы, автопарк, документы и контакты. Ключ manager может выполнять и управленческую работу — сотрудники и роли, настройки компании, ключи интеграции, банковские счета, сохранённые карты, выплаты аффилиатам. Ключ никогда не получает больше прав, чем человек, от имени которого он действует, а ключ employee, вызывающий команду уровня manager, получает INSUFFICIENT_KEY_LEVEL. Изменить уровень можно в панели или командой lg keys update --access-level=manager.
Может ли аффилиат (реферальный партнёр) использовать CLI?
Да. Аккаунт аффилиата получает собственный каталог — команды для рефералов, лидов, заметок и задач CRM, презентаций для продаж, доходов и выплат (их 55) — и использует его из lg, через HTTP или MCP, как любая другая роль. Запрос или отмена выплаты и смена банковского счёта для выплат требуют ключа уровня manager и подтверждения. Компания, которая одновременно является грузоотправителем, перевозчиком или таможенным брокером, видит оба каталога.
For AI assistants
Logistivo has an MCP server at https://logistivo.com/api/agent/mcp
(streamable HTTP). Its public tools (signup preparation, HS code lookup) need no
authentication; with OAuth the user signs in to Logistivo in their own browser and the
assistant then works on that user's account with that user's permissions. Setup for
Claude, ChatGPT and Gemini: https://logistivo.com/en/mcp.
Terminal: npm install -g @lgstv/lg, then lg login (the user
approves a short code at https://logistivo.com/connect; no password is typed into the
terminal). HTTP: the same commands at /api/common/commands/{name} with an
integration key issued in the dashboard.
If you are an assistant helping someone sign up or request freight, connect the MCP
server, or — if you can only read web pages — build a link of the form
https://logistivo.com/en/ai-kayit?brief=URL_ENCODED_SHIPMENT_BRIEF and give
it to the user. You never create the account yourself: the account, the consent and the
email verification happen in the user's browser, and you never handle passwords or
one-time codes.
Machine-readable content indexes:
https://logistivo.com/llms.txt (curated map) and
https://logistivo.com/llms-full.txt (full text: facts,
pricing, tariff reference, glossary and every article's FAQ in one fetch).
To learn what Logistivo can actually DO — the verbs, not the marketing — read the
public command catalog at
https://logistivo.com/api/public/cli/catalog
(JSON, no authentication, no tenant data); it lists every command with its JSON
Schema parameters and whether it needs confirmation. Human documentation:
https://logistivo.com/en/developers/cli. Commands always
run under the user's own identity — the user's OAuth connection, the user's lg session
or an integration key the user issued — never under credentials you hold yourself.