Logistivo CLI: управляйте логистикой из терминала и из своей ERP

Один каталог команд питает три поверхности: терминальный клиент lg, ИИ-ассистента в панели управления и канал, к которому подключаются внешние ИИ-ассистенты. Возможность пишется один раз и появляется во всех трёх — и теперь у каждого действия записи в панели есть команда, так что ваши скрипты и ваши собственные ИИ-агенты могут выполнять ту же работу, которую ваши сотрудники выполняют на экране. Платежи, юридические согласия и закрытие аккаунта намеренно остаются в браузере. Эта страница — контракт. Таблица команд ниже не написана вручную: она генерируется из живого реестра команд при каждом запросе.

Что такое Logistivo CLI?

Logistivo CLI (lg) — это клиент командной строки, который выполняет работу вашего аккаунта Logistivo — грузы и рейсы, заявки, ставки и тендеры, автопарк и водители, документы, контакты и взаиморасчёты, счета и бухгалтерия, склад и запасы, сотрудники и таможенные тарифы — из терминала, из скрипта или из вашего собственного ИИ-агента. Команды не зашиты в клиент: клиент получает каталог команд с сервера и строит себя по нему. Те же команды можно вызывать по HTTP, ничего не устанавливая, — этим путём идут интеграции с ERP и CRM, — а также через канал MCP, к которому подключаются внешние ИИ-ассистенты.

• Единая форма команды: lg --parameter=value. Сейчас в каталоге команд — 519, доменов — 125; самый широкий список, который видит одна роль: команд — 452, доменов — 112.
• У каждого действия записи в панели есть команда: по замеру относительно эндпоинтов записи панели покрыто 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}. Шлюз ролей, шлюз подтверждения, идемпотентность и журнал аудита находятся в единой точке контроля, через которую проходят также чат и терминал.
• Покрытие панели: у каждого действия записи есть команда — Команд — 519, доменов — 125; проверено по эндпоинтам записи панели: каждый эндпоинт в охвате обеспечен командой (зеркалом эндпоинта или тем же общим сервисом), и ни один не остался недоказанным. Намеренно вне охвата: платежи с 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, счёт, свидетельство о регистрации транспортного средства, фото паллет, — 33. Загрузите файл один раз на 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 ровно такого размера, как ваш аккаунт — Каталог фильтруется по роли: команда, которую ваша роль не может видеть, никогда не появится в вашем списке. Число команд для аккаунта перевозчика — 452, для грузоотправителя — 448, для таможенного брокера — 312, а у аккаунта аффилиата (реферального партнёра) собственный набор: команд — 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%, и ни один не остался недоказанным. У каждого исключённого эндпоинта есть письменно зафиксированная причина — шаги, связанные с идентичностью и платежами, плоскость управления интеграциями, собственные эндпоинты приложения водителя, клиентская телеметрия, мёртвые копии без вызывающих, — а те, что важны интегратору, перечислены ниже.

Команды, принимающие файл, подчиняются тому же правилу: команд в таблице, принимающих документ или фото, — 33, и все они работают из lg, по HTTP и через MCP (см. «Команды, принимающие файлы»).

Управленческая работа тоже покрыта, но за более сильным ключом: командам в таблице, касающимся сотрудников и ролей, настроек компании, банковских счетов, сохранённых карт и ключей интеграции (их 62), нужен ключ интеграции уровня 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. Ситуация «я думал, что пишу в песочницу, а записал в продакшен» невозможна по построению.

Поверхность идентична — это измерено: каталог, который получает ключ песочницы, — тот же, что получает ваш боевой ключ (для ключа грузоотправителя число команд с обеих сторон — 448). Мост, который работает в песочнице, работает и в продакшене; ничему не придётся учиться дважды.

Песочница открывается не пустой: в ней есть сгенерированные (НЕ скопированные) начальные данные — контакты, грузы в обоих направлениях и заявки. Имена откровенно вымышлены, а 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-уведомлений; и реальных заявок вы тоже не видите. Разделение симметрично и обеспечивается двумя отдельными запросами: кому заявка ВИДНА и кому она ОТПРАВЛЯЕТСЯ — разные вопросы.
• Вебхуки — Подписки тоже несут отметку среды. Событие песочницы никогда не доставляется в боевую подписку, а боевое событие никогда не доходит до подписки песочницы; для подписки, отметка которой разошлась со средой, доставка вообще не открывается. Поскольку потолок подписок считается на компанию, ваши репетиционные подписки не съедают боевую квоту.
• Начальные данные — Образцы записей внутри песочницы СГЕНЕРИРОВАНЫ и никогда не копируются у реальных тенантов. Заполнение идемпотентно: повторный вызов не накладывает второй набор начальных данных поверх ваших собственных записей.
• Тот же каталог — Ваша роль остаётся вашей ролью и в песочнице, а список команд идентичен — измерено: число команд с обеих сторон — 448. Песочница — не урезанная демоверсия, а двойник вашей компании.
• Сегодняшнее ограничение: подписками на вебхуки нельзя управлять ключом песочницы — Эндпоинты подписок требуют разрешения на управление сотрудниками (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.

Команды, принимающие файлы

Команд в таблице, принимающих документ или фото, — 33: прикрепить 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 положил этому конец: вы добавляете в запрос одно поле, команда не выполняется, и вы читаете, что произошло бы.

Сейчас в реестре команд — 519; из них только для чтения (ничего не записывают) — 233. Из оставшихся команд записи — их 286 — шлюз есть у 251: при вызове без confirm они уже отвечают 409 и описывают, что сделали бы. Пробел составляли остальные — их 35: черновики счетов, черновики экспортных документов, строки позиций — ровно та цепочка, которую мост подключает первой. Для них вызвать значило выполнить.

Был и второй пробел, даже в командах со шлюзом: валидация схемы выполняется ПОСЛЕ шлюза. Поэтому вызов с отсутствующим аргументом сначала получал карточку подтверждения, подтверждал её и только потом слышал «этого поля не хватает». Предварительная проверка отвечает на оба вопроса за один обмен запросом и ответом.

А самая частая — и обнаруживаемая позже всех — ошибка моста такова: вы отправляете поле, которого нет в схеме (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 . Команды только для аффилиатов здесь не перечислены; аккаунт аффилиата видит их в собственном каталоге.

• lg account-settings get — Read the account settings (Settings → Account): the company display name (and legal name, read-only), the signed-in user's own name and e-mail (e-mail is read-only here), the saved load code prefix and how the company… (чтение · — · грузоотправитель · API: get_account_settings) [ключ manager]
• lg account-settings update — Change account settings (Settings → Account): company_name (the company's display name, company-wide), first_name / last_name (the signed-in user's own name — when only one is given the other part is kept),… (запись · подтверждение · грузоотправитель · API: update_account_settings) [ключ manager]
• lg accounting-settings get — Read the company's accounting and invoicing settings and say whether they are set up (muhasebe ayarları, fatura ayarları, e-fatura / e-invoice profile, KDV / VAT tax regime, fatura numaralandırma serisi / invoice… (чтение · — · все · API: get_accounting_settings)
• lg accounting-settings set-status — Turn the company's accounting module on or off (muhasebe modülünü aç/kapa). (запись · подтверждение · все · API: set_accounting_module)
• lg accounting-settings update — Update the company's accounting/invoicing settings (muhasebe ve fatura ayarlarını değiştir): legal name, default currency, provider (local/parasut), country, tax regime (KDV/VAT/GST/none), default invoice line… (запись · подтверждение · все · API: update_accounting_settings)
• lg addresses list — Loading and delivery addresses already used on this company's previous loads (newest first): address_id, name, street, city and country. query filters by name, street or city. limit 1-50 (default 20). (чтение · — · все · API: list_worked_addresses)
• lg addresses search — Find a place for a route plan stop: the company's own address book first, then a geocoder (counted against the daily routing allowance) when the book has fewer than 3 hits. (чтение · — · перевозчик · API: lookup_address)
• lg ai-settings get — Read our company's AI switches (Settings → AI), e.g. ai_file_classify ("AI document analysis"): whether files posted into our load chats are read by AI, sorted into document types and split into company documents, or… (чтение · — · грузоотправитель · API: get_ai_settings) [ключ manager]
• lg ai-settings update — Turn our company's AI switches on or off (Settings → AI) — e.g. "stop AI from analysing the files in our load chats" → settings=[{"slug":"ai_file_classify","enabled":false}]. settings is a list of {slug, enabled}; slugs… (запись · подтверждение · грузоотправитель · API: update_ai_settings) [ключ manager]
• lg announcements list — Show the system announcements Logistivo sent to this user (new features, maintenance, policy changes) — newest first. (чтение · — · все · API: list_announcements)
• lg announcements mark-read — Mark system announcements as read for this user. (запись · — · все · API: mark_announcements_read)
• lg attachments get — Read a file the user attached to THIS conversation (listed in the user message as [Attachments] with their attachment_uuid). (чтение · — · все · API: read_attachment) [принимает файл: attachment_uuid]
• lg background-jobs get — Check a background job that another command queued and returned a job_id for (document consistency re-analysis, file classification, tariff inquiry, tariff invoice reading, receipt pack…): status pending / running /… (чтение · — · все · API: get_background_job)
• lg bank-accounts create — Add one of YOUR OWN company bank accounts to the account book (the accounts you get paid into). (запись · подтверждение + необратимо · все · API: create_company_bank_account) [ключ manager]
• lg bank-accounts delete — Delete one of OUR OWN company bank accounts (for example a closed account). (запись · подтверждение + необратимо · все · API: delete_company_bank_account) [ключ manager]
• lg bank-accounts extract — Read a supplier's bank accounts (IBAN, bank, holder, currency) from one of ITS invoices and save them on that business contact. (запись · подтверждение + необратимо · все · API: extract_supplier_bank_accounts) [принимает файл: attachment_uuid]
• lg bank-accounts list — List bank accounts. (чтение · — · все · API: list_bank_accounts)
• lg bank-accounts preview — Check an IBAN without saving anything: is it valid (country, length, checksum) and which bank it belongs to (detected offline from the bank code where known). (чтение · — · все · API: preview_bank_account_iban)
• lg bank-accounts set-default — Make one of OUR OWN bank accounts the default — the IBAN printed on our invoices and e-invoices. (запись · подтверждение + необратимо · все · API: set_default_company_bank_account) [ключ manager]
• lg bank-accounts set-status — Confirm or reject a bank account that was read from a document by AI or written by an integration — your own account or a business contact's account (find the ones waiting with list_bank_accounts… (запись · подтверждение + необратимо · все · API: decide_bank_account_verification) [ключ manager]
• lg bank-accounts update — Update one of OUR OWN company bank accounts (the accounts customers pay us into): IBAN, bank, account holder, branch code, account number or currency. (запись · подтверждение + необратимо · все · API: update_company_bank_account) [ключ manager]
• lg banks list — List the banks of Turkey with their bank_id and SWIFT/BIC code — the bank_id that create_company_bank_account and update_company_bank_account need. (чтение · — · все · API: list_banks)
• lg bids accept — Accept a carrier's bid on one of this company's demands. (запись · подтверждение + необратимо · грузоотправитель · API: accept_demand_bid)
• lg bids calculate — Before bidding: what this carrier would earn and how many credits a bid would cost if the customer accepts it. (чтение · — · перевозчик · API: calculate_bid_earnings)
• lg bids cancel — Withdraw (geri çek) one of THIS carrier company's PENDING bids. (запись · подтверждение + необратимо · перевозчик · API: cancel_demand_bid)
• lg bids create — Submit a bid (teklif ver) on an open demand. amount_per_vehicle is the freight PER VEHICLE, not the total. (запись · подтверждение + необратимо · перевозчик · API: create_demand_bid)
• lg bids get — Detail of ONE bid this carrier company submitted: demand, status (pending / accepted / revised / cancelled / price_too_high), price per vehicle and total, currency, vehicle count, customs included or customs price,… (чтение · — · перевозчик · API: get_my_demand_bid)
• lg bids list — List the bids (teklif) THIS carrier company has submitted, newest first, with their outcome. (чтение · — · перевозчик · API: list_my_bids)
• lg bids revise — Revise this carrier's own PENDING bid on a demand: the old bid is marked revised and a NEW bid replaces it (it gets a new bid code). (запись · подтверждение + необратимо · перевозчик · API: revise_demand_bid)
• lg carbon-reports calculate — Calculate the CO2 emission of an EXISTING load (load_code: weight and route from the load, including its Ro-Ro leg) OR of a route you describe (transport_mode road|roro + weight_kg + departure_address + arrival_address,… (чтение · — · все · API: calculate_load_carbon_emission)
• lg carbon-reports download — Export ALL of the company's saved CO2 emission reports to one Excel file (one row per report: date, route, mode, weight, distance, emission, factor, method) and return a short-lived download link. (чтение · — · все · API: export_carbon_emission_reports)
• lg carbon-reports generate — Produce the signed CO2 emission report (PDF, with QR code) for a load OR for a route, save it to the company's report list and return a download link. (запись · подтверждение + необратимо · все · API: generate_carbon_emission_report)
• lg carbon-reports get — Read one CO2 emission report in full: total emission in kg, transport mode, weight, distance, emission factor, calculation method and source, the departure/arrival addresses, the leg breakdown for multi-modal routes… (чтение · — · все · API: get_carbon_emission_report)
• lg carbon-reports list — List the CO2 emission reports this company has generated (newest first): report number, file name, who created it and when. (чтение · — · все · API: list_carbon_emission_reports)
• lg carrier-routes get — This carrier's route definitions (Rota Yönetimi): the countries served — always ↔ Türkiye in both directions — and the vehicle types and load types operated, with ids and names. (чтение · — · перевозчик · API: get_carrier_routes)
• lg carrier-routes set — REPLACE this carrier's route definitions (Rota Yönetimi) with the given FULL sets: countries served (each to/from Türkiye, both directions), vehicle types and load types. (запись · подтверждение · перевозчик · API: set_carrier_routes) [ключ manager]
• lg chart-of-accounts list — List the chart of accounts available to this company (Turkish uniform chart: 100 Kasa, 102 Bankalar, 120 Alıcılar, 320 Satıcılar, 391 Hesaplanan KDV, 600/601 Satışlar…), optionally filtered by code/name text or type. (чтение · — · все · API: list_chart_of_accounts)
• lg checks assign-invoices — Allocate a pending, field-confirmed cheque to one or more open LOCAL invoices of the same contact and currency: in = sales invoices (collection), out = purchase invoices (payment). (запись · подтверждение + необратимо · все · API: attach_check_to_invoices) [ключ manager]
• lg checks bounce — Record that a cheque BOUNCED (came back unpaid). (запись · подтверждение + необратимо · все · API: mark_check_bounced)
• lg checks cancel — CANCEL a pending cheque (e.g. registered by mistake, returned before use): no journal entry is written and any invoice reservation is released. (запись · подтверждение + необратимо · все · API: cancel_settlement_check) [ключ manager]
• lg checks collect — Record that a cheque was COLLECTED (money reached the bank for an incoming cheque, or left the bank for an outgoing one) on its due date. (запись · подтверждение + необратимо · все · API: mark_check_collected)
• lg checks create — Register a cheque in the cheque portfolio. (запись · подтверждение · все · API: create_settlement_check) [ключ manager] [принимает файл: front_attachment_uuid, back_attachment_uuid]
• lg checks get — Read one cheque in full: its identity (number, serial, bank and branch, drawer with tax number, IBAN), the face amount and currency, issue and due dates, the counterparty, the status with every timestamp (executed,… (чтение · — · все · API: get_settlement_check)
• lg checks list — List the cheque portfolio of this company: cheque number, direction (in = received from a customer, out = given to a supplier), drawer and bank, face amount with its currency, issue and DUE date, the counterparty… (чтение · — · все · API: list_settlement_checks)
• lg checks remove-invoices — Release a pending cheque's invoice allocation: the reservations are removed (invoices become payable again) and the cheque goes back to the unallocated pending cheques. (запись · подтверждение · все · API: detach_check_from_invoices) [ключ manager]
• lg checks run — EXECUTE a pending, allocated cheque against its invoices: the reservations become payments (the invoice balances close), and the notes receivable (121, received cheque) or notes payable (321, given cheque) journal… (запись · подтверждение + необратимо · все · API: execute_settlement_check) [ключ manager]
• lg checks update — Correct a pending cheque's fields and CONFIRM them — the human sign-off on what AI read from the photo (or on a manual entry). (запись · подтверждение · все · API: update_settlement_check) [ключ manager]
• lg companies add-role — Add a role to this company (firmaya rol ekle): customer (shipper), carrier, customs (customs broker) or affiliate. (запись · подтверждение + необратимо · все · API: add_company_role) [ключ manager]
• lg companies delete-logo — Remove this company's logo (firma logosu) from the branded login portal, documents and the panel. (запись · подтверждение + необратимо · все · API: delete_company_logo) [ключ manager]
• lg companies get — This company's own profile (firma profili): legal name, tax number and tax office, address and postal code, city/country, payment term (vade), the company roles it has (customer/carrier/customs/affiliate) and the roles… (чтение · — · все · API: get_company_profile)
• lg companies invite — Invite a company that is NOT on Logistivo yet by e-mail (e.g. a carrier we want to give a load to). (запись · подтверждение + необратимо · все · API: invite_company_to_platform)
• lg companies list — Logistivo platform companies this company has already worked with on loads (shared load chats), by company_type: customer (shippers), carrier or customs (customs brokers). (чтение · — · все · API: list_platform_companies)
• lg companies search — Check whether a company is on Logistivo — by EXACTLY ONE of: tax_number (exact VKN / tax id), vat_number (exact EU/UK VAT number) or email (any e-mail of that company, matched by its domain; then company_type is… (чтение · — · все · API: search_platform_companies)
• lg companies set-brand-colors — Set the two colours of this company's branded login portal (markalı giriş portalı, /p//login) — primary_color and secondary_color as #RRGGBB hex. (запись · подтверждение · перевозчик, таможенный брокер · API: set_company_brand_colors) [ключ manager]
• lg companies set-logo — Make an uploaded image this company's logo (firma logosu) — shown on the branded login portal, documents and the panel. attachment_uuid is a JPEG or PNG image (max 8 MB) uploaded to this conversation or with `lg upload`. (запись · подтверждение + необратимо · все · API: set_company_logo) [ключ manager] [принимает файл: attachment_uuid]
• lg companies update — Update this company's profile (firma profili) — send ONLY the fields that change: legal_name (ticaret unvanı), tax_number (VKN / VAT id), tax_branch (vergi dairesi), address_street, postal_code, city_id, country_code… (запись · подтверждение · все · API: update_company_profile) [ключ manager]
• lg company-documents create — File a document the user attached (in this chat, or uploaded to the command surface) as one of the company's own documents (firma evrakı yükle): tax certificate (vergi levhası), signature circulars (imza sirküleri),… (запись · подтверждение · все · API: upload_company_document) [принимает файл: attachment_uuid]
• lg company-documents delete — Remove one of the company's own documents (tax certificate, signature circular, trade registry gazette, permits…) from its document list — e.g. a wrong or outdated upload. document_id is the one shown by… (запись · подтверждение + необратимо · все · API: delete_company_document)
• lg company-documents list — List this company's own filed documents (tax certificate, signature circulars, trade registry gazette, contracts, TIO/L2 permits, files uploaded to chats…) with their type, number, validity date and verification status. (чтение · — · все · API: list_company_documents)
• lg company-documents list-missing — Which company documents (tax certificate, signature circulars, trade registry gazette, TIO/L2/C2 permits …) this company is REQUIRED to have for its company type and country, which of them are on file and verified, and… (чтение · — · все · API: list_missing_company_documents)
• lg company-domains create — Add an e-mail domain to our company (e.g. firma.com.tr) and e-mail a 6-digit verification code to a mailbox ON that domain. (запись · подтверждение + необратимо · все · API: create_company_domain) [ключ manager]
• lg company-domains delete — Remove one of our UNVERIFIED company domains (e.g. added by mistake). (запись · подтверждение + необратимо · все · API: delete_company_domain) [ключ manager]
• lg company-domains list — List our company's e-mail domains (Company settings → Domains): each row has company_domain_id, domain, verified (true once the 6-digit code was entered) and, for unverified ones, the mailbox the last code was sent to. (чтение · — · все · API: list_company_domains)
• lg company-domains resend — E-mail a NEW 6-digit verification code for one of our unverified company domains (the previous code stops working). (запись · подтверждение + необратимо · все · API: resend_company_domain_code) [ключ manager]
• lg company-domains verify — Verify one of our unverified company domains with the 6-digit code that was e-mailed to the mailbox on that domain. (запись · подтверждение + необратимо · все · API: verify_company_domain) [ключ manager]
• lg company-relationships accept — Accept a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (запись · подтверждение + необратимо · все · API: accept_company_relationship) [ключ manager]
• lg company-relationships create — Send a connection proposal to link one of our business contacts with its company on the Logistivo platform (company_id from search_platform_companies). (запись · подтверждение + необратимо · все · API: create_company_relationship) [ключ manager]
• lg company-relationships list — List our company connections on the platform (direction=outgoing, default: the connections in our directory, with status and roles such as carrier/customs_broker/supplier) or the connection proposals other companies… (чтение · — · все · API: list_company_relationships)
• lg company-relationships reject — Reject a connection proposal another company sent us (relationship_id from list_company_relationships direction=incoming). (запись · подтверждение + необратимо · все · API: reject_company_relationship) [ключ manager]
• lg company-relationships revoke — End a company connection we are a party of (either side may end it), or withdraw a pending proposal. (запись · подтверждение + необратимо · все · API: revoke_company_relationship) [ключ manager]
• lg contacts add-address — Add an address to a business contact (e.g. a warehouse or branch): a label, the full street address and the country (ISO-2 code); postal code optional. (запись · подтверждение · все · API: add_business_contact_address)
• lg contacts add-bank-account — Add a bank account (IBAN) to a business contact so it can be used on payment instructions and invoices. (запись · подтверждение + необратимо · все · API: add_business_contact_bank_account)
• lg contacts add-person — Add a person (yetkili kişi) to a business contact: first name, last name and e-mail are required; phone, phone country code, job title and a note are optional. (запись · подтверждение · все · API: add_business_contact_person)
• lg contacts archive — Archive a business contact (cariyi arşivle): it disappears from lists and pickers and becomes read-only, but nothing is deleted — invoices, loads and bank accounts stay linked, and restore_business_contact brings it… (запись · подтверждение · все · API: archive_business_contact)
• lg contacts create — Create a new business contact (cari) in the company directory. (запись · подтверждение · все · API: create_business_contact)
• lg contacts delete-address — Delete one of a business contact's addresses. (запись · подтверждение + необратимо · все · API: delete_business_contact_address)
• lg contacts delete-bank-account — Delete one of a business contact's bank accounts (for example an old or wrong IBAN). (запись · подтверждение + необратимо · все · API: delete_business_contact_bank_account)
• lg contacts delete-person — Delete a person from a business contact, together with that person's notification preferences. (запись · подтверждение + необратимо · все · API: delete_business_contact_person)
• lg contacts extract — Read a business card, letterhead or invoice header (image or PDF) and return the company details on it — legal name, tax number and office, VAT number, e-mail, phone, IBAN (checksum-checked, bank detected), address,… (чтение · — · все · API: extract_business_contact_from_image) [принимает файл: attachment_uuid]
• lg contacts extract-text — Read pasted text (Excel/CSV rows, e-mail signatures, a typed list) and return up to 100 draft records of ONE kind: companies, persons, addresses or bank_accounts. (чтение · — · все · API: extract_business_contacts_from_text)
• lg contacts get — Read one business contact in full (identity, tax data, address, e-mail/phone, bank accounts, platform link) together with its account summary: ledger balance (positive = they owe us), open receivables and open payables. (чтение · — · все · API: get_business_contact)
• lg contacts invite — Invite a business contact to join Logistivo by e-mail. (запись · подтверждение + необратимо · все · API: invite_business_contact)
• lg contacts list — List the company's business contacts (customers, carriers, suppliers, consignees) with optional text search over name, legal name and tax number. (чтение · — · все · API: list_business_contacts)
• lg contacts list-addresses — List the saved addresses of one business contact (label, street address, postal code, country) with address_id, needed by update/delete. (чтение · — · все · API: list_business_contact_addresses)
• lg contacts list-person-notifications — Show which load notifications a contact person receives and on which channel (e-mail, push, SMS), plus the notification types that can be chosen with their allowed channels — use those slugs with… (чтение · — · все · API: list_business_contact_person_notifications)
• lg contacts list-persons — List the people (yetkili kişiler) saved on one business contact: name, e-mail, phone, job title, note, and which load notifications each one receives. (чтение · — · все · API: list_business_contact_persons)
• lg contacts list-routes — Show which countries a business contact that is linked to a carrier on the platform serves: its declared route pairs (from-country → to-country) and the distinct country list. (чтение · — · все · API: list_business_contact_routes)
• lg contacts remove-company-link — Remove the link between a business contact and its company on the Logistivo platform. (запись · подтверждение + необратимо · все · API: unlink_business_contact_company) [ключ manager]
• lg contacts restore — Bring an archived business contact back (cariyi arşivden geri al): it returns to lists and pickers and can be edited again. (запись · подтверждение · все · API: restore_business_contact)
• lg contacts search — Resolve a business contact (customer/partner/recipient) by name, legal name or tax number to its contact_id. (чтение · — · все · API: lookup_business_contact)
• lg contacts set-default-bank-account — Make one of a business contact's bank accounts its DEFAULT account — the one pre-selected when you pay this contact. (запись · подтверждение + необратимо · все · API: set_default_business_contact_bank_account)
• lg contacts set-person-notifications — Turn load notifications on or off for a contact person, per notification type and channel (e-mail, push, SMS). (запись · подтверждение · все · API: set_business_contact_person_notifications)
• lg contacts update — Update fields of an existing business contact. (запись · подтверждение · все · API: update_business_contact)
• lg contacts update-address — Correct one of a business contact's addresses. (запись · подтверждение · все · API: update_business_contact_address)
• lg contacts update-bank-account — Correct one of a business contact's bank accounts: IBAN, account holder, bank name, BIC/SWIFT, currency, label, account type, branch code or account number. (запись · подтверждение + необратимо · все · API: update_business_contact_bank_account)
• lg contacts update-person — Correct a contact person's details. (запись · подтверждение · все · API: update_business_contact_person)
• lg containers calculate — Decode and validate a container number (konteyner numarası) per ISO 6346 — owner code, category, serial, check digit (is it correct, and what it should be) and, when known, the operating line with its public tracking… (чтение · — · все · API: decode_container_number)
• lg conversations add-file — Post a file into an OFFER (demand-bid) chat as this user — e.g. a price sheet or a vehicle photo for the other company. conversation_code comes from list_conversations (rows whose subject is demand_bid). (запись · подтверждение + необратимо · все · API: send_conversation_file) [принимает файл: attachment_uuid]
• lg conversations add-invitation — Invite a person from ANOTHER company into a load chat by e-mail (sohbete dışarıdan davet). (запись · подтверждение + необратимо · все · API: invite_to_conversation)
• lg conversations add-message — Post a message into a load/bid conversation AS THIS USER (not as an assistant). (запись · подтверждение + необратимо · все · API: send_conversation_message)
• lg conversations add-participants — Add people to a load/demand conversation (sohbete kişi ekle) — "Ayşe'yi FKZ8515 sohbetine ekle". (запись · подтверждение · все · API: add_conversation_participants)
• lg conversations create — Open the freight chat with a carrier that bid on one of OUR demands (navlun sohbetini başlat) — bid_code comes from get_demand / the bids of a demand. (запись · подтверждение + необратимо · грузоотправитель · API: start_bid_conversation)
• lg conversations list — List the chat conversations this user is a member of (load chats, bid chats and private carrier channels), newest activity first. (чтение · — · все · API: list_conversations)
• lg conversations list-files — List the files shared in a load/bid chat, newest first: document type, title, file name, who posted it and when. (чтение · — · все · API: list_conversation_files)
• lg conversations list-invitations — Show the e-mail invitations to a load chat that have not been accepted yet: who was invited, by whom and when, and what they will be allowed to see. (чтение · — · все · API: list_conversation_invitations)
• lg conversations list-messages — Read the most recent messages of one conversation — give it a load code (e.g. (чтение · — · все · API: list_conversation_messages)
• lg conversations list-participants — Who is in this conversation — name and company of every participant. (чтение · — · все · API: list_conversation_participants)
• lg conversations mark-read — Mark one conversation as read for this user (clears its unread badge), or with all=true every load, bid and direct-message chat at once. (запись · — · все · API: mark_conversation_read)
• lg conversations remove-message — Delete one of THIS user's own messages from a conversation (message_id from list_conversation_messages with `mine` true). (запись · подтверждение + необратимо · все · API: delete_conversation_message)
• lg conversations remove-participant — Remove someone from a load/bid chat, cancel a pending e-mail invitation to it, or leave it yourself (give your own user_id). (запись · подтверждение + необратимо · все · API: remove_conversation_participant)
• lg conversations update-message — Edit one of THIS user's own messages in a conversation (message_id comes from list_conversation_messages, where `mine` is true). (запись · подтверждение · все · API: update_conversation_message)
• lg countries search — Resolve a country by name (Turkish, English or the local/native name) or ISO 3166-1 alpha-2 code to its country_id, for the sending/receiving country on a load. (чтение · — · все · API: lookup_country)
• lg currencies list — The currencies the platform knows (currency_id, code, name, symbol) with the latest exchange rate against the Turkish lira (buying / selling, rate date). currency_id is what forms such as bank accounts take. (чтение · — · все · API: list_currencies)
• lg custom-reports generate — Custom report counted server-side over ALL records of a dataset: filter, group (dates by month etc.), count/sum/avg/min/max (money per currency) or list rows; format=xlsx|pdf|csv gives a file. (чтение · — · все · API: build_report)
• lg customs-companies list — Customs broker companies this customer can assign when accepting a bid (accept_demand_bid customs_company_id): the Logistivo customs companies you already work with in your chats. (чтение · — · грузоотправитель · API: list_customs_companies)
• lg customs-locations search — Search customs offices / customs locations (gümrük müdürlüğü, gümrük lokasyonu) by name or street — for the exit and destination customs of a load. (чтение · — · все · API: lookup_customs_location)
• lg demand-bid-reports get — Bid report across ALL demands at once, counted server-side: for a customer the bids RECEIVED on its demands, for a carrier the bids it PLACED. (чтение · — · грузоотправитель, перевозчик · API: get_demand_bid_report)
• lg demand-reports get — Demand report (Talep Raporu) with optional filters: status, demanding company, transport mode, pickup / delivery countries, loading-date window. (чтение · — · грузоотправитель, перевозчик · API: get_demand_report)
• lg demand-settings get — This carrier company's demand settings: whether demands opened by forwarder companies reach the company (accept_demands_from_forwarders). (чтение · — · перевозчик · API: get_demand_settings) [ключ manager]
• lg demand-settings update — Change this carrier company's demand settings. accept_demands_from_forwarders=false stops demands opened by forwarder companies from reaching the company (only shippers' demands remain); true lets them in again. (запись · подтверждение · перевозчик · API: update_demand_settings) [ключ manager]
• lg demand-targets search — Resolve a pickup/delivery location for a demand to a target token ("5-" = district/postal area, "10-" = seaport address). (чтение · — · грузоотправитель · API: lookup_demand_target)
• lg demands create — Open a freight demand (talep) so carriers can bid. (запись · подтверждение + необратимо · грузоотправитель · API: create_demand) [принимает файл: attachment_uuids]
• lg demands download — File for ONE demand owned by this company. export_type=details_pdf: the demand's detail sheet (route, dates, cargo, pallets) as PDF. export_type=sales_xlsx: the sales report workbook — demand information, every bid… (чтение · — · грузоотправитель · API: download_demand_export)
• lg demands extract — Read a freight request text (an e-mail body, a note, a voice transcript) and return the demand fields it contains in the demand wizard's shape: transport mode, countries, ports, locations, dates, load type, vehicle… (чтение · — · грузоотправитель · API: extract_demand_from_text)
• lg demands get — Detail of ONE freight demand. (чтение · — · грузоотправитель, перевозчик · API: get_demand)
• lg demands list — List freight demands (talep) this carrier is allowed to bid on, newest first. (чтение · — · перевозчик · API: list_open_demands)
• lg demands list-own — List the freight demands (talep) OWNED by this customer company, newest first, with route, dates, vehicles, status and bid count. (чтение · — · грузоотправитель · API: list_demands)
• lg demands options — Reference lists needed to build a freight demand (talep) with create_demand: vehicle types (id, name, transport mode), payment maturity options (id + days; company_default_maturity_option_id is what the company normally… (чтение · — · грузоотправитель · API: get_demand_form_options)
• lg demands set-status — Close (make passive) one of this company's ACTIVE demands so carriers stop bidding. (запись · подтверждение + необратимо · грузоотправитель · API: close_demand)
• lg demands update — Edit one of this company's ACTIVE demands that has NO bids yet (a demand with bids or a closed one cannot be edited). (запись · подтверждение · грузоотправитель · API: update_demand) [принимает файл: attachment_uuids]
• lg direct-conversations add-message — Send a direct message AS THIS USER (never as an assistant) — either into an existing chat (conversation_code from list_direct_conversations) or to one person (to_user_id from list_direct_message_contacts; their private… (запись · подтверждение + необратимо · все · API: send_direct_message)
• lg direct-conversations create — Start a direct chat. (запись · подтверждение + необратимо · все · API: create_direct_conversation)
• lg direct-conversations download — Produce the whole direct-message or group chat as a PDF (the same file as the panel's export button: participants and every message with date and time) and return a short-lived download link. (чтение · — · все · API: export_direct_conversation_pdf)
• lg direct-conversations list — List this user's direct-message (DM) chats and group chats — person-to-person messaging, separate from load/bid chats (those are list_conversations). (чтение · — · все · API: list_direct_conversations)
• lg direct-conversations list-contacts — List the people this user can direct-message: their own teammates plus people they share a load/bid chat with. (чтение · — · все · API: list_direct_message_contacts)
• lg direct-conversations list-messages — Read the latest messages of one direct-message or group chat (conversation_code from list_direct_conversations), oldest→newest, with who wrote them. `mine: true` marks this user's own messages; only those, and only… (чтение · — · все · API: list_direct_conversation_messages)
• lg direct-conversations mark-read — Mark one direct-message or group chat as read for this user (clears its unread badge). (запись · — · все · API: mark_direct_conversation_read)
• lg direct-conversations remove-message — Delete one of THIS user's own direct messages (message_id from list_direct_conversation_messages, mine and editable true), only within 5 minutes of sending. (запись · подтверждение + необратимо · все · API: delete_direct_message)
• lg direct-conversations update — Rename a GROUP direct chat (private one-to-one chats have no title). (запись · подтверждение · все · API: rename_direct_conversation)
• lg direct-conversations update-message — Edit one of THIS user's own direct messages (message_id from list_direct_conversation_messages, where mine and editable are true). (запись · подтверждение · все · API: update_direct_message)
• lg document-checks run — Cross-check documents the user attached to THIS conversation against each other and report the discrepancies: mismatched party names, quantities, weights, amounts, dates, container or reference numbers between an… (запись · — · все · API: check_document_compliance) [принимает файл: attachment_uuids]
• lg document-types list — List the platform's document types (slug and name) — the values document_type_slug accepts in upload_company_document, add_driver_document and the vehicle document commands. (чтение · — · все · API: list_document_types)
• lg documents download — Get a short-lived (15 minute) download/preview link for one document by its document_id (from list_load_documents or list_company_documents). (чтение · — · все · API: get_document_link)
• lg drive-rest-estimates get — One driver's GPS-ESTIMATED driving/rest status and driving time left under EU 561/2006 / AETR: current activity and since when, driving_left_today_s = the legal driving time left today under the daily, weekly (56 h) AND… (чтение · — · перевозчик · API: get_driver_drive_rest_estimate)
• lg drive-rest-estimates list — Fleet overview of the GPS-ESTIMATED driving/rest status and driving time left (EU 561/2006 / AETR): per driver the current activity, driving_left_today_s = the legal driving time left today under the daily, weekly (56… (чтение · — · перевозчик · API: list_driver_drive_rest_estimates)
• lg driver-accounts get — Answer "how much do we owe this driver / how much does the driver owe us". (чтение · — · грузоотправитель, перевозчик · API: get_driver_account_summary)
• lg driver-accounts list-candidates — Before opening or filling a driver settlement statement: which of ONE driver's receipts and advances can go on it, and why the others cannot. (чтение · — · грузоотправитель, перевозчик · API: list_driver_account_candidates)
• lg driver-advances cancel — Cancel (void) a recorded driver money movement that did not really happen or was entered with the wrong amount. (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: cancel_driver_advance)
• lg driver-advances create — Record a money movement between the company and a driver: an advance handed to the driver, money the driver gave back, a closing payout, or a carry-forward opening balance. (запись · подтверждение · грузоотправитель, перевозчик · API: create_driver_advance) [принимает файл: attachment_uuid]
• lg driver-advances delete — Delete a driver money movement that was entered by mistake (duplicate, wrong driver). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_driver_advance)
• lg driver-advances list — List the money movements between the company and its drivers: cash advances handed out, money paid back by the driver, closing payouts and carry-forward opening balances. (чтение · — · грузоотправитель, перевозчик · API: list_driver_advances)
• lg driver-advances update — Correct the non-money details of a recorded driver money movement: its reference, note, or the load it belongs to. (запись · подтверждение · грузоотправитель, перевозчик · API: update_driver_advance)
• lg driver-availabilities create — Record that a driver is unavailable on some days — "Ali is on leave 14-20 November", "Mehmet rests at home next week", "Kemal is sick from today". (запись · подтверждение · перевозчик · API: create_driver_availability)
• lg driver-availabilities delete — Delete ONE availability period (id from list_driver_availabilities) — the driver counts as available again on those days. (запись · подтверждение + необратимо · перевозчик · API: delete_driver_availability)
• lg driver-availabilities list — List drivers' leave, home-rest, sick and other unavailability periods (newest planning input), optionally for one driver and/or a date window. (чтение · — · перевозчик · API: list_driver_availabilities)
• lg driver-availabilities update — Correct one availability period (id from list_driver_availabilities): kind, dates, Schengen presence or note. (запись · подтверждение · перевозчик · API: update_driver_availability)
• lg driver-expense-settings get — Read this company's driver expense module settings: is the module switched on, which currency receipts and advances are converted into, whether receipts need approval (and above which amount), whether drivers may… (чтение · — · грузоотправитель, перевозчик · API: get_driver_expense_settings)
• lg driver-expense-settings update — Change this company's driver expense module settings — only the fields you pass change. (запись · подтверждение · грузоотправитель, перевозчик · API: update_driver_expense_settings) [ключ manager]
• lg driver-expenses create — File one or MANY expense receipts the user attached to this conversation (fuel, toll, ferry, parking, repair, meal…) into the driver expense ledger as pending expenses of ONE of this company's drivers. (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: process_receipt) [принимает файл: attachment_uuid, attachment_uuids]
• lg driver-expenses declare — Record a driver expense WITHOUT a receipt (fişsiz şoför harcaması) — "Mehmet dün 40 EUR otopark ödedi, fişi yok", "log 120 PLN toll for driver X". (запись · подтверждение · грузоотправитель, перевозчик · API: create_driver_expense)
• lg driver-expenses delete — Delete a driver expense entered by mistake (duplicate receipt, wrong driver, test entry). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_driver_expense)
• lg driver-expenses download — Get the download link of a receipt pack that generate_driver_receipt_pack prepared in the background. (чтение · — · грузоотправитель, перевозчик · API: download_driver_receipt_pack)
• lg driver-expenses generate — Produce ONE PDF that contains the driver receipts of a selection — for a trip, a load, a driver statement or a date window — e.g. to hand to accounting or the customer. (чтение · — · грузоотправитель, перевозчик · API: generate_driver_receipt_pack)
• lg driver-expenses get — Read one driver expense (receipt) by its id: merchant, amount, currency, converted amount, category, payment channel, whether it is charged to the driver, and the approval status. (чтение · — · грузоотправитель, перевозчик · API: get_driver_expense)
• lg driver-expenses list — List driver expense receipts (fuel, toll, ferry, parking, food, repair…) with a converted total. (чтение · — · грузоотправитель, перевозчик · API: list_driver_expenses)
• lg driver-expenses list-loads — For ONE driver: which loads they carried and, per load, how many receipts there are, how many still await approval, how much is reimbursable to the driver, how much is company-billed (fuel card / DKV / UTA — never the… (чтение · — · грузоотправитель, перевозчик · API: list_driver_expense_loads)
• lg driver-expenses list-trips — For ONE driver: which trips (load groups) they drove and, per trip, the number of loads and the driver's OWN receipt figures (count, awaiting approval, reimbursable, company-billed fuel-card / DKV / UTA, still… (чтение · — · грузоотправитель, перевозчик · API: list_driver_expense_trips)
• lg driver-expenses review — Approve or reject ONE driver expense (receipt) from the chat, or send an already-decided one back to pending. status=approved means the company accepts the expense (an approved reimbursable receipt can then be counted… (запись · подтверждение · грузоотправитель, перевозчик · API: review_driver_expense)
• lg driver-expenses set-in-account — Count driver receipts INTO the driver's account (include=true, default) or take them OUT of it (include=false). (запись · подтверждение · грузоотправитель, перевозчик · API: set_driver_expenses_in_account)
• lg driver-expenses update — Correct a recorded driver expense (receipt or no-receipt): amount, currency, date, category, how it was paid, merchant, description or the load it belongs to — "the parking was 45 EUR not 40", "that fuel was paid with… (запись · подтверждение · грузоотправитель, перевозчик · API: update_driver_expense)
• lg driver-expenses update-conversion — Retry the currency conversion of ONE driver receipt whose exchange rate could not be resolved (it then sits outside every total and cannot go into a driver statement). (запись · — · грузоотправитель, перевозчик · API: retry_driver_expense_conversion)
• lg driver-schedules accept — Apply ONE schedule suggestion (suggestion_id from get_driver_schedule): the proposed driver is assigned to the load (or every consignment of the trip — consignments still held by another driver are taken over, and the… (запись · подтверждение · перевозчик · API: apply_driver_schedule_suggestion)
• lg driver-schedules generate — Compute schedule suggestions for a 7-90 day window starting within 30 days: which driver should take each unassigned load, trip and route plan so that nobody runs out of Schengen days, leave is respected and vehicles do… (запись · подтверждение · перевозчик · API: generate_driver_schedule)
• lg driver-schedules get — Read one schedule run (schedule_id from generate_driver_schedule / list_driver_schedules): summary (jobs covered, unassignable jobs and why, vehicle idle days before → after, lowest Schengen margin), the suggestions in… (чтение · — · перевозчик · API: get_driver_schedule)
• lg driver-schedules list — List the company's schedule-suggestion runs, newest first: id (schedule_id), status (queued | running | completed | failed), the planned window, objective and whether the run is out of date (is_stale — planning inputs… (чтение · — · перевозчик · API: list_driver_schedules)
• lg driver-schedules reject — Dismiss ONE open schedule suggestion (suggestion_id from get_driver_schedule) so it is no longer offered; nothing is assigned or changed elsewhere. (запись · — · перевозчик · API: dismiss_driver_schedule_suggestion)
• lg driver-statements cancel — Cancel a statement that should not exist (opened by mistake, duplicated). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: cancel_driver_account)
• lg driver-statements create — Open a NEW draft settlement statement for a driver. (запись · подтверждение · грузоотправитель, перевозчик · API: create_driver_account)
• lg driver-statements download — Give a short-lived download link to the PDF statement of a FINALISED driver settlement statement — the document the driver sees and signs, with every line, the fuel-card block that is outside the driver maths, and the… (чтение · — · грузоотправитель, перевозчик · API: download_driver_account_pdf)
• lg driver-statements finalize — FINALISE a draft settlement statement — it freezes the document, makes it visible to the driver and (for settle_cash) writes the counter-entry into the advance ledger. (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: finalize_driver_account) [ключ manager]
• lg driver-statements get — Read one driver settlement statement in full: its status and revision, the driver, the currency, every total (expenses, advances, repayments, receiptless declarations), the NET balance with the sentence that says which… (чтение · — · грузоотправитель, перевозчик · API: get_driver_account)
• lg driver-statements list — List the driver settlement statements (mutabakat belgesi) of this company: code, which driver, status (draft / finalized / cancelled), currency, the net balance and what it means, how many expense and advance lines it… (чтение · — · грузоотправитель, перевозчик · API: list_driver_accounts)
• lg driver-statements reopen — Reopen a FINALISED statement so it can be corrected (a late receipt arrived, a line was wrong). (запись · подтверждение · грузоотправитель, перевозчик · API: reopen_driver_account) [ключ manager]
• lg driver-statements update — Change the note printed on a DRAFT driver settlement statement (e.g. "September trips, fuel excluded"). (запись · подтверждение · грузоотправитель, перевозчик · API: update_driver_account)
• lg driver-statements update-lines — Attach receipts/advances to a DRAFT statement, or detach ones that should not be on it. (запись · подтверждение · грузоотправитель, перевозчик · API: update_driver_account_lines)
• lg driver-statuses list — Fleet command centre — every driver's live operational status in one list: last position and its AGE, signal health (streaming / delayed / stale / no_signal / permission_denied / app_missing), duty (on_trip / assigned /… (чтение · — · грузоотправитель, перевозчик · API: list_fleet_driver_statuses)
• lg drivers add-document — Record a driver paper — visa, passport, residence permit, driving licence, SRC certificate, psychotechnic certificate, travel health insurance — for ONE of this carrier's drivers, so its expiry is tracked. (запись · подтверждение · перевозчик · API: add_driver_document) [принимает файл: attachment_uuid]
• lg drivers archive — Archive (deactivate) a driver: their account is disabled, open mobile sessions are revoked and the login link stops working. (запись · подтверждение + необратимо · перевозчик · API: archive_driver)
• lg drivers calculate — Check whether ONE driver can take a job: Schengen 90/180 days left at the end of the trip (expected and worst case, counting the drive back out and the driver's later planned work), leave / home-rest / sick periods,… (чтение · — · перевозчик · API: check_driver_for_trip)
• lg drivers create — Create a new driver account for this carrier company. (запись · подтверждение · перевозчик · API: create_driver)
• lg drivers delete-document — Remove a driver paper from the driver's file. (запись · подтверждение + необратимо · перевозчик · API: delete_driver_document)
• lg drivers get — Full detail of ONE driver of this carrier: identity, archive state, mobile app state, last GPS position, assigned load codes, ALL driver documents (passport, visa, licence, SRC… with expiry and days_to_expiry) and the… (чтение · — · перевозчик · API: get_driver)
• lg drivers list — List this carrier company's drivers with their status, current country, expiring/expired document counts, assigned load codes and vehicle plates. (чтение · — · перевозчик · API: list_drivers)
• lg drivers list-candidates — Rank the company's drivers for a job — which drivers are available and can do it (Schengen days at trip end incl. the drive back, leave/home-rest, other jobs, estimated driving/rest readiness, distance to the start)… (чтение · — · перевозчик · API: list_trip_driver_candidates)
• lg drivers list-documents — List ONE driver's documents (passport, visa, residence permit, licence, SRC, ADR, health insurance…) with document number, issuing country, valid_until, days_to_expiry, is_expired and AI extraction status. (чтение · — · перевозчик · API: list_driver_documents)
• lg drivers list-locations — A driver's GPS trail — the raw position pings from the driver app in a time window, oldest to newest, with the first and last timestamps and the point count. (чтение · — · перевозчик · API: list_driver_locations)
• lg drivers login-link — Produce the driver's 48-hour mobile app login link (sensitive credential). (запись · подтверждение · перевозчик · API: get_driver_login_link)
• lg drivers request-location — Ask a driver's phone for a fresh position ("where is Ahmet right now — ping him"). (запись · — · перевозчик · API: request_driver_location)
• lg drivers search — Resolve one of this company's drivers by name to its driver_id. (чтение · — · перевозчик · API: lookup_driver)
• lg drivers update — Correct a driver's first/last name. (запись · подтверждение · перевозчик · API: update_driver)
• lg drivers update-document — Correct a driver paper already on file — most often its expiry date (valid_until) after a renewal, but also the document number, the issuing country, the type or the note. (запись · подтверждение · перевозчик · API: update_driver_document)
• lg drivers update-login-link — Generate a NEW 48-hour mobile login link for a driver and kill the old one (lost phone, expired or leaked link). (запись · подтверждение + необратимо · перевозчик · API: refresh_driver_login_link)
• lg equipment-damages create — Open a damage record on one of the company's own vehicles or trailers (dorse hasar kaydı aç) — "33ABC12 dorsesinin sol arka kapısında ezik var", "record a scratch on the rear bumper of the truck". (запись · подтверждение · все · API: create_equipment_damage)
• lg equipment-damages delete — Delete a damage record that was opened by mistake (a duplicate, the wrong vehicle). (запись · подтверждение + необратимо · все · API: delete_equipment_damage)
• lg equipment-damages generate — Produce the equipment damage ledger as an Excel file (the same file as the panel's export button) and return a short-lived download link — e.g. "give me this year's open trailer damages as Excel". (чтение · — · все · API: export_equipment_damages)
• lg equipment-damages list — List the equipment/trailer damages recorded for this company: which vehicle, where on it (area and angle), damage type and severity, whether it is still open or repaired, the estimated and actual repair cost, who is… (чтение · — · все · API: list_equipment_damages)
• lg equipment-damages update — Update an existing damage record: mark it repaired (with repair date, cost and note), dismissed or disputed, change severity/type/area/description, set the estimated cost, or set/clear the responsible driver. (запись · подтверждение · все · API: update_equipment_damage)
• lg equipment-inspection-links create — Create a one-time link so a driver or agent who is NOT on the platform (port agent, another company's driver) can upload the hand-over photos of one of the company's trailers/vehicles from a phone, without an account. (запись · подтверждение · все · API: create_equipment_inspection_link)
• lg equipment-inspections create — Record an equipment hand-over inspection of one of the company's own trailers or vehicles on behalf of a driver or the office — "record the pickup inspection of trailer 34ABC12 with these 4 photos, driver Ali".… (запись · подтверждение · все · API: create_equipment_inspection) [принимает файл: photos[].attachment_uuid]
• lg equipment-inspections delete — Delete an equipment inspection that was recorded by mistake (wrong vehicle, duplicate), together with its photos. (запись · подтверждение + необратимо · все · API: delete_equipment_inspection)
• lg equipment-inspections get — Full detail of ONE equipment hand-over inspection: vehicle, event (pickup / dropoff / interim), who did it and where and when, the AI analysis status with its overall condition and summary, the damages that inspection… (чтение · — · все · API: get_equipment_inspection)
• lg equipment-inspections list — List the equipment hand-over inspections (teslim-tesellüm controls) of this company: which vehicle, the event type (hand-over, take-over, interim), when and where it happened, who performed it (driver or office user, or… (чтение · — · все · API: list_equipment_inspections)
• lg equipment-inspections run — Run the AI damage analysis again on the photos of one equipment inspection (for example after the analysis failed, or photos were added later). (запись · подтверждение · все · API: reanalyze_equipment_inspection)
• lg equipment-settings get — Read the company's equipment inspection settings: whether the module is on, at which hand-overs an inspection is required (pickup / dropoff), whether photos are required, the minimum photo count, which angles are… (чтение · — · все · API: get_equipment_settings)
• lg equipment-settings update — Change the company's equipment inspection settings — e.g. "turn on equipment inspection and require at least 4 photos with front, rear, left and right at pickup". (запись · подтверждение · все · API: update_equipment_settings) [ключ manager]
• lg equipment-timelines get — Who has one trailer/vehicle right now (custody: in custody of a driver since the last pickup, or released at the last dropoff), the inspections it went through (newest first) and its OPEN damages — in one read. (чтение · — · все · API: get_equipment_timeline)
• lg export-documents add-item — Append a line item to an export document. (запись · — · все · API: add_export_document_item)
• lg export-documents create — Create a new export document draft. (запись · — · все · API: create_export_document_draft)
• lg export-documents create-set — Create SEVERAL export document drafts (a set, e.g. commercial invoice + packing list) from ONE source in one go: the source is read once by AI and every chosen document is filled from it. (запись · — · все · API: create_export_document_set) [принимает файл: attachment_uuid]
• lg export-documents delete — Delete one export document of this company (draft or generated). (запись · подтверждение + необратимо · все · API: delete_export_document)
• lg export-documents duplicate — Copy an existing export document into a NEW draft of the same type (same parties, items and terms; no document number, not generated). (запись · — · все · API: duplicate_export_document)
• lg export-documents extract — Read a pasted order e-mail, offer or confirmation — or an Excel/CSV/TXT item list given as attachment_uuid — and fill an export document from it. (запись · — · все · API: extract_export_document_from_text) [принимает файл: attachment_uuid]
• lg export-documents generate — Produce the final PDF of an export document AND return a short-lived signed download link for it, so the user gets the file straight from the chat. (запись · подтверждение + необратимо · все · API: generate_export_document)
• lg export-documents generate-set — Generate several export documents as PDFs in one go and return a short-lived download link for each generated one. (запись · подтверждение + необратимо · все · API: generate_export_document_set)
• lg export-documents get — Read one export document in full: every filled field as dot-paths, the line items with their 1-based positions, the server-computed totals and which required fields are still empty. (чтение · — · все · API: get_export_document)
• lg export-documents list — List the export documents of the current company (proforma invoice, commercial invoice, packing list, shipping instruction, delivery note, certificate/movement applications, exporter declaration, insurance request). (чтение · — · все · API: list_export_documents)
• lg export-documents options — List the export document types and the ready-made document sets with their credit cost. (чтение · — · все · API: get_export_document_options)
• lg export-documents preview — Before generating several export documents as PDFs, show what it would cost: which documents would spend a credit, which are free (already generated), the total, the remaining balance and the required fields still empty… (чтение · — · все · API: plan_export_document_generation)
• lg export-documents remove-item — Delete one line item by its 1-based position. (запись · — · все · API: remove_export_document_item)
• lg export-documents set — Set one or more fields on an export document draft. (запись · — · все · API: set_export_document_fields)
• lg export-documents update-item — Change columns of one existing line item, addressed by its 1-based position from get_export_document. (запись · — · все · API: update_export_document_item)
• lg finance calculate — Build a budget / financial forecast (bütçe tahmini, gelecek yıl bütçesi, nakit/ciro projeksiyonu) from the company's MEASURED history, month by month. (чтение · — · все · API: generate_budget_forecast)
• lg finance get — One call that returns the measured financial BASE for a period — the numbers a budget, a forecast, a business plan, a cash-flow projection or a board summary is built on, instead of chaining six separate reads. (чтение · — · все · API: get_financial_snapshot)
• lg fleet-documents list — List fleet documents that expire soon (or already expired): vehicle papers (insurance, inspection, permits) and — for carriers — driver papers (passport, visa, licence, SRC). (чтение · — · грузоотправитель, перевозчик · API: list_expiring_documents)
• lg freight-invoices archive — Archive (remove from the active list) a freight invoice YOUR company uploaded — e.g. a duplicate or the wrong file. (запись · подтверждение + необратимо · все · API: archive_freight_invoice)
• lg freight-invoices create — Attach 1-20 freight invoices (navlun faturası) to a load. (запись · подтверждение · все · API: upload_freight_invoices) [принимает файл: attachment_uuids]
• lg freight-invoices list — List the freight invoices (navlun faturaları) of a load that your company is a party to: who uploaded it, amount and currency, invoice date, the AI reading status, and which load parties it is shared with. (чтение · — · все · API: list_freight_invoices)
• lg freight-invoices set-visibility — Choose which load parties can see a freight invoice YOUR company uploaded — e.g. "share the invoice with the receiver too", "only we should see it". (запись · подтверждение · все · API: set_freight_invoice_visibility)
• lg freight-reports get — Freight (navlun) cost report over the loads this company can see: agreed freight totals per currency plus the EUR equivalent, freight-invoice totals, how many loads have NO freight recorded (listed by code), a breakdown… (чтение · — · грузоотправитель, перевозчик · API: get_freight_cost_report)
• lg fuel-cards create — Register a fuel card (DKV, UTA and the like) in the fleet card book, optionally tied to a driver or a vehicle. (запись · подтверждение · грузоотправитель, перевозчик · API: create_fuel_card)
• lg fuel-cards delete — Delete a fuel / toll card (DKV, UTA, Shell…) that was entered BY MISTAKE. (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_fuel_card)
• lg fuel-cards list — List the company's fuel and toll cards (DKV, UTA, Eurowag, E100, Shell, OMV, Aral, Petrol Ofisi, Opet…) with the last four digits, the driver or vehicle they are tied to, and whether they are active. (чтение · — · грузоотправитель, перевозчик · API: list_fuel_cards)
• lg fuel-cards update — Update a fuel card: move it to another driver or vehicle, change its label or note, or DEACTIVATE it (is_active false) when the card is cancelled. (запись · подтверждение · грузоотправитель, перевозчик · API: update_fuel_card)
• lg handoff-links generate — Get the logistivo.com link for work that deliberately stays in the browser: package_purchase (buy or upgrade a package; optional package_slug from list_packages and billing_period monthly|yearly pre-select it — the… (чтение · — · все · API: get_browser_handoff_link)
• lg import-duties get — Read the Turkish import duty table for one GTİP code: customs duty (İthalat Rejimi Kararı) and additional customs duty / İGV, with every country-group column, plus the statutory duty from the nomenclature. (чтение · — · все · API: get_import_duty_rates)
• lg integration-keys list — List the company's integration (API) keys: name, uuid, which teammate it acts as, scope (read/write) and allowed domains, access level (manager/employee), environment (live/sandbox), status (active/revoked/expired),… (чтение · — · все · API: list_integration_keys) [ключ manager]
• lg integration-keys revoke — Revoke one of the company's integration (API) keys by its uuid from list_integration_keys: the key stops working immediately and cannot be re-enabled (issue a new key instead). (запись · подтверждение + необратимо · все · API: revoke_integration_key) [ключ manager]
• lg invitations create — Invite colleagues to this company by e-mail — one address in email, or up to 20 at once in emails (all-or-nothing: the seat limit and every address's domain are checked before anything is sent). (запись · подтверждение + необратимо · все · API: invite_teammate) [ключ manager]
• lg invitations list — List teammate invitations of this company that are not completed yet (pending / e-mail verified / account created), with invitation_code, e-mail, role and expiry. (чтение · — · все · API: list_pending_invitations)
• lg invitations resend — Re-send a pending teammate invitation e-mail and extend its expiry by 14 days. (запись · подтверждение + необратимо · все · API: resend_invitation) [ключ manager]
• lg invitations revoke — Cancel a pending teammate invitation so its link stops working (it can later be re-sent). (запись · подтверждение · все · API: revoke_invitation) [ключ manager]
• lg invoice-settings get — Read the invoice document settings (fatura ayarları, fatura şablonu ayarları): which invoice templates exist, which template configuration is the company default, which fields of it are filled (logo, seller address,… (чтение · — · все · API: get_invoice_settings)
• lg invoice-templates create — Create a new invoice template configuration for your company: a base template plus field values (colours, font, header / footer text, IBANs shown, QR code, language; logo and signature from uploaded images). (запись · подтверждение + необратимо · все · API: create_invoice_template) [ключ manager] [принимает файл: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoice-templates delete — Delete one of your invoice template configurations. (запись · подтверждение + необратимо · все · API: delete_invoice_template) [ключ manager]
• lg invoice-templates get — Show the fillable fields of an invoice template (logo, colours, font, header / footer text, IBANs shown, QR code, signature, language) with their types, options and defaults — and, for one of your configurations, its… (чтение · — · все · API: get_invoice_template)
• lg invoice-templates set-default — Make one of your invoice template configurations the company default; the previous default stops being default. (запись · подтверждение · все · API: set_default_invoice_template) [ключ manager]
• lg invoice-templates update — Edit one of your invoice template configurations: switch its base template, rename it, change field values (merged over the stored ones — only the keys you pass change), replace the logo / signature image, or make it… (запись · подтверждение + необратимо · все · API: update_invoice_template) [ключ manager] [принимает файл: logo_attachment_uuid, signature_image_attachment_uuid]
• lg invoices add-line — Add a line item to a DRAFT invoice and recompute totals (tax auto-resolved if tax_rate_id omitted). (запись · — · все · API: add_invoice_line)
• lg invoices add-payment — Record money received (sales invoice) or paid (purchase invoice) against ONE issued invoice: writes the payment, posts the balanced journal entry and reduces the remaining balance. (запись · подтверждение + необратимо · все · API: record_invoice_payment)
• lg invoices cancel — Cancel an ISSUED invoice this company issued: posts the reversing journal entry and marks the invoice cancelled. (запись · подтверждение + необратимо · все · API: cancel_invoice)
• lg invoices create — Create a DRAFT invoice (reversible) issued by the current company to a recipient business contact. (запись · — · все · API: create_invoice_draft)
• lg invoices delete-draft — Delete a DRAFT invoice of this company together with its lines and taxes. (запись · подтверждение + необратимо · все · API: delete_invoice_draft)
• lg invoices download — Get a short-lived download link for the PDF of an invoice visible to this company (and the e-invoice XML when one exists). (чтение · — · все · API: download_invoice_pdf)
• lg invoices get — Read one invoice in full: parties, load link, dates, every line with tax, tax breakdown, totals, remaining balance and the payments recorded against it. (чтение · — · все · API: get_invoice)
• lg invoices issue — Issue (finalize) a DRAFT invoice: assigns a number and posts accounting entries. (запись · подтверждение + необратимо · все · API: issue_invoice)
• lg invoices list — List invoices visible to this company — the ones it issued and the ones issued to it (as a linked party). (чтение · — · все · API: list_invoices)
• lg invoices preview — Show the user a full preview of a DRAFT invoice (recipient, line items, tax breakdown, totals) WITHOUT issuing it. (чтение · — · все · API: preview_invoice · устарела: 2026-09-03 · используйте get_invoice)
• lg invoices remove-line — Remove one line from a DRAFT invoice your company issued; the totals are recalculated. (запись · подтверждение · все · API: remove_invoice_line)
• lg invoices reverse-payment — Undo ONE payment/collection recorded on an invoice: posts the reversing journal entry, gives the amount back to the invoice's remaining balance and removes the payment row. (запись · подтверждение + необратимо · все · API: reverse_invoice_payment)
• lg invoices update — Edit the header of a DRAFT invoice your company issued: recipient contact, currency, issue / due date, the printed note and the invoice template. (запись · — · все · API: update_invoice_draft)
• lg invoices update-line — Edit one line of a DRAFT invoice your company issued (text, quantity, unit, net unit price, discount, tax rate, order). (запись · — · все · API: update_invoice_line)
• lg join-requests approve — Approve a pending join request: the applicant becomes a user of our company with the EMPLOYEE role, takes one team seat and is e-mailed the decision. (запись · подтверждение + необратимо · все · API: approve_join_request) [ключ manager]
• lg join-requests list — List PENDING requests from people asking to join our company (they signed up with an e-mail on one of our verified domains and picked our company). (чтение · — · все · API: list_join_requests) [ключ manager]
• lg join-requests reject — Reject a pending join request: the applicant does not join our company and is e-mailed the decision. (запись · подтверждение + необратимо · все · API: reject_join_request) [ключ manager]
• lg journal-entries create — Post a manual double-entry journal entry (yevmiye fişi). (запись · подтверждение + необратимо · все · API: create_journal_entry)
• lg journal-entries get — Read one journal entry with its lines (account code/name, debit, credit, counterparty) and totals. (чтение · — · все · API: get_journal_entry)
• lg journal-entries list — List journal entries (yevmiye fişleri) of the company, newest first, with optional date window. (чтение · — · все · API: list_journal_entries)
• lg language-settings get — Read the signed-in user's own language settings (dil ayarları). (чтение · — · все · API: get_language_settings)
• lg language-settings update — Change the signed-in user's OWN language settings — "dilimi İngilizce yap", "e-postalarım Türkçe gelsin", "sohbet mesajlarını Almancaya çevir". (запись · — · все · API: set_language)
• lg load-ai-settings get — Read our company's load AI reminder setting (Settings → Loads): whether the assistant posts reminders into load chats about loads whose status was not updated (ai_warning_enabled) and on which days (warning_frequency:… (чтение · — · все · API: get_load_ai_settings)
• lg load-ai-settings update — Change our company's load AI reminders (Settings → Loads): ai_warning_enabled turns the reminders the assistant posts into load chats on or off; warning_frequency picks the days (daily, mon_wed_fri, weekly_wed,… (запись · подтверждение · все · API: update_load_ai_settings) [ключ manager]
• lg load-containers create — Add a sea container number to a load (yüke konteyner ekle) — "add MSC container MSCU1234565 to FKZ8515". (запись · подтверждение · грузоотправитель, перевозчик · API: add_load_container)
• lg load-containers delete — Delete a container record from a load (konteyneri sil) — only while its vessel tracking has NOT started (otherwise refused with INVALID_STATUS). (запись · подтверждение + необратимо · все · API: delete_load_container)
• lg load-containers get — Show one container of a load and the last known position of the ship carrying it (konteyner konumu): ship name/IMO, latitude/longitude, speed, course, destination, ETA and the position time. (чтение · — · все · API: get_load_container)
• lg load-containers list — List the sea containers recorded on a load (konteynerler) with their shipping line, whether vessel tracking has started and which ship carries them. (чтение · — · все · API: list_load_containers)
• lg load-containers set-tracking — Start vessel tracking for a load from its containers (konteyner takibini başlat): the shipping line is queried for each container until the vessel carrying it is found; that ship is then tracked on the load's map and… (запись · подтверждение · все · API: start_load_container_tracking)
• lg load-documents create — File one or MANY documents the user attached to this conversation onto a load: each file is stored as a company document and posted into the load's chat, where every participant (customer, carrier, customs broker) sees… (запись · подтверждение + необратимо · все · API: attach_chat_file_to_load) [принимает файл: attachment_uuid, attachment_uuids]
• lg load-documents list — List the documents (CMR, invoice, packing list, customs papers, photos…) filed on a load — i.e. the files shared in that load's chat. (чтение · — · все · API: list_load_documents)
• lg load-groups add-loads — Merge EXISTING loads into a groupage trip you own as consignments (they keep their own code, chat, documents and participants; only the trip membership changes — nothing is duplicated and NO credit is used). (запись · подтверждение · грузоотправитель, перевозчик · API: add_loads_to_group)
• lg load-groups create — Create a groupage trip (parsiyel/sefer): ONE truck carrying several ISOLATED consignments; each consignment is its own load with its own chat/documents/status and receivers never see each other. (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: create_load_group)
• lg load-groups download — Download the route report of a groupage trip (sefer / parsiyel, code like LGV00253): route_pdf = detailed route report with map and itinerary, route_xlsx = the same as Excel, driver_sheet_pdf = the simplified driver… (запись · — · грузоотправитель, перевозчик · API: download_load_group_report)
• lg load-groups get — Detail of one groupage trip: consignments visible to you (load code, status, receiver, route, driver), planned date, optimised master route summary and stop count. (чтение · — · грузоотправитель, перевозчик · API: get_load_group)
• lg load-groups list — List groupage trips (parsiyel / sefer: one truck, several isolated consignment loads) this company owns or — for carriers — carries, newest first, with visible consignment count and route optimisation state. (чтение · — · грузоотправитель, перевозчик · API: list_load_groups)
• lg load-groups optimize — Re-optimise the master route of a groupage trip you own and RETURN the new itinerary: the ordered stops (pickup → export customs → import customs → dropoff), each stop's address and consignment codes, the total distance… (запись · — · грузоотправитель, перевозчик · API: optimize_trip_route)
• lg load-groups remove-load — Take one consignment out of a groupage trip you own. (запись · подтверждение · грузоотправитель, перевозчик · API: remove_load_from_group)
• lg load-heatmaps generate — Produce the load heatmap report (PDF, with QR code and the list of your active loads: code, departure, arrival, date, weight), save it to the company's reports and return a download link. (запись · подтверждение + необратимо · все · API: generate_load_heatmap_report)
• lg load-heatmaps get — Load heatmap data in words: the densest departure and arrival areas of your active loads, ranked by number of loads and by total kilograms. (чтение · — · все · API: get_load_heatmap)
• lg load-locations create — Report a position for a load on behalf of the carrier (konum bildir) — "FKZ8515 is at Kapıkule now", "the truck is at 41.0, 28.9". (запись · подтверждение + необратимо · перевозчик · API: report_load_location)
• lg load-locations list — Show a load's position history (konum geçmişi) and its last known position — "where is FKZ8515 now", "where was it yesterday", "show the truck's track". (чтение · — · все · API: list_load_locations)
• lg load-locations list-routes — Show the road route segments drawn on a load's tracking map (rota parçaları), each with distance (metres) and duration (seconds): from the pickup address to the first reported position, between reported positions, and… (чтение · — · все · API: list_load_route_segments)
• lg load-notifications list-recipients — Show which load parties can receive a load notification (departure, arrival, daily location) and how many of their people are subscribed per channel (e-mail, push, SMS). (чтение · — · все · API: list_load_notification_recipients)
• lg load-notifications send — Send a departure / arrival / daily-location notification about a load to chosen load parties — e.g. "notify the receiver that FRT6470 arrived". (запись · подтверждение + необратимо · все · API: send_load_notification)
• lg load-notifications send-email — E-mail a departure / arrival / location update about a load to people you choose from YOUR OWN company directory (business contact persons) — e.g. "e-mail Mehmet at Arkas the location of FKZ8515". (запись · подтверждение + необратимо · все · API: send_load_email_notification)
• lg load-participants create — Add a party to a load (yüke taraf ekle) — "FKZ8515'e Arkas'ı alıcı olarak ekle" — or assign a sub-carrier. business_contact_id comes from lookup_business_contact (your own directory). (запись · подтверждение · все · API: add_load_participant)
• lg load-participants delete — Remove a party or a sub-carrier from a load (yükten taraf çıkar) — "FKZ8515'ten alt taşıyıcı Yılmaz Nakliyat'ı kaldır". participant_id comes from list_load_participants. (запись · подтверждение · все · API: remove_load_participant)
• lg load-participants list — List a load's parties (yük tarafları): sender, receiver, carrier and sub-carriers, organizer, sender/receiver customs brokers — with participant_id (needed by every other load-participant command), position (0 = primary… (чтение · — · все · API: list_load_participants)
• lg load-participants set-order — Put the parties of one role in a new order (load owner only); the first id becomes the primary. participant_ids must list ALL current rows of that role (from list_load_participants). (запись · подтверждение · все · API: reorder_load_participants)
• lg load-participants set-primary — Make a party the primary one in its role (load owner only) — e.g. the main receiver or main customs broker. participant_id from list_load_participants. (запись · подтверждение · все · API: set_primary_load_participant)
• lg load-participants update — Change one load party's settings (load owner only) — "Arkas FKZ8515'i görmesin": share_with_assigned_company (can the linked company see the load; cannot be turned off for a sub-carrier), conversation_user_ids (only… (запись · подтверждение · все · API: update_load_participant)
• lg load-party-suggestions approve — Accept a party suggestion: link the suggested business contact to your OWN load as sender or receiver (business_contact_id and party_role from list_load_party_suggestions). (запись · подтверждение · все · API: confirm_load_party_suggestion)
• lg load-party-suggestions list — Show sender/receiver suggestions for one of your OWN loads: parties named in the load's documents that match a contact in your directory but are not linked to the load yet. (чтение · — · все · API: list_load_party_suggestions)
• lg load-party-suggestions reject — Close wrong party suggestions on your OWN load so they are not suggested again — "bu önerileri bir daha gösterme". (запись · — · все · API: dismiss_load_party_suggestions)
• lg load-reports get — Build a report of your ACTIVE loads, optionally filtered by sender, receiver, transport mode, departure country or arrival country. format=summary (default) answers in chat: the number of loads and how many are in each… (чтение · — · все · API: get_load_report)
• lg load-reports options — List the companies you can filter the load report by — the senders, receivers, carriers and other parties that appear on your active loads — with their company id and role. (чтение · — · все · API: get_load_report_options)
• lg load-types search — Resolve a load/transport type (e.g. (чтение · — · все · API: lookup_load_type)
• lg load-vehicles delete — Detach the fleet equipment from a load: both slots by default, or only the tractor unit / only the trailer. (запись · подтверждение · все · API: clear_load_equipment)
• lg load-vehicles get — Show which tractor unit (or truck/van) and which trailer are attached to a load, whether they belong to your own fleet, and whether the load can still be changed. (чтение · — · все · API: get_load_equipment)
• lg load-vehicles set — Attach one of your own fleet vehicles to a load: the tractor unit / truck slot (plate) and/or the trailer slot (trailer_plate). (запись · подтверждение · все · API: assign_vehicle_to_load)
• lg loads add-order-reference — Attach an order reference to a load (sipariş referansı ekle) — "FKZ8515'e satın alma siparişi PO-4471 ekle". order_type is the kind of order (e.g. purchase, sales), order_no the number. (запись · подтверждение + необратимо · все · API: add_load_order_reference)
• lg loads analyze-documents — Re-run the background AI consistency analysis of a load's documents (does the invoice contradict the CMR, the packing list, the declared weight…) and refresh the load's problem flag with the outcome. (запись · — · все · API: reanalyze_load_documents)
• lg loads archive — Archive one of the company's OWN loads (yükü arşivle) — "FKZ8515'i arşive al". (запись · подтверждение + необратимо · все · API: archive_load)
• lg loads assign-driver — Assign one of this company's drivers to a load so the driver sees it in the mobile app and starts reporting position. (запись · подтверждение · перевозчик · API: assign_driver_to_load)
• lg loads audit-documents — Cross-check the documents already attached to loads and report, PER LOAD, whether their package counts and gross weights agree. (чтение · — · все · API: audit_load_documents)
• lg loads close-problem — Close the open document-consistency flag of ONE load, from the chat. action=resolved means the contradiction was actually fixed (a corrected document was uploaded); action=dismissed means it was a false alarm and should… (запись · подтверждение · все · API: resolve_load_problem_flag)
• lg loads create — Open a freight load (yük). (запись · подтверждение + необратимо · все · API: create_load)
• lg loads download — Generate a load's CMR consignment note as a PDF and return a short-lived download link — "FKZ8515'in CMR'ını ver". (чтение · — · все · API: download_load_cmr)
• lg loads extract — Read a booking/order text (an e-mail body, a note, an ERP export line) and return the load fields it contains, in the quick-load form's shape: transport mode, countries, dates, load type, vehicle type, weight, goods… (чтение · — · грузоотправитель · API: extract_load_from_text)
• lg loads get — Read one load in full by its code: route, dates, weight, current status, parties (sender/receiver/carrier), agreed freight (freight_amount + freight_currency) with its freight invoices (number, date, total), latest… (чтение · — · все · API: get_load)
• lg loads list — List the freight loads (yük) this company can see, newest first. (чтение · — · все · API: list_loads)
• lg loads list-associated — List the loads of the same multi-vehicle order as a given load (aynı siparişin diğer araçları) — every active load that shares its vehicle group code (LG…) and that your company can see, with status, date and carrier. (чтение · — · все · API: list_associated_loads)
• lg loads list-billing-targets — Show who you can invoice for a load: its commercial parties (sender, receiver, carrier) you are allowed to bill, each with recipient_contact_id to pass to create_invoice_draft and in_my_directory (true = already in your… (чтение · — · все · API: list_load_billing_targets)
• lg loads list-problems — List loads whose uploaded documents the AI consistency check found to CONTRADICT each other (e.g. invoice weight vs CMR weight). (чтение · — · все · API: list_load_problem_flags)
• lg loads list-status-history — Show a load's status history (durum geçmişi) in order — when it went pending, in transport, transit, delivered (done). (чтение · — · все · API: list_load_status_history)
• lg loads list-stops — List the stops of a multi-stop load (çok duraklı yük — several pickups/drop-offs on one load) in route order, with type (pickup, dropoff, customs_exit, customs_entry), company, address, leg distance/duration and whether… (чтение · — · все · API: list_load_stops)
• lg loads optimize — Re-order the stops of a multi-stop load for the shortest driving route (pickups first, then drop-offs) and store the new order with leg distances — "optimise FKZ8515's stops". (запись · — · все · API: optimize_load_stops)
• lg loads options — Read a load's editable fields, their current values and the allowed options (load types, vehicle types, goods classes, stackability, incoterms, movement types) — "FKZ8515'te neyi değiştirebilirim?". (чтение · — · все · API: get_load_edit_form)
• lg loads preview-copy — Prepare a copy draft of one of your company's OWN loads (yükü kopyala) — "FKZ8515'in aynısından bir tane daha açalım": transport mode, countries, addresses, load type, vehicle type, weight, goods class, incoterms, ports… (чтение · — · все · API: get_load_copy_template)
• lg loads remove-driver — Remove the driver from a load (the opposite of assign_driver_to_load): the load disappears from the driver's app and GPS tracking of the load stops. (запись · подтверждение · перевозчик · API: unassign_driver_from_load)
• lg loads search — Full-text search across your loads (yük ara) — company names, pickup/delivery address, order references, load code, text written in the load chat and text read from documents shared in the chat: "içinde PO-4471 geçen… (чтение · — · все · API: search_loads)
• lg loads set-status — Move a load to a new transport status and append it to the load's status history (this is what the customer sees on the tracking screen). (запись · подтверждение + необратимо · перевозчик · API: update_load_status)
• lg loads set-stop-status — Mark one stop of a multi-stop load as completed, or undo it (completed=false) — "FKZ8515's second drop-off is done". (запись · подтверждение · перевозчик · API: mark_load_stop_completed)
• lg loads set-tracking — Turn a load's GPS location tracking on or off (konum takibi) — "stop location tracking for FKZ8515", "resume tracking". (запись · подтверждение · перевозчик · API: set_load_location_tracking)
• lg loads update — Edit an existing load (yükü düzenle): loading date, weight, load type, vehicle types, goods class, stackability, pickup/delivery address, incoterms, movement type, loading/destination port. (запись · подтверждение + необратимо · все · API: update_load)
• lg maturity-options list — The selectable payment terms (vade): maturity_option_id and the number of days (0 = cash / peşin). maturity_option_id is what update_company_profile takes. (чтение · — · все · API: list_maturity_options)
• lg notification-settings get — Read our company's notification switches (Settings → Notifications): which e-mail notifications (type "notification") and push notifications (type "web-push") are on for the whole company — e.g. message, load, demand… (чтение · — · грузоотправитель · API: get_notification_settings) [ключ manager]
• lg notification-settings update — Turn our company's notification switches on or off (Settings → Notifications) — e.g. stop load chat push notifications or message e-mails for the whole company. settings is a list of {slug, enabled}; slugs come from… (запись · подтверждение · грузоотправитель · API: update_notification_settings) [ключ manager]
• lg notifications list — Read the signed-in user's own notification inbox (the bell icon): what happened, which kind of event it was, when, whether it is still unread, and the panel address the notification points at. (чтение · — · все · API: list_notifications)
• lg notifications mark-read — Mark ALL of the signed-in user's unread notifications as read (empty the bell). (запись · — · все · API: mark_notifications_read)
• lg packages get — Read this company's package and CREDIT balance: how many credits are left, how many the package grants per year, how many were used, the renewal date, and the assistant token usage of the current period (1,000,000… (чтение · — · все · API: get_credit_balance)
• lg packages list — List the Logistivo packages this company can buy: slug, name, monthly price and yearly upfront total in the company's BILLING currency (TRY for Türkiye-billed companies, EUR otherwise — never converted with an exchange… (чтение · — · все · API: list_packages)
• lg pallets add-measurement — Record a NEW measurement for an existing pallet (dimensions in centimetres and/or gross weight in kilograms). (запись · подтверждение · все · API: add_pallet_measurement)
• lg pallets add-proof — Attach a proof photo to one of this company's pallets (e.g. the wrapped pallet, its label, damage on arrival). (запись · — · все · API: add_pallet_proof) [принимает файл: attachment_uuid]
• lg pallets calculate — Suggest the missing base side of a pallet from a standard footprint (EUR 120×80, industrial 120×100, half 80×60; ±5 cm) when only one base side is known, and compute the volume when length, width and height are all… (чтение · — · все · API: complete_pallet_dimensions)
• lg pallets create — Register a NEW pallet in a warehouse, optionally with its first measurement. warehouse_id is required — resolve the warehouse name with lookup_warehouse first. (запись · подтверждение · все · API: create_pallet)
• lg pallets delete — Delete one of this company's pallet records. (запись · подтверждение + необратимо · все · API: delete_pallet)
• lg pallets delete-proof — Remove one proof photo from one of this company's pallets. (запись · подтверждение + необратимо · все · API: delete_pallet_proof)
• lg pallets extract — Estimate a pallet's content label, dimensions (cm) and gross weight (kg) from photo(s) the user attached to THIS conversation. (запись · — · все · API: extract_pallet_from_photos) [принимает файл: attachment_uuids]
• lg pallets get — Read one pallet in full: its identity (code, label, SKU, barcode), status, warehouse and area, the FULL measurement history (each row with its id, source — manual, lidar, arcore or ai_photo — and confidence), its proof… (чтение · — · все · API: get_pallet)
• lg pallets list — List the pallets of this company: code, label, SKU/barcode, status, which warehouse and area it sits in, its latest measured dimensions (cm) and gross weight, and how many proof photos it has. (чтение · — · все · API: list_pallets)
• lg pallets update — Update an existing pallet: its status (in_stock, in_transit, reserved, shipped, disposed), its label/SKU/barcode/note, or MOVE it to another warehouse or area. (запись · подтверждение · все · API: update_pallet)
• lg parasut-contacts create — Create a new customer or supplier contact IN PARAŞÜT and keep its local copy. (запись · подтверждение + необратимо · все · API: create_parasut_contact)
• lg parasut-contacts list — List the customer / supplier contacts held in Paraşüt (the local copy synchronised from Paraşüt): parasut_contact_id (the Paraşüt id used by create_parasut_sales_invoice — NOT a business contact id), name, short name,… (чтение · — · все · API: list_parasut_contacts)
• lg parasut-invoices create — Issue a SALES invoice in Paraşüt for one of this company's Paraşüt contacts, as an e-invoice (scenario commercial or basic — the recipient must be an e-invoice user) or an e-archive invoice (scenario e_archive); check… (запись · подтверждение + необратимо · все · API: create_parasut_sales_invoice)
• lg parasut-invoices list — List invoices held in Paraşüt (local copy): sales invoices (default) or purchase bills, newest issue date first — invoice id and number, item type, description, issue / due date, net / gross / VAT totals, currency,… (чтение · — · все · API: list_parasut_invoices)
• lg parasut-invoices options — Return the options of the Paraşüt invoice form: income/expense categories (category_id), the Paraşüt bank and cash accounts, and — with tax_number — whether that VKN is a registered e-invoice user (then use scenario… (чтение · — · все · API: get_parasut_invoice_options)
• lg parasut-settings delete — Disconnect Paraşüt from this company: the saved credentials are removed, the accounting provider switches back to local when it was Paraşüt, and the LOCAL copies pulled from Paraşüt (contacts, invoices, bank accounts,… (запись · подтверждение + необратимо · все · API: disconnect_parasut) [ключ manager]
• lg parasut-settings get — Show the Paraşüt integration status of this company: whether it is connected, the Paraşüt firm number, the user name, the client id/secret MASKED (last 4 characters only), when it was connected, the token status and the… (чтение · — · все · API: get_parasut_settings) [ключ manager]
• lg parasut-settings update — Connect this company's Paraşüt account or renew its credentials (replaces an existing connection). (запись · подтверждение · все · API: connect_parasut) [ключ manager] [только CLI]
• lg payables list — Payables ("whom do we owe how much"): per-supplier totals of recorded purchase invoices — invoiced, paid, remaining, earliest due date — with a per-currency breakdown and an overall summary. (чтение · — · все · API: list_payables)
• lg payment-cards delete — Remove a saved payment card (card_id from list_payment_cards). (запись · подтверждение + необратимо · все · API: delete_payment_card) [ключ manager]
• lg payment-cards list — List the company's saved payment cards, MASKED (last four digits only), with the card holder name, expiry and which one is the default card the monthly subscription is charged to. (чтение · — · все · API: list_payment_cards)
• lg payment-cards set-default — Make one of the saved cards (card_id from list_payment_cards) the DEFAULT card: the monthly package payment is charged to it from now on, and every other card loses the default flag. (запись · подтверждение + необратимо · все · API: set_default_payment_card) [ключ manager]
• lg payment-instructions cancel — CANCEL a pending bank payment instruction: the reservation on its invoices is released so they can be paid another way, and the instruction becomes "cancelled". (запись · подтверждение + необратимо · все · API: cancel_settlement_instruction)
• lg payment-instructions download — Get the bank payment instruction document (PDF) with a short-lived download link. (чтение · — · все · API: download_settlement_instruction)
• lg payment-instructions get — Read one bank payment instruction: its code, template, effective date, status with timestamps and cancel reason, its note, and — when the PDF has already been rendered — a short-lived signed link to it so the user gets… (чтение · — · все · API: get_settlement_instruction)
• lg payment-instructions list — List the bank payment instructions of this company: instruction code, which template (bank format) it uses, its effective date, status (pending, executed, cancelled) and when it was executed or cancelled. (чтение · — · все · API: list_settlement_instructions)
• lg payment-instructions run — EXECUTE a pending bank payment instruction (banka talimatını yürüt / uygula): the reserved invoices are paid, the payments and journal entries are written with the instruction's effective date, and the instruction… (запись · подтверждение + необратимо · все · API: execute_settlement_instruction)
• lg planning-boards get — The planning calendar: for every driver, the stretches of days with planned work inside the Schengen area (planned_in), days assumed inside (drive back, assumed_in), planned work outside (planned_out), leave / rest… (чтение · — · перевозчик · API: get_planning_board)
• lg plans archive — Close a plan because the user says the work is finished or abandoned. (запись · — · все · API: archive_plan)
• lg plans create — Write down a multi-step job so it survives between conversations ("link these 5 loads to a trip, then invoice them"). (запись · подтверждение · все · API: create_plan)
• lg plans get — Read one plan: the steps that were agreed AND the commands that actually ran while it was active. (чтение · — · все · API: get_plan)
• lg plans list — List this company's plans, newest first. (чтение · — · все · API: list_plans)
• lg ports search — Find a seaport by name or UN/LOCODE (liman ara) — "Mersin", "TRMER", "Trieste". (чтение · — · все · API: lookup_port)
• lg preferences create — Remember a lasting preference of THIS user, so it applies to every future conversation too ("always show amounts in EUR", "write driver names surname first", "I want the weekly summary on Mondays"). (запись · — · все · API: remember_preference)
• lg preferences delete — Forget one stored preference of this user. (запись · — · все · API: forget_preference)
• lg preferences list — List what you have been asked to remember about THIS user, with the labels. (чтение · — · все · API: list_preferences)
• lg product-brands create — Create a new product brand for this company (the panel's "new brand"). (запись · подтверждение · грузоотправитель · API: create_product_brand)
• lg product-brands list — List this company's product brands (id, name, code, active flag, number of products). (чтение · — · грузоотправитель · API: list_product_brands)
• lg product-categories create — Create a new product category for this company (the panel's "new category"). (запись · подтверждение · грузоотправитель · API: create_product_category)
• lg product-categories list — List this company's product categories (id, name, code, active flag, number of products). (чтение · — · грузоотправитель · API: list_product_categories)
• lg products add-image — Add a photo to a product's gallery. (запись · — · грузоотправитель · API: add_product_image) [принимает файл: attachment_uuid]
• lg products create — Define a new product in this company's catalogue so stock can be recorded against it: name plus optionally its unit of measure, SKU, barcode, category, brand, minimum stock level, reorder quantity and lot tracking. (запись · подтверждение · грузоотправитель · API: create_product)
• lg products delete — Delete a product from this company's catalogue. (запись · подтверждение + необратимо · грузоотправитель · API: delete_product)
• lg products delete-image — Remove one photo from a product's gallery (image_id from get_product). (запись · подтверждение + необратимо · грузоотправитель · API: delete_product_image)
• lg products extract — Read product details (name, description, SKU, barcode, unit, category, brand) from 1-5 photos of the product or its label — the panel's "fill from photo" button. (запись · — · грузоотправитель · API: extract_product_from_photos) [принимает файл: attachment_uuids]
• lg products get — Show one product of this company in full: code, SKU, barcode, unit, category and brand, low-stock threshold and reorder quantity, lot tracking, its photos (with image_id for delete_product_image /… (чтение · — · грузоотправитель · API: get_product)
• lg products list — List the products of this company: code, name, SKU/barcode, unit, category and brand, whether it is active, and its low-stock threshold. (чтение · — · грузоотправитель · API: list_products)
• lg products list-low-stock — List the products whose quantity on hand is BELOW their low-stock threshold (strictly below — a product exactly at the threshold is not listed), with the quantity on hand and the threshold itself. (чтение · — · грузоотправитель · API: list_low_stock_products)
• lg products options — List the units of measure a product can be held in (slug for create_product / update_product unit, with Turkish and English names). (чтение · — · грузоотправитель · API: get_product_options)
• lg products search — Resolve a product to its product_id + on-hand quantity. (чтение · — · грузоотправитель · API: lookup_product)
• lg products set-primary-image — Make one of a product's photos its cover image (image_id from get_product). (запись · — · грузоотправитель · API: set_product_primary_image)
• lg products update — Correct an existing product: its name, unit, SKU, barcode, category, brand, minimum stock level, reorder quantity, lot tracking, note, or whether it is active. (запись · подтверждение · грузоотправитель · API: update_product)
• lg receivables get — Account statement of one contact: every sales invoice issued to them and every collection, in date order with a running balance, plus totals (invoiced, paid, open balance, open invoice count). (чтение · — · все · API: get_receivable_statement)
• lg receivables list — Receivables ("who owes us how much"): per-contact totals of issued sales invoices — invoiced, paid, remaining — with a per-currency breakdown and an overall summary. (чтение · — · все · API: list_receivables)
• lg report-files create — Turn a table you compiled from tool results into a downloadable Excel (default), PDF or CSV file — any custom table, list, comparison or export, with optional charts. (чтение · — · все · API: create_report_file)
• lg reports get — Financial reports from posted journal entries: trial_balance (per-account debit/credit/balance as of a date), balance_sheet (as of a date) or income_statement (revenues/expenses/net income for a date range; defaults to… (чтение · — · все · API: get_accounting_report)
• lg reservations approve — As the warehouse owner, approve a pending reservation received at your warehouse (the booker is notified). (запись · подтверждение · грузоотправитель · API: approve_reservation)
• lg reservations cancel — Cancel (withdraw) a warehouse reservation you booked, or — as the warehouse owner (customer) — cancel a reservation received at your warehouse. (запись · подтверждение + необратимо · все · API: cancel_reservation)
• lg reservations complete — As the warehouse owner, mark an APPROVED reservation at one of your warehouses as completed (the vehicle came and the work is done). (запись · подтверждение + необратимо · грузоотправитель · API: complete_reservation)
• lg reservations create — Book a warehouse dock time slot. (запись · подтверждение · все · API: create_reservation)
• lg reservations get — Detail of one warehouse reservation you booked or (customer) one received at your warehouse: warehouse, area, time window, status, contact, notes, rejection reason. (чтение · — · все · API: get_reservation)
• lg reservations list — List warehouse dock reservations. side=booked_by_me (default): reservations this user/company booked at other companies' warehouses. side=received (customer role only): reservations other companies made at ONE of your… (чтение · — · все · API: list_reservations)
• lg reservations list-slots — Available dock time slots of one day with remaining capacity. (чтение · — · все · API: list_reservation_slots)
• lg reservations reject — As the warehouse owner, reject a pending reservation received at your warehouse, with an optional reason shown to the booker. (запись · подтверждение + необратимо · грузоотправитель · API: reject_reservation)
• lg reservations reschedule — As the warehouse owner, move a PENDING or APPROVED reservation at one of your warehouses to a new time. (запись · подтверждение · грузоотправитель · API: reschedule_reservation)
• lg roro-routes list — For a load you are carrying, list the Ro-Ro (ferry) lines closest to its PICKUP address, nearest first: the line name, its departure and arrival ports and how many kilometres the pickup point is from the departure port. (чтение · — · перевозчик · API: list_nearby_roro_routes)
• lg roro-routes select — Select the Ro-Ro (ferry) line a load you are carrying will use. (запись · подтверждение · перевозчик · API: select_roro_route)
• lg roro-routes set-required — Mark whether a load you are carrying will travel by Ro-Ro (ferry) or not. (запись · подтверждение · перевозчик · API: set_load_roro_required)
• lg route-plans assign-driver — Assign a driver (and, on a double-crew plan, a co-driver; optionally the vehicle/trailer) to a saved route plan (route_plan_id or route_plan_code). (запись · подтверждение · перевозчик · API: assign_driver_to_route_plan)
• lg route-plans calculate — Calculate a multi-stop truck journey WITHOUT saving it: truck driving time (car time × hgv_factor, capped speed), the EU 561/2006 / AETR breaks, daily and weekly rests, weekend/holiday driving bans and border waits, and… (запись · подтверждение · перевозчик · API: calculate_route_plan)
• lg route-plans create — Save a route plan as a DRAFT (same arguments as calculate_route_plan, plus name, vehicle_id, trailer_id, start_flex_days). (запись · подтверждение · перевозчик · API: create_route_plan)
• lg route-plans delete — Cancel and delete a route plan (route_plan_id or route_plan_code). (запись · подтверждение + необратимо · перевозчик · API: delete_route_plan)
• lg route-plans get — One saved route plan: stops with arrival/departure ranges, the summary (distance, truck driving time, arrival optimistic / expected / conservative, breaks, daily/weekly rests, reduced rests, border waits), Schengen days… (чтение · — · перевозчик · API: get_route_plan)
• lg route-plans list — List the company's saved route plans, newest first: code, name, status (draft | assigned | converted | cancelled), departure, crew, driver, vehicle, linked load/trip, stops, arrival range and Schengen day count. (чтение · — · перевозчик · API: list_route_plans)
• lg route-plans preview — Compare 1-6 variants of the same journey side by side — different drivers, departure days or a double crew: arrival range, driving and rest counts, Schengen days left at the end for every crew member, availability /… (запись · подтверждение · перевозчик · API: compare_route_plan_scenarios)
• lg route-plans remove-driver — Take the driver (and co-driver) off an assigned route plan (route_plan_id or route_plan_code); the plan goes back to draft and stops counting as planned Schengen days for them. (запись · подтверждение · перевозчик · API: unassign_driver_from_route_plan)
• lg route-plans select — Link a saved route plan (route_plan_id or route_plan_code) to the load or trip it was planned for — give load_code OR trip_code; give neither to remove the link. (запись · подтверждение · перевозчик · API: link_route_plan)
• lg route-plans update — Change a saved route plan (route_plan_id or route_plan_code): any create_route_plan field — name, departure, stops, crew, options, vehicle. (запись · подтверждение · перевозчик · API: update_route_plan)
• lg schengen-stays calculate — Project ONE driver's Schengen 90/180 days into the future: days used today, then how the remaining days move with the loads, trips and route plans already assigned to him (plus the drive back out) and his leave /… (чтение · — · перевозчик · API: get_driver_schengen_projection)
• lg schengen-stays create-set — Import drivers' past Schengen entry/exit periods (passport stamps) from an Excel/CSV file — one row per stay: driver code or name, entry date, exit date (empty = still inside). (запись · подтверждение · перевозчик · API: import_driver_schengen_periods) [принимает файл: attachment_uuid]
• lg schengen-stays download — Give a short-lived download link to the Schengen history import template, pre-filled with the company's active drivers (user code + name; entry/exit date cells empty). (чтение · — · перевозчик · API: download_schengen_import_template)
• lg schengen-stays get — One driver's full Schengen 90/180 picture: days used (confirmed / declared / inferred), days left (signed; negative = overstay), latest exit date, breach date, when days come back (regain schedule), per-country day… (чтение · — · перевозчик · API: get_driver_schengen_detail)
• lg schengen-stays list — Fleet-wide Schengen 90/180 compliance: which drivers breached the 90-days-in-180 rule or are close to it, how many days each has left (days_remaining is SIGNED — negative means overstay), the latest exit date… (чтение · — · перевозчик · API: list_schengen_compliance)
• lg schengen-stays list-periods — List the Schengen stay periods DECLARED for a driver (passport stamps / starting balance) with their period_id, entry and exit dates and day count. (чтение · — · перевозчик · API: list_driver_schengen_periods)
• lg schengen-stays remove-period — Delete ONE wrongly entered declared Schengen period of a driver (period_id from list_driver_schengen_periods). (запись · подтверждение + необратимо · перевозчик · API: delete_driver_schengen_period)
• lg schengen-stays set-baseline — Set a driver's Schengen starting balance — what happened BEFORE GPS tracking: either the exact periods inside the zone from passport stamps (baseline_mode=periods) or just "X days used in the last 180"… (запись · подтверждение · перевозчик · API: set_driver_schengen_baseline)
• lg schengen-stays set-exemption — Exempt a driver from Schengen 90/180 tracking (EU/EFTA passport, residence permit, national long-stay visa) or switch the rule back on. (запись · подтверждение · перевозчик · API: set_driver_schengen_exemption)
• lg settlements cancel — CANCEL a bulk collection / payment (settlement batch). (запись · подтверждение + необратимо · все · API: cancel_settlement_batch) [ключ manager]
• lg settlements create — Close several open invoices of ONE contact in ONE currency in a single bulk collection (direction in) or bulk payment (direction out). instrument transfer = money already moved by bank transfer (payments + journal… (запись · подтверждение + необратимо · все · API: create_settlement_batch)
• lg settlements get — Read one bulk collection / payment (settlement batch) in full: code, direction (in = collection, out = payment), instrument (transfer, bank instruction or cheque), status, counterparty, currency and total, value date,… (чтение · — · все · API: get_settlement_batch)
• lg settlements list — List bulk collection/payment batches (code, direction, instrument, contact, currency, total, value date, status), newest first. (чтение · — · все · API: list_settlement_batches)
• lg settlements list-counterparties — List the business contacts that have OPEN local invoices in one money direction — in = customers owing us (sales invoices), out = suppliers we owe (purchase invoices) — each with its default open-invoice currency and… (чтение · — · все · API: list_settlement_counterparties)
• lg settlements list-invoices — Open LOCAL invoices of one contact in one currency that can be allocated in a bulk collection (direction in = sales invoices) or bulk payment (direction out = purchase invoices), each with payable_remaining (remaining… (чтение · — · все · API: list_settlement_invoices)
• lg settlements options — Return the options of the bulk collection / payment form: allowed currencies, this company's OWN bank accounts (bank_account_id for create_settlement_batch / attach_check_to_invoices), bank instruction templates, batch… (чтение · — · все · API: get_settlement_options)
• lg ship-trackings create — Attach a ship to a load and track it on the load's map (yüke gemi bağla), or swap the ship (replace_ship_id = the ship being replaced) — "FKZ8515 sails on MSC Gülsün, track it". (запись · подтверждение · грузоотправитель, перевозчик · API: track_ship_for_load)
• lg ship-trackings delete — Stop tracking a ship on a load (gemi takibini durdur). (запись · подтверждение · грузоотправитель, перевозчик · API: stop_ship_tracking)
• lg ship-trackings get — Show the ship(s) tracked on a load and their position history since the load was created (yükün gemi takibi) — "where is FKZ8515's ship now". (чтение · — · все · API: get_load_ship_tracking)
• lg ships search — Search the ship registry (gemi sicili) by name, IMO or MMSI — "what is MSC Gülsün's IMO", "find the vessel 9839430". (чтение · — · все · API: lookup_ship)
• lg stock adjust — Record a stock count correction (sayım düzeltme) or write-off (fire). mode=set sets the absolute on-hand at the slot; mode=delta applies a signed change (negative reduces). reason is required. (запись · подтверждение + необратимо · грузоотправитель · API: create_stock_adjustment)
• lg stock list — Read current on-hand stock levels. (чтение · — · грузоотправитель · API: check_stock_level)
• lg stock list-movements — List the stock movements of this company, newest first: which product moved, in or out (or a transfer or a count adjustment), how much, in which warehouse and area, on which pallet, who performed it and when. (чтение · — · грузоотправитель · API: list_stock_movements)
• lg stock move — Record a stock movement: inbound (giriş), outbound (çıkış), or transfer between locations. (запись · подтверждение + необратимо · грузоотправитель · API: create_stock_movement)
• lg stock options — List the stock movement types (receipt, issue, transfer, count adjustment …) with their slug and Turkish/English names — the values create_stock_movement and list_stock_movements use. (чтение · — · грузоотправитель · API: get_stock_options)
• lg sub-companies create — Add a group / sub company (alt firma) to this customer company: legal_name (ticaret unvanı), tax_office (vergi dairesi), tax_number and the full address — all four required. (запись · подтверждение · грузоотправитель · API: create_sub_company) [ключ manager]
• lg sub-companies delete — Delete one of this customer company's group / sub companies (alt firma) by sub_company_id from list_sub_companies. (запись · подтверждение + необратимо · грузоотправитель · API: delete_sub_company) [ключ manager]
• lg sub-companies list — This customer company's group / sub companies (alt firmalar, grup şirketleri — Settings › Sub Companies): sub_company_id, legal name, tax office, tax number and address. (чтение · — · грузоотправитель · API: list_sub_companies)
• lg tariff-chapters get — Answer "which chapter is this GTİP in / what does chapter 76 cover / what do the chapter notes say?". (чтение · — · все · API: get_tariff_chapter)
• lg tariff-matrices get — FREE. (чтение · — · все · API: get_tariff_matrix)
• lg tariff-matrices list — FREE. (чтение · — · все · API: list_tariff_matrix_runs)
• lg tariff-matrices preview — FREE. (чтение · — · все · API: plan_tariff_matrix)
• lg tariff-matrices run — Run an official duty + anti-dumping inquiry for ONE tariff code across MANY origin and destination countries at once, and record it. (запись · подтверждение + необратимо · все · API: run_tariff_matrix)
• lg tariffs coverage — FREE. (чтение · — · все · API: get_tariff_coverage)
• lg tariffs extract — Read an invoice or proforma the user attached to THIS conversation and pull out its product lines with candidate GTİP/HS codes, plus the origin and destination it names. (запись · — · все · API: extract_tariff_codes_from_invoice) [принимает файл: attachment_uuid]
• lg tariffs get — Read the result of a tariff inquiry that was already run: duty rate, the column it came from, the statutory rate, anti-dumping measures and the data notes. (чтение · — · все · API: get_tariff_inquiry)
• lg tariffs inquiry — Start an official duty / anti-dumping inquiry for one GTİP/HS code and a COUNTRY PAIR (origin → destination). (запись · подтверждение + необратимо · все · API: run_tariff_inquiry)
• lg tariffs list — List this company's recent tariff inquiries (code, direction, counterpart country, status, date) so the user can find an earlier one by code or country instead of running a new inquiry. (чтение · — · все · API: list_tariff_inquiries)
• lg tariffs search — Search the Turkish customs nomenclature (GTİP / HS) by goods description or by a partial code, and return matching codes with their official descriptions. (чтение · — · все · API: lookup_tariff_code)
• lg teammates delete — Remove a person from the company team. (запись · подтверждение + необратимо · все · API: remove_teammate) [ключ manager]
• lg teammates list — List the other users of this company (drivers excluded) with e-mail, active state and RBAC role (manager | employee | fleet-manager), plus seat_usage (team seats used / limit / remaining under the package). role narrows… (чтение · — · все · API: list_teammates)
• lg teammates set-role — Change a team member's role (for example make them a manager, or move them back to employee). (запись · подтверждение · все · API: update_teammate_role) [ключ manager]
• lg teammates set-status — Activate or deactivate a team member. (запись · подтверждение · все · API: set_teammate_status) [ключ manager]
• lg tender-bids create — Submit YOUR bid for a tender using a file the user attached to THIS conversation (the filled specification spreadsheet, a PDF offer, or a zip). (запись · подтверждение + необратимо · перевозчик · API: submit_tender_bid) [принимает файл: attachment_uuid]
• lg tender-bids get — Read YOUR OWN bid on a tender: its status (submitted, revision requested, accepted, rejected), when it was submitted and which files it carries. (чтение · — · перевозчик · API: get_my_tender_bid)
• lg tender-bids set-status — As the tender owner, ACCEPT a carrier's bid, REJECT it, or ask for a REVISION. (запись · подтверждение + необратимо · грузоотправитель · API: decide_tender_bid)
• lg tenders add-document — Attach a file to one of YOUR tenders as an additional specification document (accepted: pdf, xlsx, xls, doc, docx; at most 10 MB). (запись · подтверждение · грузоотправитель · API: add_tender_document) [принимает файл: attachment_uuid]
• lg tenders create — Open a NEW document-based freight tender and generate its specification Excel from the lanes the user gives (origin → destination, vehicle/load type, monthly volume). (запись · подтверждение · грузоотправитель · API: create_tender) [принимает файл: attachment_uuid]
• lg tenders delete-document — Remove a specification file from one of YOUR tenders (document_id from get_tender → documents[]). (запись · подтверждение + необратимо · грузоотправитель · API: delete_tender_document)
• lg tenders extract — Draft the specification (terms) text of a tender from a tender document the user supplies (accepted: pdf, xlsx, xls; at most 10 MB). (чтение · — · грузоотправитель · API: extract_tender_specification) [принимает файл: attachment_uuid]
• lg tenders generate — Generate a specification Excel for an EXISTING tender from the lanes/items the user gives and attach it to the tender as a document; returns a short-lived download link. (запись · подтверждение · грузоотправитель · API: generate_tender_excel)
• lg tenders get — Read one tender in full: specification text, dates, attached specification files (with short-lived download links) and — for the tender owner — every carrier bid with its status; a carrier sees only its own bid. (чтение · — · грузоотправитель, перевозчик · API: get_tender)
• lg tenders list — List document-based freight tenders. (чтение · — · грузоотправитель, перевозчик · API: list_tenders)
• lg tenders update — Edit one of YOUR tenders: title, description, specification text, the bidding window (start_date / end_date), the price-validity window, whether it still accepts bids (is_active), its status, and who it is shared with. (запись · подтверждение · грузоотправитель · API: update_tender)
• lg trade-measures get — Answer "is there an anti-dumping / countervailing / safeguard measure on this GTİP code when importing INTO TURKEY?" straight from the Ministry of Trade's measures-in-force list, which we sync every day. (чтение · — · все · API: get_trade_measures)
• lg trade-measures list — Browse Türkiye's trade-defence measures WITHOUT a GTİP code: by origin country ("which measures apply to goods from China"), by product ("which countries have a measure on aluminium foil"), by measure type, or by end… (чтение · — · все · API: list_trade_measures)
• lg user-accounts preview — Show what closing MY OWN account would do, without closing it: whether I am a manager, whether I am the only user (then the company is deactivated too), whether I must first hand the manager role to a teammate… (чтение · — · все · API: preview_account_closure)
• lg users get — Who am I? (чтение · — · все · API: get_current_user)
• lg vehicle-assignments create — Hand a fleet vehicle over to a driver (open an assignment), so their expense receipts and trips are attached to the right tractor unit or trailer. (запись · подтверждение · грузоотправитель, перевозчик · API: assign_vehicle_to_driver)
• lg vehicle-assignments list — List which driver currently holds which vehicle (tractor unit / trailer). (чтение · — · грузоотправитель, перевозчик · API: list_vehicle_assignments)
• lg vehicle-assignments revoke — Close an open vehicle assignment: the driver hands the vehicle back. (запись · подтверждение · грузоотправитель, перевозчик · API: end_vehicle_assignment)
• lg vehicle-expenses create — Record a cost against one of the company's own vehicles without an invoice file — category, amount and currency are required, the rest is optional. (запись · подтверждение · грузоотправитель, перевозчик · API: create_vehicle_expense) [принимает файл: attachment_uuid]
• lg vehicle-expenses delete — Delete a vehicle cost entered by mistake (duplicate, wrong plate, test entry). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_vehicle_expense)
• lg vehicle-expenses list — List the cost records of the company's own vehicles (maintenance, tyres, repair, roadworthiness test, insurance, fuel, tolls, parts) with a EUR total and a breakdown per category and per currency. (чтение · — · грузоотправитель, перевозчик · API: list_vehicle_expenses)
• lg vehicle-expenses update — Correct a recorded vehicle cost: category, amount, currency, vendor, invoice number, invoice date or description — "the tyre invoice was 580 not 850". (запись · подтверждение · грузоотправитель, перевозчик · API: update_vehicle_expense)
• lg vehicles add-document — File a paper of one of the company's own vehicles — registration (ruhsat), traffic or kasko insurance, roadworthiness inspection, tachograph calibration, CMR insurance, green card, ADR certificate — from an uploaded… (запись · подтверждение · грузоотправитель, перевозчик · API: add_vehicle_document) [принимает файл: attachment_uuid]
• lg vehicles archive — Take a vehicle out of service (archive it) or put an archived one back into service. (запись · подтверждение · грузоотправитель, перевозчик · API: archive_vehicle)
• lg vehicles create — Add a vehicle to this company's fleet: plate plus its kind (truck, tractor unit, trailer, van, pickup, car), optionally brand, model, model year, VIN and a note. (запись · подтверждение · грузоотправитель, перевозчик · API: create_vehicle) [принимает файл: attachment_uuid]
• lg vehicles delete — Delete a vehicle record that was created BY MISTAKE (wrong plate, duplicate). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_vehicle)
• lg vehicles delete-document — Remove a paper from a vehicle's file (a duplicate row, a paper filed on the wrong vehicle, an old registration). (запись · подтверждение + необратимо · грузоотправитель, перевозчик · API: delete_vehicle_document)
• lg vehicles get — Full detail of ONE fleet vehicle: identity (plate, kind, brand, model, model year, VIN), whether it is active or archived, ALL of its papers with their expiry date and days_to_expiry, how many papers expire soon or… (чтение · — · грузоотправитель, перевозчик · API: get_vehicle)
• lg vehicles list — List this company's fleet vehicles with plate, kind (truck / tractor unit / trailer / van / pickup / car), brand, model, model year, VIN and how many of their papers (insurance, inspection, permits) expire soon or have… (чтение · — · грузоотправитель, перевозчик · API: list_vehicles)
• lg vehicles search — Resolve one of this company's fleet vehicles (truck, tractor unit, trailer, van, pickup, car) to its vehicle_id by plate, brand, model or VIN. (чтение · — · грузоотправитель, перевозчик · API: lookup_vehicle)
• lg vehicles update — Correct a fleet vehicle's fields: plate, kind, brand, model, model year, VIN or note. (запись · подтверждение · грузоотправитель, перевозчик · API: update_vehicle)
• lg vehicles update-document — Correct a vehicle paper already on file — most often its expiry date (valid_until) after a renewal or a wrong AI reading, but also its type, number, issue date, issuer, the plate printed on it, issuing country, title or… (запись · подтверждение · грузоотправитель, перевозчик · API: update_vehicle_document)
• lg wallets get — Read this company's Logistivo WALLET balance — the prepaid MONEY balance (amount + currency). (чтение · — · все · API: get_wallet_balance)
• lg wallets list-transactions — List this company's Logistivo WALLET movements, newest first: top-ups and money spent on packages or paid features, with the amount, the balance before/after, who did it and when. (чтение · — · все · API: list_wallet_transactions)
• lg warehouse-areas create — Add a new area to one of this company's warehouses — an open area, a closed area or a loading ramp — with how many vehicles it can take at the same time (its booking slot capacity). (запись · подтверждение · грузоотправитель · API: create_warehouse_area)
• lg warehouse-areas delete — Delete one area/ramp of a warehouse. (запись · подтверждение + необратимо · грузоотправитель · API: delete_warehouse_area)
• lg warehouse-areas update — Change a warehouse area's name, type (open_area, closed_area, ramp), vehicle capacity, display order or active flag. (запись · подтверждение · грузоотправитель · API: update_warehouse_area)
• lg warehouse-links create — Create a public booking link for one of this company's warehouses, to share with a carrier, supplier or customer: anyone holding the URL can book a slot (the booking still waits for your approval). (запись · подтверждение · грузоотправитель · API: create_warehouse_link)
• lg warehouse-links list — List the public booking links shared for one of this company's warehouses: the full URL (anyone holding it can book a slot), the area it is limited to (if any), the expiry, and whether it is active. (чтение · — · грузоотправитель · API: list_warehouse_links)
• lg warehouse-links revoke — Permanently revoke a warehouse booking link: the URL stops working for everyone and cannot be brought back (create a new link if needed). (запись · подтверждение + необратимо · грузоотправитель · API: revoke_warehouse_link)
• lg warehouse-links set-status — Turn a warehouse booking link off (nobody can book through it) or back on. (запись · подтверждение · грузоотправитель · API: set_warehouse_link_status)
• lg warehouses create — Define a new warehouse for this company so stock can be held and dock slots booked there: a name and its street address are enough. (запись · подтверждение · грузоотправитель · API: create_warehouse)
• lg warehouses delete — Delete one of this company's warehouses. (запись · подтверждение + необратимо · грузоотправитель · API: delete_warehouse)
• lg warehouses get — Read one warehouse in full: its identity and address, working days and hours, holiday opening, capacity, reservation slot rules (slot length, minimum and maximum duration), its safety and driver rules, the… (чтение · — · грузоотправитель · API: get_warehouse)
• lg warehouses list — List the warehouses of this company: name, address, whether it is active, its working days and hours, open/closed area capacity, the dock slot length and how many areas (racks/bays) it has. (чтение · — · грузоотправитель · API: list_warehouses)
• lg warehouses search — Resolve a warehouse by name to its warehouse_id, with its areas. (чтение · — · грузоотправитель · API: lookup_warehouse)
• lg warehouses set-equipment — Set a warehouse's equipment list IN FULL (forklift, transpallet = pallet truck, other; with quantity and an optional name/specification). (запись · подтверждение · грузоотправитель · API: set_warehouse_equipment)
• lg warehouses update — Update a warehouse: its name or address, working days and hours, holiday opening, capacity, dock slot rules, the driver/safety flags or the active flag. (запись · подтверждение · грузоотправитель · API: update_warehouse)

Интеграция с 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 без аутентификации: один файл, который можно передать коллегам.
• Операций: 559 — 519 (команды) + 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-эндпоинты, несущие интеграционный контракт, и эндпоинты обнаружения. Количество — для ВАШЕЙ роли, а не общее по платформе: сегодня ключ грузоотправителя даёт методов команд — 448, перевозчика — 452, таможенного брокера — 312. Если генерировать из публичного описания без аутентификации, максимум операций — 559. 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-эндпоинт, несущий интеграционный контракт, и эндпоинты обнаружения. Генерируйте из описания своей роли — и получите только то, что можете вызвать (для грузоотправителя команд — 448); генерируйте из публичного описания — и получите все операции (559). В день, когда на сервере добавляется команда, повторная генерация приносит её; ждать релиза клиента не нужно.
• Типы аргументов — Схема `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 работает в контексте пользователя тенанта — Каждая команда выполняется от имени компании и роли пользователя, чей токен предъявлен. Режим оператора платформы — административный режим, читающий данные разных компаний, — находится вне этой поверхности и отсюда открыт не будет.
• Ваш список команд зависит от роли — Число команд для аккаунта грузоотправителя — 448, перевозчика — 452, таможенного брокера — 312, аффилиата — 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 a public MCP server at https://logistivo.com/api/agent/mcp (streamable HTTP, no authentication). Setup instructions for Claude, ChatGPT and Gemini: https://logistivo.com/mcp. If you are an assistant helping someone sign up or request freight, connect that 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. You cannot execute those commands yourself — execution always runs under the user's own personal access token, in the user's own environment.