Logistivo CLI:物流オペレーションをターミナルから、そして ERP から実行
1 つのコマンドカタログが 3 つの窓口を支えています。lg ターミナルクライアント、ダッシュボード内の AI アシスタント、そして外部 AI アシスタントが接続するチャネルです。機能は一度書かれると 3 つすべてに現れます。さらに、パネルのすべての書き込み操作に対応するコマンドが揃ったため、チームが画面上で行っている作業を、スクリプトや自社の AI エージェントが実行できます。決済、法的同意、アカウントの閉鎖は意図的にブラウザに残しています。 このページは契約(コントラクト)です。下のコマンド表は手書きではなく、リクエストのたびにライブのコマンドレジストリから生成されます。
Logistivo CLI とは何ですか?
Logistivo CLI(lg)は、Logistivo アカウントの業務(貨物と運行、輸送依頼、見積もりと入札、車両とドライバー、書類、取引先と取引先元帳、請求書と会計、倉庫と在庫、チームメンバー、関税率)を、ターミナル、スクリプト、または自社の AI エージェントから実行するコマンドラインクライアントです。コマンドはクライアントに組み込まれていません。クライアントはサーバーからコマンドカタログを取得し、それをもとに自分自身を組み立てます。同じコマンドは何もインストールせずに HTTP 経由でも呼び出せます(ERP・CRM 連携が使うのはこの経路です)。また、外部 AI アシスタントが接続する MCP チャネルからも呼び出せます。
コマンドの形は 1 つだけです:lg --parameter=value 。カタログには現在 175 ドメインにわたる 721 個のコマンドがあり、1 つのロールが見られる最大の一覧は 165 ドメインにわたる 646 個のコマンドです。
パネルのすべての書き込み操作にコマンドがあります。パネルの書き込みエンドポイントと照合した結果、対象範囲内のものは 100% カバーされています。決済(3D Secure)、法的同意、アカウントの閉鎖は意図的にブラウザに残しており、これらについてはコマンドが代わりにリンクを返します。
書類や写真を受け取るコマンドもブラウザの外で動作します。--attachment_uuid=@./cmr.pdf と書けば、lg が先にファイルをアップロードします。HTTP の場合は /api/common/commands:upload にアップロードし、返された attachment_uuid を渡します。
連携キー(integration key)にはアクセスレベルがあります。日常業務には employee(新しいキーのデフォルト)、チーム・設定・キー・お金に関わる操作には manager を使います。キーが、代理で操作する本人より多くの権限を持つことはありません。
フラグが勝手に作られることはありません。すべてのフラグはそのコマンド自身の JSON Schema にあるパラメータ名であり、型と必須かどうかも同じく JSON Schema で決まります。
書き込みコマンドは確認を求めます。取り消せないコマンドは確認なしには決して実行されません(HTTP 409、CLI 終了コード 4)。
再試行しても重複は生まれません。idempotency_key を付けた呼び出しは最大 1 回しか実行されません。
すべての実行は 1 つの監査台帳に記録されます。ターミナル、チャット、アシスタントのどこから来たかも記録に残ります。
現在稼働しているもの、そして準備中のもの
このセクションは意図的にページの先頭に置いています。連携ドキュメントが犯しうる最も高くつく誤りは、まだ公開されていないエンドポイントを公開済みであるかのように説明することです。連携担当者がコードを書き、エンドポイントが 404 を返し、信頼は二度と戻りません。
コントラクトは凍結されているため、今日書いた連携コードは、残りの部分が公開されても動き続けます。知らないフィールドは無視しなければなりません。このルールがあるからこそ、互換性を壊さずに追加できるのです。
コマンドカタログと識別テーブル — すべてのコマンドの公開 domain/verb 識別子は凍結されており、コントラクトバージョンはすべてのカタログレスポンスと X-Contract-Version ヘッダーで 1 として公開されています。このページの表はライブのレジストリから生成されます。サーバーで追加されたコマンドは自動的にここに現れ、削除されたコマンドは消えます。
認証不要のディスカバリーエンドポイント — 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} の 3 つです。ロールゲート、確認ゲート、冪等性、監査台帳は 1 か所の適用ポイントに集約されており、チャットとターミナルも同じポイントを通過します。
パネルのカバレッジ:すべての書き込み操作にコマンドがある — 175 ドメインにわたる 721 個のコマンドを、パネルの書き込みエンドポイントと照合しました。対象範囲内のすべてのエンドポイントがコマンド(エンドポイントのミラー、または同じ共有サービス)で裏付けられており、未検証のものはありません。意図的に対象外としているのは、ブラウザに残る 3D Secure 決済・法的同意・アカウントの閉鎖・サインイン、lg の組み込みコマンドであるキー・Webhook・サンドボックスの管理、そしてドライバーアプリ専用のエンドポイントです。
プリフライト(dry_run):実行せずに結果を確認 — リクエストボディに dry_run: true を含めると、コマンドは実行されません。バリデーション、ロール/スコープゲート、対象の解決、クレジット計算はすべて実行されてプレビューが返りますが、何も書き込まれず、クレジットも消費されず、冪等キーも消費されません。バッチエンドポイントもバッチ単位でこれを受け付けます。プリフライトがコマンドのハンドラーに入ることはありません。リリース時には、当時カタログにあったすべての書き込みコマンドに対する 178 回のプリフライトで、書き込みステートメントは 1 つも発生しませんでした。
連携キー — 実在するチームメンバーの代理として動作する API キーで、パネルまたは lg keys create で発行します。read/write スコープ、アクセスレベル(デフォルトは employee、または manager)、有効期間、最終使用日時、ローテーション、移譲、失効を備えています。lg login --api-key、lg whoami、そしてサーバー側でもキーを失効させる lg logout は、このキーの上に構築されています。
サンドボックス:本番に触れずに書き込みをリハーサル — 企業ごとに、同じコマンドカタログを持つ独立したサンドボックステナントが用意されます。セルフサービスで開設でき、専用のキーを発行します。クレジット、マーケットプレイス、Webhook のルーティングは 2 つの環境で分離されています。環境はキーの所属企業から導出され、リクエストで指定することはできません。
バージョニング、エラー分類、冪等性、レート制限 — コマンドは since / deprecated_at / replaced_by / aliases を持ち、非推奨のコマンドは X-Deprecated ヘッダー付きで応答します。業務上の失敗には、トランスポートレベルの error_code に加えて安定した error_key が付き、キーの辞書はカタログで公開されています。冪等キーは自社にスコープされ、1 つのコマンドに紐づき、24 時間ロックされます。レート制限はトークン単位で 3 つのバケットに分かれており、すべての 429 には Retry-After が付きます。
送信 Webhook:何かが起きたら POST — 署名付きプッシュは 13 種類のイベントで稼働中です。購読はパネルまたは lg webhooks で管理します。署名には独自のタイムスタンプが含まれ、再試行スケジュールは 60 · 300 · 1800 · 7200 · 21600 秒で、ミュートの理由は必ず記録されます。すべてのイベント名は、実際にディスパッチされるイベントクラスに裏付けられています。告知だけして一度も送られないものはありません。プル方式(updated_since + cursor)は廃止していません。プッシュはその代わりではなく、その隣に追加されたものです。
ファイルを受け取るコマンド — 38 個のコマンドが書類や写真(CMR、請求書、車検証、パレット写真)を受け取ります。POST /api/common/commands:upload に一度アップロードするか、--attachment_uuid=@./file.pdf で lg に任せ、返された attachment_uuid を渡します。MCP クライアントは upload_attachment ツールを使います。ファイル形式は内容から判定され、アップロードは 24 時間利用できます。
lg ターミナルクライアント — MIT ライセンスで npm に公開されています。`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)は確定しており、一覧コマンドへ順次展開中です。ある一覧コマンドが JSON Schema で cursor と updated_since を公開するまでは、小さなウィンドウとして扱ってください(上限 20 行、カーソルなし)。
何が違うのか:クライアントはコマンドを知らず、カタログから描き出す
これは、このページの残りすべてに意味を与える唯一の設計判断です。一般的な CLI ではコマンドはクライアントの中にありますが、Logistivo ではサーバー上にあります。
従来の構成では、サーバーに機能が加わるとクライアントの新しいリリースが必要になり、ユーザーはそれをインストールしなければなりません。その間、両者が知っている内容は食い違います。これこそ連携で最も気づかれにくい失敗パターンです。スクリプトは動き、終了コードは 0 なのに、コマンドはサーバーにできることを正しく表していないのです。
Logistivo では、コマンドの定義は 1 つのレコードです。名前、何をするか、JSON Schema パラメータ、どのロールが見られるか、確認が必要か、その効果を元に戻せるか。lg は起動時にこのカタログを取得し、ヘルプテキスト、フラグ、入力バリデーションをそこから生成します。サーバーでコマンドが追加された瞬間に、クライアントを更新しなくても lg はそれを知っています。
同じカタログが、ダッシュボードの AI アシスタントと、外部 AI アシスタントが接続するチャネルも支えています。機能は一度書かれると 3 か所に現れ、3 つすべてが同じロールゲート、同じ確認ゲート、同じ監査台帳を通ります。CLI 専用のコマンド一覧は別に存在しません。もしあれば、3 つの窓口は半年もしないうちに静かに食い違っていくでしょう。
バージョンのずれがない — クライアントが知っているコマンド一覧は、構造上、サーバーが持つ一覧そのものです。「このコマンドはどの lg バージョンにありますか?」という問いはそもそも存在しません。
フラグ名を推測する必要がない — コマンドのフラグは、その JSON Schema のパラメータ名そのものです。コマンドが何を受け付けるかを知る方法は、ドキュメントを読むことではなくカタログを読むことです。そしてカタログは常に最新です。
CLI の大きさはアカウントに応じて決まる — カタログはロールでフィルタリングされます。自分のロールで見られないコマンドが一覧に現れることはありません。運送会社アカウントには 621 個、荷主には 646 個、通関業者には 392 個のコマンドが表示され、アフィリエイト(紹介パートナー)アカウントには独自の 55 個のコマンドが表示されます。
ドキュメントが遅れることがない — このページのコマンド表も同じレジストリから生成されています。人間が現実と同期させ続けなければならない一覧は、どこにも存在しません。
命名ルール:コマンド名はどのように増えていくか
カタログは今後も成長します。新しいコマンドはその場しのぎで命名されるのではなく、6 つのルールに従います。ここで公開するのは、これらがあなたの連携コードで何年にもわたって書かれ続ける名前であり、その予測可能性があなたにとって価値を持つからです。
ドメインは複数形のエンティティ — loads、demands、invoices、export-documents。2 語のドメインは kebab-case です。唯一の例外は不可算名詞で、stock は複数形にしません。「stocks」は別の意味になるからです。
1 つのエンティティの動詞はすべて 1 つのドメインに置く — loads は貨物に作用するすべての動詞を持ちます:create、list、get、update、set-status、assign-driver、list-problems、archive など。動詞ごとに新しいドメイン(load-statuses、load-drivers)を作ると、ユーザーは同じエンティティを 3 か所で探し回ることになります。
動詞はドメインに漏れ出さない。ドメインは「変化するもの」である — ドライバーを割り当てたときに変化するのはドライバーではなく貨物なので、lg loads assign-driver になります。間接目的語(-driver)は動詞に付け、ドメインには決して付けません。
サブリソースには独自のドメインを与えない — 請求書の明細行や書類の品目は単独では一覧できず、所有者を通じて指定します(lg invoices add-line、lg export-documents add-item)。判断基準は 1 つです。それを単独で list も get もできないなら、それはドメインではありません。
絞り込みは新しい動詞ではなくフラグで行う — lg fleet-documents list --days=30 が正しい形です。期間はすでにパラメータなので、「list-expiring」という別の動詞はありません。修飾付きの動詞を使うのは、返す行がそのドメインのエンティティではない場合だけです。loads list-problems が返すのは貨物ではなく問題フラグです。
(domain, verb)の組はカタログ全体で一意 — ロールが決して重ならない 2 つのコマンドであっても同様です。同じ組が 2 つのコマンドに与えられると、連携コードは 1 つの名前を見ているのに、CLI は呼び出した人によって異なる処理を実行してしまいます。
カバレッジ:パネルのすべてを、コマンドから
多くのチームが Logistivo を自社の AI エージェントや自動化の仕組みに組み込んでいます。エージェントは、仕事を最後までやり遂げられて初めて役に立ちます。そこでルールは単純です。オフィスのユーザーがパネルで変更できるものは、コマンドでも変更できます。同じロールゲート、同じ確認ゲート、同じ監査台帳のもとで。
これは主張ではなく測定結果です。パネルの背後にあるすべての書き込みエンドポイントをコマンドレジストリと照合しており、あるエンドポイントがカバー済みと数えられるのは、コマンドがそれを自身の HTTP ミラーとして宣言しているか、同じ共有サービスを呼び出している場合だけです。対象範囲内の書き込みエンドポイントは 100% カバーされており、未検証のものはありません。除外したすべてのエンドポイントには、理由が文書で記されています(本人確認と決済のステップ、連携のコントロールプレーン、ドライバーアプリ専用のエンドポイント、クライアントのテレメトリー、呼び出し元のない使われていない複製)。連携担当者にとって重要なものは以下に挙げています。
ファイルを受け取るコマンドも同じルールに従います。表のうち 38 個のコマンドが書類や写真を受け取り、そのすべてが lg、HTTP、MCP から動作します(「ファイルを受け取るコマンド」を参照)。
管理業務も、より強いキーのもとでカバーされています。表のうち 87 個のコマンド(チームメンバーとロール、企業設定、銀行口座、保存済みカード、連携キー)には、manager レベルの連携キーが必要です。デフォルトの employee レベルのキーは日常業務を実行し、これらのコマンドは INSUFFICIENT_KEY_LEVEL で拒否されます。
アフィリエイト(紹介パートナー)アカウントには独自のカタログがあります:20 ドメインにわたる 55 個のコマンドで、紹介、リード、CRM のメモとタスク、営業資料、収益と支払いに加え、すべてのロールが持つアカウントとチームのコマンドを含みます。アフィリエイト専用のコマンドは、パネルの 3 つのロールを掲載する下の公開表には含まれていません。アフィリエイトアカウントでは 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. 結果をコマンドで読み取る — ステップが完了すると、その結果は再びコマンドから見えるようになります:パッケージとクレジット残高、保存済みカード(マスク済み、下 4 桁のみ)、キー一覧の新しいキー。エージェントがチャットでカード番号、決済、同意を受け取ることは決してありません。
決済と 3D Secure — パッケージの購入やアップグレード、カードの追加には、ブラウザでの 3D Secure が必要です。コマンドでは、パッケージと価格の一覧表示、残高とその履歴の読み取り、保存済みカード(マスク済み)の一覧表示、デフォルトカードの設定とカードの削除ができます。購入そのものは引き渡しリンクを通じて行います。
法的同意 — 法的文書への同意は、本人がブラウザで行います。lg users get は同意が保留中であることを教えてくれますが、どのコマンドも同意を与えることはできません。
アカウントの閉鎖、サインイン、パスワード — 自分のアカウントの閉鎖、サインイン、パスワードの変更は本人確認のステップであり、ブラウザに残ります。lg user-accounts preview は、実際には閉鎖せずに、アカウントを閉鎖すると何が起きるかを示します。
連携キー、Webhook、サンドボックス — これらの管理では、ターミナルで一度だけ表示しなければならないシークレットが返されるため、カタログのコマンドではなく、専用の HTTP エンドポイント上で動作する lg の組み込みコマンド(lg keys、lg webhooks、lg sandbox)になっています。カタログに含まれるのは、シークレットを伴わない 2 つのキー用コマンド、integration-keys list と integration-keys revoke だけです。
ダッシュボードのアシスタントチャット — 連携キーでは、ダッシュボード内の AI アシスタントチャットを操作できません。キーで実行を開始または継続しようとすると 403 が返ります。エージェントは代わりにコマンドエンドポイント、lg、または MCP チャネルを通じて接続します。そこでは各コマンドがキーのアクセスレベルで実行され、その書き込みは連携による書き込みとして記録されます。
ドライバーアプリ — ドライバーアカウントにはコマンドカタログがなく、ドライバーアプリは専用のエンドポイントを持ち続けます。オフィスのユーザーは、ドライバー、その書類、経費、運行をコマンドで管理します。
インストールと認証
lg は依存関係のない単一ファイルの Node スクリプト(Node 18 以上)で、npm で @lgstv/lg として公開されています。パッケージは同一の 2 つのコマンド lg と logistivo をインストールします。お使いのマシンで lg がすでにエイリアスとして使われている場合は logistivo を使ってください。単一ファイルなので、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(メールアドレスとパスワード)は代替手段として引き続き使えます。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 は 1 つのコマンドの全パラメータを、型と必須かどうかとともに表示します。これらのテキストはどれもクライアントの中にはなく、すべてカタログから来ています。一覧はロールによって異なることに注意してください。同じドメインでも、運送会社と荷主とでは動詞が異なります(たとえば 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 フラグは 1 回のコマンドに対して同じことを行います。
LOGISTIVO_HOME — 設定ファイルとカタログキャッシュのディレクトリ。デフォルトは ~/.logistivo です。1 台のマシンで 2 つのアカウントを使う場合は分けてください。
LOGISTIVO_PROFILE — どのプロファイルで実行するか。`lg profile use` は永続的な選択で、この変数は 1 回の実行用です。CI で本番プロファイルとサンドボックスプロファイルを切り替える最短の方法です。存在しないプロファイル名は黙って無視されず、エラーになります。
NO_COLOR — 設定すると ANSI カラーが出力されなくなります(`--no-color` フラグの恒久版)。ログファイルや CI 出力に書き込むブリッジでは有効にしてください。カラーのエスケープシーケンスは、後でそのログを読むツールを壊します。
クライアントの使い勝手
これらの機能は `lg` クライアントの日常的な利用を楽にします。どれも HTTP コントラクトを変更しないため、HTTP で直接連携する場合はこのセクションを読み飛ばしてかまいません。
複数の環境とキー — ステージングと本番、あるいは荷主用ブリッジと運送会社用ブリッジを、別々のプロファイルに分けて保持します。プロファイル一覧がトークンを表示することはなく、各行にはトークンの sha256 フィンガープリントが表示されます。コマンドカタログはプロファイル・ホスト・トークンごとにキャッシュされるため、2 つのロールが互いのコマンド一覧を見ることはありません。
増分同期:lg sync — クックブックの同期ループを 1 つのコマンドで実行します。エンティティごとのウォーターマーク、cursor 付きの updated_since、JSONL 出力、5 分間の安全マージンを備えています。最初のバックフィルには --full を使います。このコマンドは読み取り専用で、--write フラグはありません。lg sync --list は、自分のロールで同期可能なエンティティをカタログから導出します。
エラー時の体験とシェル補完 — 422 のとき、クライアントは拒否されたフィールドを、入力したフラグの名前で示し、安定した error_key とカタログ自身によるその説明を表示します。409 のときは --yes を付けたそのまま使えるコマンドラインを表示し、429 のときは Retry-After の間待機します。シェル補完はドメイン、動詞、フラグ、enum 値をカバーし、オフラインでも動作します。
シークレットパラメータは決してコマンドラインに書かない — いくつかのコマンドはシークレットを受け取ります。たとえば Paraşüt 会計連携の接続には、そのシステムのクライアント認証情報とパスワードが必要です。lg はこのような値をフラグとしては決して受け付けません。シェル履歴や ps の出力に残ってしまうからです。エコーなしで入力を求めるか、---file=PATH または標準入力(---file=-)から読み取り、メモリ上にのみ保持します。必須パラメータがシークレットであるコマンドは lg からしか実行できません。チャット、MCP、または lg batch の中から呼び出すと SECRET_REQUIRES_CLI で拒否されます。監査台帳には値が常に *** として記録されます。
API キーで接続する
ERP、CRM、スクリプト、AI エージェントは、パネルまたは lg keys create で発行した連携キーで Logistivo に接続します。キーは実在するチームメンバーの代理として動作します。その人のロールがコマンド一覧を決め、キーのアクセスレベルが作業の重さを決め、その人がチームを去るとキーも一緒に無効になります。合成の「サービスアカウント」は存在せず、今後も作りません。マルチテナントの分離はユーザーに結びついており、持ち主のいないブリッジこそ、何年も黙って書き込み続けるものだからです。
1. パネルでキーを発行する — Settings › Integration keys › New key を開きます。名前(例:「ERP 夜間同期」)を付け、スコープとアクセスレベルを選び、必要に応じて有効期間を短くします。キーはその画面で一度だけ表示され、サーバーには保存されません。紛失した場合は Rotate で新しいキーが発行され、古いキーは即座に無効になります。
2. ターミナルから接続する — lg login --api-key はキーを検証し、ID とスコープを表示し、コマンドカタログをダウンロードします。lg whoami は、どのユーザー、企業、ロール、スコープで実行しているかをサーバーに問い合わせます。lg logout は、承認コードのセッションをサーバー側で終了させるのと同じように、サーバー側でキーも失効させます(パスワードセッションの lg logout だけはそれができません)。
3. または素の HTTP で — キーは Authorization: Bearer ヘッダーで送るアクセストークンで、3 つのコマンドエンドポイントに対して直接使えます。サーバーや 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 で応答します。意図的な例外が 2 つあり、どちらもより細かいゲートで守られています。コマンド実行エンドポイント(書き込みを伴わないコマンドも POST で呼び出されるため、判断はコマンド自身の read_only フラグに基づきます)と、キーが自分自身を失効させる操作(lg logout。読み取り専用のキーでも許可されます)です。スコープ、ドメイン許可、アクセスレベルは 3 つの独立した軸で、すべてを通過しなければなりません。read キーは manager レベルでも書き込めず、employee の write キーはチームを管理できず、loads:write のドメイン許可で管理業務が開放されることはありません。必要な範囲をカバーする、最も権限の小さいメンバーの代理としてキーを発行してください。そもそもどのレコードを見られるかは、ロールが決めます。
read — コマンドカタログと、書き込みを伴わないコマンド(list、search、preview)。書き込みコマンドは確認ゲートの前に 403 forbidden を返すため、読み取り専用のキーが 409 を目にすることすらありません。夜間同期やレポーティングに適した選択です。
write — すべてのコマンド。確認が必要なコマンドは、引き続き 409 で確認を求めます。confirm: true(CLI では --yes)はこれまでとまったく同じように動作します。スコープによって確認ゲートが緩むことはありません。
employee — すべての新しいキーのデフォルトです。日常業務:貨物、輸送依頼、見積もり、運行、車両と車両書類、書類、取引先。管理権限を必要としないすべてのコマンドに加え、車両関連の権限を含みます。それ以上が必要なコマンドは、error_key INSUFFICIENT_KEY_LEVEL と required_key_level: manager を付けて 422 で応答し、対応する REST エンドポイントは同じエラーキーとともに 403 で応答します。ERP の夜間同期、テレマティクスのブリッジ、業務スクリプトに適したレベルです。
manager — キーの代理対象の本人が行えることすべてで、管理業務も含みます:チームメンバーとロール、企業設定、連携キー、銀行口座とその検証、保存済みカード、企業間の関係、アフィリエイトの支払い。manager キーが本人の持たない権限を追加することはありません。チーム管理権限がなければ、manager キーでもチームは管理できません。アクセスレベルの導入前から存在していたキーは manager キーなので、これまでとまったく同じように動作します。
連携ごとに 1 つのキー — CRM と ERP がキーを共有していると、一方を切ればもう一方も切ることになります。ブリッジごとに専用のキーを与えてください。一覧にはいずれにせよ名前で表示されます。
ローテーション — 新しいトークンを発行し、古いトークンを即座に失効させます。残りの有効期間は引き継がれます。漏えいの疑いがあるときや、定期的に実施してください。連携側は、新しいトークンに更新されるまで 401 を受け取ります。
失効 — キーは恒久的に閉じられます。元に戻すことはできないため、必要なら新しいキーを発行してください。キーの代理対象のメンバーがチームから外されたり無効化されたりすると、キーは自動的に無効になります。
有効期間と上限 — デフォルトの有効期間は 180 日です。作成時に短くすることはできますが、延長はできません。1 人のユーザーが持てる有効なキーは最大 10 個です。最終使用日時は一覧で確認でき、一度も使われていないキーはその旨が明示されます。
管理できる人 — 発行、ローテーション、移譲、失効は、チーム管理権限を持つマネージャーが行えます(チームメンバーの追加・削除と同じゲートです)。連携キーで行う場合、そのキーは manager レベルでなければなりません。マネージャーは別のメンバーの代理としてキーを発行できます。ブリッジには、権限を絞った専用のメンバーを推奨します。
最初の 10 分間:パネルから最初の呼び出しまで
連携で最も高くつくのは最初の 10 分間です。以下の 4 つのステップは、その道のりを順に示しています。同じ順序はパネルにもウィザード(Settings › Integration › Setup wizard)として用意されており、ウィザードはここで説明するエンドポイントをそのまま呼び出します。ウィザードを使えない開発者も、このセクションを読めば同じ地点にたどり着けます。
4 つのステップのどれも「送信した」で終わりません。キーが本当に機能しているかはリクエスト台帳が答え、Webhook が本当に届いているかは配信台帳が答えます。どちらもパネルと lg で確認できます。一度も測定されない設定は、動くと信じられているだけの設定です。
1. 何をするかを決める:まずスコープを設定する — キーが何を見られるかを後から決めることはできません。スコープはキーの発行時に選びます。軸は 2 つあります。粗いスコープ(read / write)が答えるのは「書き込んでよいか」だけです。細かいスコープ(ドメイン許可:loads:read、invoices:write)は、どのドメインに触れてよいかを示し、設定した瞬間にキーはフェイルクローズになります。選択しなかったすべてのドメインと、どのドメインにも対応しないすべてのエンドポイントは 403 を返します。パネルのドメイン一覧は手書きの一覧ではなく、自分のロールのライブのコマンドカタログから導出され、各ドメインがいくつのコマンドと REST エンドポイントを開放するかを表示します。コマンドカタログ、「自分は誰か」(current)、「ログアウト」のエンドポイントは、常にスコープの対象外です。キーは常に自分自身を説明し、閉じることができなければならないからです。3 つ目の軸はアクセスレベルです。employee(デフォルト)は日常業務を実行し、manager はチーム・設定・キー・お金に関わる作業も行います。ブリッジが管理業務を行わない限り、employee を選んでください。
2. キーを発行する:トークンは一度だけ表示される — Settings › Integration › New key を開きます。名前(例:「ERP 夜間同期」)を付け、代理で動作するユーザーとアクセスレベルを選び、必要なら有効期間を短くします。生のトークンはそのレスポンスでのみ返されます。サーバーには保存されず、パネルに「もう一度表示」はありません。紛失した場合はローテーションして新しいトークンを取得すれば、古いトークンは即座に無効になります。トークンをバージョン管理、CI ログ、チャット画面に決して置かず、対象システムのシークレットストアに保管してください。
3. 最初の呼び出しを行い、それが「本当に」届いたことを確認する — リクエストは 2 つで十分です。1 つ目は本人確認です(スコープの対象外で、どのキーでも動作します):スコープは想定どおりか、ステータスは有効か、expires_at が近づいていないか。2 つ目は、選んだドメインから実データを読み取ります。これが通れば、ID、スコープ、メールゲート、ネットワーク経路はすべて正しいということです。通らなければ、推測しないでください。キー自身のリクエスト台帳が、どのエンドポイントがどのコードで、どの安定したエラーキー(INSUFFICIENT_SCOPE、IP_NOT_ALLOWED、KEY_ACTOR_BLOCKED …)で拒否されたかを 1 行ずつ示します。パネルではこの台帳は「Recent requests」ウィンドウ、ターミナルでは lg logs です。ウィザードはまさにこの台帳を監視しており、実際に成功した呼び出しを確認するまで、そのステップを緑にしません。
4. Webhook を設定し、何よりも先に署名を検証する — 毎分問い合わせるより、イベントを待つほうが安上がりです。https のアドレスを登録し、関心のあるイベントを選び、購読を自分のキーに紐づけます。キーが失効すれば、配信も止まります。シークレットは作成時に一度だけ表示されます。受信側のエンドポイントは、まず署名を検証しなければなりません。署名対象の文字列は "{t}.{raw body}"、アルゴリズムは HMAC-SHA256 です。タイムスタンプは署名の「中に」含まれているため、署名が有効でも 300 秒より古いリクエストは破棄してください。比較は定数時間で行い、ボディを決して再シリアライズしないでください。JSON をパースして再び出力した瞬間に、署名は一致しなくなります。パネルの「Send test」は本物の署名付き ping を送信し、配信の様子を試行ごとに確認できます。
サンドボックス:本番に触れずに書き込みを練習する
プリフライト(dry_run)は、コマンドが何を「するか」を教えてくれます。しかし、冪等性が本当にリプレイされるか、Webhook が本当に配信されるか、エラー分岐がどう見えるか、クレジットがどこから引かれるかは、「実際の」書き込みでしか確かめられません。そのためにあるのがサンドボックスです。自社を映した独立したテナントで、コードもコマンドカタログも同じですが、本番の台帳には決して触れません。
サンドボックスはリクエストのフラグではなく、「テナント」です。自社のために開設される独立した Logistivo 企業で、独自のユーザー、独自のパッケージ、独自のクレジット台帳、独自の Webhook 購読を持ちます。環境はキーの所属企業から「導出」され、呼び出し側が指定することはできません。そのため、誤ったプロファイルを選んでも、リクエストはサーバー側で 403 ENVIRONMENT_MISMATCH となって停止します。「サンドボックスに書き込んだつもりが本番に書き込んでいた」ということは、構造上起こりえません。
窓口は同一です。これは測定済みです。サンドボックスキーで得られるカタログは、本番キーで得られるものと同じです(荷主のキーでは、どちらも 646 個のコマンド)。サンドボックスで動くブリッジは本番でも動きます。学んだことを二度学び直す必要はありません。
サンドボックスは空の状態では開設されません。生成された(コピーでは「ない」)シードデータが入っています:取引先、両方向の貨物、輸送依頼です。名前は明らかに架空のもので、メールアドレスは @sandbox.invalid ドメインにあります。実在するテナントの行が読み取られたり、複製されたり、テンプレートとして使われたりすることは決してありません。
リセットボタンは意図的に「ありません」。レコード、ファイル、書類が削除されることも一切ありません。まっさらな状態から始めたい場合は、更新によって新しい世代が開設され、古い世代は引退した状態で残ります。蓄積された数百行のリハーサルデータのコストは、誤ったテナントにつながった削除処理に比べれば無に等しいものです。
1. サンドボックスを開設する — サンドボックスは企業ごとに 1 つです。このエンドポイントにはチーム管理権限(team.manage)が必要なため、自社の管理者が行います。すでに存在する場合は、同じエンドポイントが GET でその状態を返します:企業 id、残りのクレジット、有効なキーの数、購読、世代の履歴、各種上限。
2. サンドボックスキーを発行し、2 つ目のプロファイルとして保持する — キーはサンドボックス専用のブリッジユーザーの代理として発行され、environment: sandbox の印が付いて返ります。生のトークンが表示されるのはその 1 回のレスポンスだけです。lg 側では本番キーを置き換えず、「両方」を別々のプロファイルとして保持してください。--sandbox と --live は 1 回の実行ごとの選択子です。
3. 実際に書き込む — ここでは --dry-run は使いません。書き込むことこそが目的です。同じ冪等キーを 2 回送り、2 回目のレスポンスが status: replayed で返ってくるのを確認してください。これがサンドボックスで測定された結果です。ゲート付きのコマンドをあえて確認なしで呼び出して 409 のボディを読み、スコープ外のコマンドを試して拒否の内容を読んでください。どれも本番の台帳には痕跡を残しません。同じ実行の間、本番の残高は変わりません。
4. 本番移行の前にチェックリストを読む — go-live エンドポイントは、サンドボックスで「実際に」行ったことに基づいて答えます:書き込んだか、エラー分岐を確認したか、Webhook が配信されたか、受信側をリハーサル用のアドレスから移したか、キーに有効期限を設定したか。各項目は pass / todo / unknown で返ります。同じレスポンスには、実際に呼び出したコマンドから導出された「スコープの提案」も含まれます。これを使って、本番キーを必要以上に広くせずに発行してください。
クレジットと請求 — サンドボックスは独自のクレジット台帳を持ち、本番の残高は動きません。これはチェックではなく構造です。クレジットは企業ごとに数えられ、サンドボックスは別の企業だからです。無料プランで開設され、支払い方法を持たず、月次の請求サイクルの外にあるため、どの経路からも請求書に至ることはありません。
マーケットプレイス — サンドボックスで作成した輸送依頼は、実在の運送会社の画面に表示され「ず」、メールやプッシュの受信箱にも届き「ません」。また、あなたにも実在の輸送依頼は表示されません。この分離は対称的で、2 つの別々のクエリで強制されます。輸送依頼が誰に「見える」かと、誰に「送られる」かは、別の問いだからです。
Webhook — 購読にも環境の印が付きます。サンドボックスのイベントが本番の購読に配信されることはなく、本番のイベントがサンドボックスの購読に届くこともありません。印がずれてしまった購読には、配信が一切作成されません。購読の上限は企業ごとなので、リハーサル用の購読が本番の枠を食うことはありません。
シードデータ — サンドボックス内のサンプルレコードは「生成された」もので、実在のテナントからコピーされることはありません。シードの投入は冪等です。2 回目の呼び出しで、自分のレコードの上に 2 回目のシードが重ねられることはありません。
同じカタログ — サンドボックスでもロールは同じで、コマンド一覧も同一です。測定の結果、どちらも 646 個のコマンドです。サンドボックスは機能を削ったデモではなく、自社の双子です。
現時点の制限:サンドボックスキーでは Webhook の購読を管理できない — 購読のエンドポイントにはチーム管理権限(team.manage)が必要ですが、サンドボックスのブリッジユーザーはチームロールを持たないため、`lg --sandbox webhooks …` は現時点では 403 を返します。コマンドの窓口はすべて動作し、制限は購読の台帳にのみあります。サンドボックスで Webhook をリハーサルしたい場合はサポートにお問い合わせください。これは測定済みで、未解決の課題として記録されています。
GET /api/common/integration-sandbox — 状態:存在するかどうか、どの企業か、残りのクレジット、有効なキーと購読の数、世代の履歴、各種上限、そしてどのコマンドがどのイベントを発生させるかを示すトリガーガイド。
POST /api/common/integration-sandbox — サンドボックスを開設します(企業ごとに 1 つ、冪等)。team.manage 権限が必要です。
POST /api/common/integration-sandbox/keys — 201 + キーと生のトークン(ここでのみ、一度だけ)。environment: sandbox の印は企業から導出され、呼び出し側が指定することはできません。
GET /api/common/integration-sandbox/go-live — 本番移行チェックリストとスコープの提案。サンドボックスでの実際のトラフィックから算出されます。
POST /api/common/integration-sandbox/renew — サンドボックスの新しい「世代」を開設し、前の世代を引退させます。
コマンドモデル
文法は 1 つだけで、例外はありません。コマンドの呼び出し方を知るために必要なのは、カタログがそのコマンドについて述べている内容だけです。
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、同期モード(cursor または updated_since 使用時)では最大 100 です。
--json — 生の JSON 出力。
--json — 生の JSON を出力します。スクリプトにとって正しい形式はこれだけです。デフォルトの整形済みテーブルは人間向けで、列をデータから選び、予告なくレイアウトが変わることがあります。テーブル出力をパースするスクリプトは決して書かないでください。
--yes, -y — 確認ゲートを通過します(HTTP では confirm: true)。これから何をするのかを把握しているスクリプトでのみ使ってください。取り消せないコマンドでは、このフラグは「元に戻せない」の略記です。
--idempotency-key= — 書き込みコマンドの再試行を安全にします。同じキーでの 2 回目の呼び出しはコマンドを再実行せず、最初の結果を返します。再試行ループを組む場合は、キーを「自分で」生成し、毎回同じキーを送ってください。
--dry-run — コマンドの代わりにプリフライトを実行します。バリデーション、各ゲート、クレジット計算は実行されますが、何も書き込まれません(プリフライトのセクションを参照)。すべてのコマンドと lg batch で有効です。
--refresh — カタログの再取得を強制します。lg はカタログを 1 時間キャッシュします。サーバーでコマンドが追加されたばかりだとわかっている場合は、待たずにこれを使ってください。
--help, -h — コマンドのカタログ上の説明、すべてのパラメータ、その型、enum 値、必須かどうかを表示します。クライアント内にヘルプファイルはありません。
--profile=, --sandbox, --live — この 1 回の呼び出しをどのプロファイルで実行するか。--sandbox と --live は、サンドボックスキーまたは本番キーを持つプロファイルを選びます。環境はサーバー側でキーから導出されるため、不一致の場合は誤った場所に書き込むのではなく 403 ENVIRONMENT_MISMATCH で停止します。
--base-url, --timeout, --verbose, --no-color, --version — それぞれ、1 回のコマンドを別のサーバーに向ける、秒単位のタイムアウト、リクエスト/レスポンスの詳細表示、ANSI カラーの無効化、クライアントのバージョン表示です。
実際の例
以下のコマンドはすべて現在のカタログに存在し、ここにある名前やパラメータに作り話は一切ありません。出力は省略しています。出力は `data.result` の階層を示しています。HTTP では同じオブジェクトが `{success, data:{…}}` エンベロープに包まれて届きます(「HTTP コマンド API」を参照)。
現在輸送中の貨物 — lg loads list --status=in_transport --limit=20
1 件の貨物の全情報(生の 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 は便利な道具であって、入口そのものではありません。カタログと実行はどちらも 3 つの HTTP エンドポイントを通ります(ファイルには 4 つ目としてアップロード用エンドポイントがあります。「ファイルを受け取るコマンド」を参照)。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、自分のカタログロール、attachments(アップロード)コントラクト、呼び出しに使っているキーのアクセスレベルがあります。ETag を送信し、If-None-Match には 304 で応答します。?domain= は古い(エイリアスの)ドメインにも一致します。クライアントはここから組み立て、コマンド一覧をハードコードしないでください。
GET /api/common/commands/{name} — 1 つのコマンドの全情報。name はカタログ上の凍結されたコマンド名(list_loads)であり、CLI 上の識別子ではありません。非推奨のコマンドは X-Deprecated ヘッダー付きで応答します。
POST /api/common/commands/{name} — 実行。ボディ:{ args, confirm?, idempotency_key? }。レスポンスの HTTP ステータスが結果そのものです。200 以外はノイズではなく情報です。エラーには error_code(トランスポート)が付き、業務上の拒否の場合は error_key も付きます。
ファイルを受け取るコマンド
表のうち 38 個のコマンドが書類や写真を受け取ります:貨物に CMR を添付する、請求書から HS コードを読み取る、車検証から車両を作成する、写真からパレットを推定する、企業書類をアップロードする、請求書をパッキングリストと照合する、などです。ブラウザではファイルをフォームにドロップしますが、それ以外の場所では 2 つのステップが必要です。ファイルをアップロードし、その id をコマンドに渡します。
名前が attachment_uuid または attachment_uuids で終わるパラメータはファイルを受け取ります。リスト内なら photos[].attachment_uuid、小切手なら front_attachment_uuid です。これを覚えておく必要はありません。カタログの各行には正確なパスを含む file_params があり、スキーマはそれらのフィールドに印を付け(format: uuid、x-logistivo-file: true)、カタログのレスポンスにはアップロード先、受け付ける形式、サイズ上限、有効期間を含む attachments ブロックがあります。lg help でも表示されます。
アップロードは書き込みなので、read スコープのキーではアップロードできません。write スコープのキーなら、どちらのアクセスレベルでもアップロードできます。アップロードしたファイルはキーではなくユーザーに属します。同じユーザーの 2 つのキーは同じアップロードを参照でき、他人のアップロードは誰も使えません。未知の id、期限切れの id、自分のものではない id は単に「見つからない」とされ、その理由は開示されません。
ダッシュボードのチャットの添付ファイルとコマンドのアップロードは別々の領域です。アシスタントチャットで添付したファイルを id でコマンドに渡すことはできず、コマンドのアップロードがチャットのスレッドに現れることもありません。
アップロードはコマンドではなく、それ自体に業務上の効果はありません。コマンドがその id を使うまで、データには何も起こりません。アップロードで確認が求められないのもそのためです。ゲートを持つのは、ファイルを消費するコマンドのほうです。
1. lg:ローカルパスの前に @ を付ける — lg はまずファイルをアップロードし、返された id でコマンドを実行します。@ のない値は、以前にアップロードしたファイルの id です。リストにはカンマ区切りのパスか、フラグの繰り返しを指定し、ネストしたフィールドには JSON を指定します。コマンドにトップレベルのファイルフィールドがちょうど 1 つしかない場合は、--file が近道になります。lg は何かを送信する前に各ファイルをローカルで検証し(存在、サイズ、形式)、lg batch はバッチの実行前に、重複しない各ファイルを 1 回ずつアップロードします。
2. HTTP:アップロードしてから attachment_uuid を渡す — ファイルを multipart/form-data として、file という名前のフィールドで送ります。新しいアップロードには 201 が返ります。同じユーザーが同じファイルを再度アップロードすると、status replayed と同じ id とともに 200 が返り、何も書き込まれません。このページの他の箇所と同様、例はエンベロープ内の data オブジェクトを示しています。
3. MCP:upload_attachment ツール — MCP クライアントは multipart を送信できないため、チャネルはカタログにない追加のツールを 1 つ提供しています。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 MB、その他のファイルは最大 15 MB です。
有効期間 — アップロードは 24 時間利用できます。それを過ぎると解決されなくなります(ATTACHMENT_NOT_FOUND)が、削除はされません。その理由でコマンドが失敗した場合は、再度アップロードしてください。
同じファイルなら同じ id — 同じファイル(名前、サイズ、内容が同じ)を再度アップロードすると、残りの有効期間が 1 時間以上ある限り、新しく書き込む代わりに既存の id が返り、1 日あたりの上限も消費しません。
1 日あたりの上限 — ユーザーごとに 1 日 300 件のアップロード(TOO_MANY_FILES)、企業ごとに 1 日 2 GB(DAILY_LIMIT_REACHED)。どちらも retry_after 付きで 429 を返します。
POST /api/common/commands:upload — file フィールドでの multipart アップロード。新しいアップロードには 201、同じファイルには status replayed とともに 200 を返します。data.attachment を返します:attachment_uuid、filename、mime_type、size_bytes、sha256、extraction_status、expires_at、reused。
確認ゲートと取り消せないコマンド
カタログのすべてのコマンドは 2 つのフラグを持ちます。confirmation_needed(実行前に明示的な承認が必要か)と irreversible(その効果を元に戻せるか)です。これらは別々の問いであり、どちらもクライアントの行儀の良さに任せるのではなく、サーバー側で強制されます。
このゲートは業務ルールではなく、責任のためのものです。見積もりを提出することは運送契約への第一歩であり、請求書を発行すれば会計仕訳が生まれ、在庫移動は台帳を変えます。どれも、うっかり 2 回実行できてしまってよいものではありません。
ゲートは「実際に実行される」コマンドから読み取られます。チャットの汎用実行コマンドのように、あるコマンドが別のコマンドをラップする場合、ゲートはラッパーではなく、実際に実行されるコマンドのフラグから決まります。フラグが固定されていたら、2 つの失敗のどちらかが避けられません。請求書コマンドが確認なしで実行されるか、国を検索するたびに確認カードが表示されるかです。
read_only と「ゲートなし」は同じではありません。3 つの異なる状態があります。invoices preview はゲートがなく、何も書き込みません。loads create はゲート付きで、書き込みます。invoices create はゲートがないものの書き込みます(下書きが生まれます)。判断基準は 1 つです。コマンドが戻ったとき、データベースの行が変わっているかどうかです。
一部の操作は、そもそもコマンドではないため、このゲートの対象外です。パッケージの購入、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 を付けて繰り返します(CLI では --yes)。取り消せないコマンドには、最大 1 回しか実行されないよう印が付けられています。
プリフライト:書き込みコマンドを実行せずに、何が起きるかを確認する
ERP ブリッジの組み込みで最も高くつくのは、リクエストボディが正しいかどうかを、コマンドを「実際に」実行して確かめることです。本番の台帳に下書きの請求書が残り、クレジットが消費され、手作業での後始末が必要になります。dry_run はそれを終わらせます。リクエストにフィールドを 1 つ追加するだけで、コマンドは実行されず、何が起きるかを読み取れます。
レジストリには現在 721 個のコマンドがあり、そのうち 327 個は読み取りのみで何も書き込みません。残りの 394 個の書き込みコマンドのうち 346 個はゲート付きで、confirm なしで呼び出すとすでに 409 を返し、何をするかを説明します。抜け穴は残りの 48 個でした。請求書の下書き、輸出書類の下書き、明細行といった、まさにブリッジが最初に組み込む一連の処理です。これらは、呼び出すことがそのまま実行することでした。
ゲート付きのコマンドにも 2 つ目の抜け穴がありました。スキーマバリデーションはゲートの「後」に実行されます。そのため、引数が欠けた呼び出しはまず確認カードを受け取り、確認し、その後でようやく「このフィールドがありません」と知らされていました。プリフライトは 1 回の往復で両方に答えます。
そして、最もよくあり、かつ最も発見が遅れるブリッジのバグはこれです。スキーマにないフィールドを送る(recipient_contact_id が期待される箇所に customer_id を送る)と、サーバーはそれを黙って捨て、コマンドは 200 を返し、レコードは誤った場所に作られます。プリフライトのレスポンスは、そうしたフィールドを arguments.ignored の下に名前付きで列挙します。エラーメッセージがそれを教えてくれることは決してありません。
プリフライトは何も書き込みません。これは測定結果である以前に、構造上の性質です。プリフライトの経路はコマンドのハンドラーに決して入らないため、後から追加されるものも含め、すべてのコマンドに当てはまります。リリース時には測定も行いました。当時カタログにあったすべての書き込みコマンドをプリフライトした際(2 種類の引数セット、2 つのロール、178 回のプリフライト)に発行されたすべての SQL ステートメントを記録しました。INSERT/UPDATE/DELETE は 1 つもなく、キューに入ったジョブも、メールも 1 通もありませんでした。31 テーブルの行数とクレジット残高も変わりませんでした。
終了コードは実際の呼び出しが返すものと同じです(実行可能なら 0、確認ゲートなら 4、冪等性の衝突なら 2、それ以外は 1)。そのため "lg … --dry-run || exit" は CI ステップで意味のあるゲートになります。
1. dry_run 付きで呼び出す — リクエストボディに "dry_run": true を追加します。バリデーション、ロールとスコープのゲート、対象の解決、クレジット計算はすべて実行されますが、コマンド自体は実行されません。
2. would_execute を読む — 分岐に使うフラグはこれ 1 つです。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 はレート制限です。
read スコープのキーでは書き込みコマンドをプリフライトできない — 403 が返ります。プリフライトが答えるのは「今、このキーで呼び出したら何が起きるか」です。read キーに青信号を出しておいて実際の呼び出しで 403 を返すことは、まさにプリフライトが防ぐために存在する不意打ちです。
冪等キーは消費されない — プリフライト中に送ったキーは台帳の行を作らず、期限切れのロックも解放されません。ですから、本番で使うつもりのキーを送ってください。プリフライトは、そのキーがまだ空いているか、以前の実行をリプレイすることになるか、別のコマンドと衝突するかを教えてくれます。
confirm と組み合わせられる — dry_run と confirm を一緒に送ると、問いは「確認したら何が起きるか」になります。それでも何も実行されません。
バッチのプリフライトはバッチ単位 — commands:batch も dry_run を受け付けますが、このフラグは個々の項目ではなくバッチに属します(項目に付けて送ると 422 になります)。項目ごとのレポートに加えて、バッチ全体のクレジットコストが返ります。残高不足は拒否されるのではなく、報告されます。
無料ではない — プリフライトは毎回実際のクエリ(プレビュー、残高)を実行し、レート制限にカウントされます。デプロイのたびにカタログ全体をプリフライトするのではなく、変更したコマンドだけをプリフライトしてください。
冪等性:再試行しても重複が生まれない理由
ERP はエラーメッセージを読まず、画面も見ず、タイムアウトの後には同じリクエストを再送します。このセクションはまさにその振る舞いのためにあります。
idempotency_key を付けた呼び出しは最大 1 回しか実行されません。2 回目の呼び出しはコマンドを再実行せず、記録された結果を status replayed で返します。ネットワークが切れたとき、リクエストがタイムアウトしたとき、キューが同じジョブを 2 回拾ったときも、重複した請求書ではなく最初の結果が返ります。
すべての書き込みコマンドでキーを使ってください。カタログの read_only フィールドが、その区別を労せず教えてくれます。read_only: false のコマンドにはすべて冪等キーを付けるべきです。
再試行戦略では指数バックオフを使い、毎回「同じ」キーを送ってください。試行ごとに新しいキーを生成するのは、冪等性をまったく使わないのと同じです。同じキーを並列に送らないでください。at-most-once(最大 1 回)が保証されるのは順次の再試行に対してであり、互いに競合する 2 つのリクエストに対してではありません。
落とし穴 1:失敗もロックされる — 最初の実行が業務ルールによって拒否された場合(failed)、同じキーでの 2 回目の呼び出しは同じエラーと同じ error_key を返し、再試行はしません。引数を直してもう一度試すには「新しい」キーが必要です。キーが表すのは意図ではなく、1 回の試行です。
落とし穴 2:大きな結果はボディなしでリプレイされる — 台帳が結果を保存するのは 64 KB 未満の場合だけです。それより大きな結果は status replayed でリプレイされますが、ボディは空です。連携側はボディではなく「replayed」というシグナルに頼り、対応する get コマンドでデータを取得してください。
落とし穴 3:キーは 1 つのコマンドに属する — 同じキーを別のコマンドで送ると、conflicting_command とともに 409 idempotency_conflict が返ります。何も実行されず、何もリプレイされません。1 つのキーを 2 つの動詞で共有するクライアントは壊れており、そのことを黙ったリプレイではなくエラーで知ることになります。
落とし穴 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)は、2 つの共通パラメータを受け付け、1 つの共通フィールドを返します。
offset がない理由:稼働中のテーブルでは offset がずれます。2 つのページの間に挿入された行のせいで、レコードを黙って読み飛ばしたり二重に数えたりします。カーソルは前進のみなので、走査の途中で挿入・更新されたレコードは一覧の末尾に来ます。何も失われず、何も重複しません。
最初の全件取得も同じ仕組みです。updated_since=1970-01-01T00:00:00Z から始め、next_cursor が null になるまでたどります。必要がないため、別の「エクスポート」エンドポイントはありません。
lg でも同じことができます:lg loads list --updated_since=2026-09-01T00:00:00Z --limit=100 --json を実行し、続いて lg loads list --cursor= --json を実行します。
次回の同期では、updated_since に、これまでに見た最大の updated_at を設定します。タイムスタンプの精度は 1 秒なので、境界上のレコードが 2 回届くことがありますが、自分の側で external_ref または code をキーに upsert していれば無害です。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=... のいずれも動作します。list と search のコマンドでは、--external_ref= は完全一致のフィルターです。
企業ごとに一意 — 同じキーを持つ 2 件目のレコードは 422 で拒否され、result.error_key = DUPLICATE_EXTERNAL_REF となります。別の企業のキーに対しては「見つかりません」と応答します。照合は大文字・小文字を区別しません(ord-1 = ORD-1)。アーカイブされたレコードはキーを保持し続けるため、キーを再利用する前にそのレコードを復元してください。
idempotency_key も送る — ネットワークのタイムアウト後に再試行しても、重複を作らずに最初の結果が返ります。この 2 つは互いの代わりにはなりません。external_ref はあなたの業務キーであり、idempotency_key は 1 回の試行を識別します。
送信 Webhook:何かが起きたら、こちらからあなたへ POST します
ここまでの内容はすべてプル方式でした。あなたが尋ね、こちらが答えます。ERP ブリッジは、貨物のステータスが変わった、請求書が発行された、見積もりが届いたといったことを知るために、1 分ごとに問い合わせる必要がありました。今は違います。https のアドレスを登録し、関心のあるイベントを選べば、それが起きたときに署名付きの POST が届きます。
プッシュはプルの代わりではなく、プルの「隣に」追加されました。増分同期(updated_since + cursor)には手を加えておらず、今も正しい手段です。最初の全件取得、履歴のバックフィル、「何か見落としていないか」の確認は、すべてそちらで行います。Webhook は遅延を数分から数秒に短縮します。健全なブリッジは両方を使います。Webhook をトリガーとして、同期をセーフティネットとして。
ペイロードはレコードのコピーではなく「シグナル」です。識別子(id、あなた自身の external_ref、status、時刻)を運びます。詳細は自分のキーを使って GET で取得し、その呼び出しはすでにあなた自身の認可ゲートを通過します。そのため、露出面は識別子のレベルにとどまります。2 つのフィールドは意図的に含めていません。見積もりを出した企業の身元(ブラインド見積もりはパネルでは別名で表示されます。Webhook に身元を入れると、2 つ目の経路からそのプライバシーを破ることになります)と、予約の連絡先情報(個人データを余計な経路で動かす必要はありません)です。
イベント名は「凍結」されています。名前の意味が変わる場合は新しい名前が作られ、古い名前は非推奨期間のあいだ存続します。ペイロードに新しいフィールドを追加しても、コントラクトバージョンは上がり「ません」。受信側は知らないフィールドを無視しなければなりません。
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} — 購読を削除します。行はソフトデリートされ(履歴は引き続き照会可能)、保留中の配信はキャンセルされます。
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 — 1 件の配信を再送します。event_id は「保持」され、配信 id は新しくなり、ペイロードはそのままコピーされます。
イベントカタログ
以下の 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 プレフィックスによって方式をバージョン管理できます。将来 2 つ目の方式が加わった場合、ヘッダーは t=…,v1=…,v2=… となり、知っている方式を選べばよいのです。
依存関係のないリファレンス受信側を 2 つ公開しています。1 つは Node 用、もう 1 つは素の PHP 用です。どちらも上記の 4 つのルールを適用し、--selftest で自己テストします:有効な署名、改ざんされたボディ、誤ったシークレット、許容幅外のタイムスタンプ、不正な形式のヘッダー、再シリアライズの落とし穴、そして 2 種類の繰り返し(同じ配信/同じ事実)です。検証ロジックは、私たち自身が使っているコードとまったく同じものです。私たちは自ら公開するコントラクトを自分でも使っています。
「生の」ボディを検証する — 署名はバイト列に対して計算されます。ボディをデコードして再シリアライズすると(JSON.stringify(req.body)、json_encode($request->all()))、同じ「データ」が異なる「バイト列」になり、署名が一致しなくなります。Node での落とし穴は数値の書式(通信上の 1.50 が 1.5 になる、大きな整数の精度が失われる)、PHP では文字のエスケープ(/ が \/ に、İ が \u0130 になる)です。Express では express.raw を、Laravel では $request->getContent() を使ってください。これは受信側を書くときに最もよくある間違いです。
タイムスタンプを確認する — t は署名の「中に」含まれています。署名だけを検証すると、有効なリクエストを傍受した誰もが数時間後にそれをリプレイでき、受信側はそれを検証済みのイベントとして扱ってしまいます。署名が正しくても、|now − t| > tolerance となるリクエストは破棄してください。推奨される許容幅は 300 秒です。
定数時間で比較する — hash_equals / timingSafeEqual を使います。== で比較すると、攻撃者が署名を 1 バイトずつ推測できてしまいます。
重複排除は id ではなく event_id で行う — event_id は「事実」を識別します。同じイベントを受け取る 2 つの購読者で同じ値になり、リプレイ時にも「保持」されます。id(= X-Logistivo-Delivery)は「配信」を識別し、リプレイ時に変わります。「これはもう処理したか」の判断には event_id を使ってください。id で判断すると、リプレイで同じ処理が 2 回実行されてしまいます。
配信、再試行、ミュート
受信側が常に稼働しているとは限りません。この仕組みはそれを前提としています。一時的な失敗は再試行スケジュールに入り、恒久的な失敗は購読をミュートします。そしてミュートの「理由」は必ず記録されます。
ミュートの理由は機械可読で安定しており(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 も含め、「すべて」再試行されます。業務イベントを失う損失は、数回の余分なリクエストよりも大きいのです。4xx を恒久的な失敗として扱う仕組みでは、WAF ルールの更新中に 403 を返した受信側は「請求書発行」イベントを黙って失ってしまいます。
Retry-After — 429 と 503 で尊重されます(上限 6 時間)。
リダイレクト — 追従「しません」。302 で内部アドレスに飛ばされると、別の経路からアドレスゲートを破られてしまうからです。
自動ミュート — 再試行を使い切った配信が 10 回連続した後にミュートされます。410、安全でない宛先、紐づいた連携キーの失効の場合は「即座に」ミュートされます。
https のみ、ポートは 443/8443 のみ、埋め込まれた認証情報 (https://user:pass@…) は拒否。
localhost、単一ラベルの名前、.internal / .local / .svc などの内部向けサフィックスは拒否。名前解決の結果を見る前に意図そのものを拒否するため、スプリットホライズン DNS でゲートを破ることはできません。
IP リテラルと DNS 解決の「すべての」レコードがパブリックでなければなりません。ある名前がパブリックとプライベートの両方のアドレスに解決される場合、どちらを選ぶかを誰かがこちらに尋ねてくれるわけではありません → その名前はそのまま拒否されます。
配信時にはアドレスを 1 回だけ解決し、接続を検証済みのアドレスに固定します。これにより DNS リバインディングの隙は閉じられています。
受信側のレスポンスの「ボディ」はどこにも保存されません(保存するのはステータスコード、所要時間、短いエラータグのみ)。そのため、アドレスゲートの穴が実際に持つ価値である「読み取り」経路は閉じたままです。
「プライベートアドレスを許可する」設定スイッチは意図的に「ありません」。そのようなスイッチは、いつか誤ってオンのまま放置されるものだからです。
購読の作成時と rotate-secret の実行時にだけ、「一度だけ」返されます。サーバー上では暗号化して保存され、読み戻すことはできません。「もう一度表示」はありません。
lg はそれを画面に表示するだけで、設定ファイルにもキャッシュファイルにも書き込みません。
紛失した場合はローテーションします。古い値は「その時点で」使えなくなります。途切れなく切り替えるには、移行期間中は受信側で両方のシークレットを試すようにしてください。
アドレスを変更してもシークレットには影響「しません」。「URL が移った」といった日常的なメンテナンスで、受信側の検証が壊れてはならないからです。
ヘルスとステータス:沈黙したブリッジに、あなたより先に誰かが気づくことがないように
連携ブリッジが派手に停止することはめったにありません。たいていは深夜に静かに止まります。トークンの期限が切れる、キーの代理対象の人がチームを離れる、スコープが狭められる、受信側のエンドポイントが 403 を返し始める。最初に気づくのは、ほとんどの場合顧客です。lg status はその順序を逆転させるためにあります。
1 つのコマンドが 2 つの問いに同時に答えます。障害時にはどちらも同じ瞬間に問われるからです。プラットフォームは稼働しているか、そして自分のブリッジは健全か。プラットフォームの行はトークンなしで動作します。障害時にはトークンそのものが最初の容疑者であり、ステータスの問いをトークンに結びつけてしまうと、答えが最も必要なときに答えが得られなくなるからです。
ヘルスサマリーは新しい台帳を持たず、既存の 3 つの情報源を 1 つの文にまとめます:日次の利用カウンター(どれだけ呼び出し、どれだけ失敗したか)、リクエスト台帳(どのリクエストが、いつ、なぜ拒否されたか)、送信 Webhook の配信台帳(イベントが受信側に届いたか)。エラー率は常に日次カウンターから読み取ります。詳細台帳には上限があり、上限に達した場合はその旨をはっきりと示します。
同じサマリーはパネルにも表示されます。Settings › Integration › Keys の下で、各行にバッジが付き、その下に理由が表示されます。しきい値はクライアント側では計算しません。サーバーが割り当てたレベルを、パネルと lg status の両方がそのまま表示するため、2 つの画面が同じキーについて異なることを言うことはありません。
監視ツールにトークンは不要です。このエンドポイントが返すのはステータスを表す単語だけで、バージョン、ホスト名、キュー名、ジョブ数、エラーテキスト、顧客データは含まれません。含めることもできません。
ヘルスサマリーは、リクエストごとに一定数のクエリで生成されます。クエリ数はキーの数に応じて増えません。詳細は、そのキーの最近のリクエストを lg logs で、送信側のブリッジを lg webhooks list で確認してください。
正常 — 測定された障害がなく、成功の証拠があります。台帳に成功した呼び出しがある、またはカウンター上でエラーのないトラフィックが続いている状態です。
要注意 — 何かが壊れ始めています。エラー率または連続失敗回数がしきい値を超えた、リクエストがゲートで拒否されている、キーの有効期限が近い、または定期的に通信していたブリッジが沈黙した、のいずれかです。
障害中 — ブリッジは現在動作していません。トークンが意図せず失効した、クローズ済みのキーがまだ呼び出されている、5 回連続で失敗している、エラー率が 50% を超えている、または Webhook の購読がミュートされた、のいずれかです。
クローズ済み — キーが意図的にクローズされ、誰も呼び出していません。これは障害ではなく判断であり、赤では表示されません。
データなし — 測定値がありません。キーが一度も呼び出されていないか、測定そのものに失敗しています。どちらも緑ではありません。
偽の緑はありません。正常バッジには、測定された成功の証拠が必要です。一度も呼び出されていないキーが緑になることはありません。動作することを示す測定値が 1 つもないからです。
偽の赤もありません。意図的にクローズしたキーは「クローズ済み」と表示されます。何でも赤にすると赤の意味がなくなります。クローズ済みのキーが赤になるのは、クローズ後もまだ呼び出されている場合だけです。そのときは本当にブリッジが壊れています。
「測定できなかった」は「データなし」と同じではありません。サーバー側でクエリが失敗した場合、その行は黙ってゼロを表示するのではなく、測定できなかったことを示します。
沈黙は常に報告されますが、機械的に警告に変えられることはありません。月末にだけ動くブリッジが 30 時間沈黙するのは正常です。直近 7 日のうち少なくとも 5 日通信していたブリッジが沈黙するのは障害です。リズムは推測ではなく測定されます。
ステータスの照会そのものがヘルスの数値を汚すことはありません。lg status による呼び出しはリクエスト台帳には記録されますが、ヘルスの計算からは除外されます。そうしなければ、自分自身のステータス照会の成功が連続失敗回数をリセットし、この画面が示すために存在する障害そのものを隠してしまいます。
すべての行が測定に基づきます。データベースに対して実際にクエリを実行し、コマンドカタログを実際に構築し、キューワーカーのライブ記録を実際に読み取ります。推測は一切ありません。
レスポンスそのものも測定です。ボディを読めるなら、Web 層は稼働しています。
トップレベルの値は必須コンポーネントだけから導出されます。キューが止まった場合の答えは down ではなく degraded です。同期的な API 呼び出しにキューは不要であり、プラットフォームを down と宣言すれば誤報になるからです。
キューの状態を測定できない場合、トップレベルの値はそのままにします。「わからない」ことは「壊れていると測定した」ことと同じではありません。
プラットフォームが停止している場合、エンドポイントは HTTP 503 を返します。ボディはエンベロープを持たないため、監視ツールはパースせずにアラートを出せます。また、レスポンスがキャッシュに保存されることはありません。
エラーと終了コード
機械が分岐に使うのは安定した文字列です。error フィールドのテキストは人間向けで、ローカライズされ、予告なく変わります。メッセージのテキストで分岐する連携はサポート対象外であり、それが壊れてもバグではありません。
2 つの分類、2 つのフィールドがあります。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 は待機して最大 3 回再試行し、その後終了コード 5 で終了します。
5xx server_error / ネットワークエラー — 指数バックオフで、「同じ」冪等キーを使って再試行します。キーを変えると、サーバーがすでに完了しているかもしれない処理が再実行されます。lg は 3 回(1 秒、2 秒、4 秒)再試行し、その後 error_code network_error または server_error とともに終了コード 6 で終了します。
安定性の約束
連携コントラクトで最も重い問いは「今日書いたコードは明日も動くか」です。それに答えるのが 1 つの数値、つまりカタログ内の contract_version と、すべてのレスポンスに付く X-Contract-Version ヘッダーです。この数値が答えるのはただ 1 つの問い、「以前に書いたコードが変更なしで今も動くか」です。数値が増えていなければ、動きます。増えていれば、動きません。あなたが依存していた何かが削除されたか、狭められたのです。
告知は何も削除しないからです。告知の翌日も、既存のコードはまったく以前どおりに動きます。告知でバージョンを上げると、1 つの変更に対して 2 つのシグナルを出すことになり、最初のシグナルを無視する癖をつけさせてしまいます。それは本当に重要なシグナルを弱めます。告知は、あなたが行っている呼び出しにすでに乗っています。カタログの行の deprecated_at と replaced_by、そのコマンドのレスポンスに付く X-Deprecated ヘッダーと deprecated ブロック、そして lg を使っていれば stderr への 1 行の警告です。何かが廃止予定であることを知るために、何かをする必要はありません。それはすでにあなたのログにあります。
告知から削除までには、少なくとも暦の上で 2 四半期が経過します。猶予期間中、古いコマンドは引き続き応答し、呼び出しのたびに警告します。CLI 名が廃止される場合は、後継のコマンドがその名前をエイリアスとして引き継ぎます。猶予期間中は古い名前で古いコマンドに届き、削除された日からは同じ呼び出しが新しいコマンドに届きます。クライアントの新しいリリースを出す必要はありません。
preview_invoice → get_invoice(2026 年 9 月 3 日に告知)。get_invoice は同じ preview ブロックを返し、さらに明細行、税の内訳、記録済みの入金、残高、自社 ERP キー(external_ref)による指定を追加します。preview_invoice は引き続き動作し、lg invoices preview も同様です。どちらも警告を出します。
変更なし — 新しいコマンド · 新しい「任意」パラメータ · 新しいレスポンスフィールド · 新しいエラーキー · 新しいエンドポイント — 何もする必要はありません。知らないフィールドは無視しなければなりません。未知のフィールドで失敗するパーサーは仕様に準拠していません。
変更なし — 非推奨の「告知」:コマンドが廃止予定であるという通知 — コードは動き続けます。カレンダーにタスクを入れておいてください。猶予期間は最低 6 か月です。
上がる — コマンドの削除 · 古い CLI 名の廃止 · レスポンスフィールドの削除 · 任意パラメータの必須化 · enum の縮小 — 猶予期間を逃したということです。通知は 3 つの別々の場所であなたに届いていました。
コマンドの 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 を実行してください。アフィリエイト専用のコマンドはここには掲載していません。アフィリエイトアカウントでは自分のカタログで確認できます。
貨物と追跡 — 貨物の作成、関係者、書類、追跡リンク、受領署名、到着予定時刻と例外。 115 件のコマンド — /ja/developers/cli/loads
国境と通関 — 国境通過の準備チェック、国境・港湾の待ち時間、輸出書類、U-ETDS 届出。 42 件のコマンド — /ja/developers/cli/border
依頼と見積 — 輸送依頼の作成、見積の依頼と提出、入札、ネットワーク内の運送会社。 42 件のコマンド — /ja/developers/cli/quotes
運賃表と販売見積 — 契約運賃表、オファーの段階送信、顧客向け販売見積。 57 件のコマンド — /ja/developers/cli/pricing
車両とドライバー — ドライバー、車両、経費レシート、ドライバー精算、運行計画とシェンゲン日数。 115 件のコマンド — /ja/developers/cli/fleet
倉庫と在庫 — 倉庫、予約、バース予約、ゲート画面、製品、在庫とパレット。 69 件のコマンド — /ja/developers/cli/warehouse
会計と請求 — 請求書、仕入請求書の監査、Paraşüt、仕訳、入金と支払い、利益率。 95 件のコマンド — /ja/developers/cli/finance
メッセージとメール — 貨物チャット、ダイレクトメッセージ、メールの下書きと受信箱、通知。 58 件のコマンド — /ja/developers/cli/messages
関税と貿易措置 — HS コード検索、輸入税、アンチダンピング措置、炭素レポート。 20 件のコマンド — /ja/developers/cli/tariffs
会社とチーム — 会社名簿、取引関係と書類、子会社、チームメンバーと招待。 65 件のコマンド — /ja/developers/cli/contacts
自動化とレポート — 自動化ルール、カスタムレポート、Excel・PDF ファイル、作業計画。 27 件のコマンド — /ja/developers/cli/automation
アカウントと連携 — アカウントと言語の設定、連携キー、パッケージ、クレジットとウォレット。 16 件のコマンド — /ja/developers/cli/account
ERP・CRM 連携 — 認証主体:サービスアカウントではなく、実在のユーザー
ERP や CRM は、パネルで発行したパーソナルアクセストークンを持つ、実在する企業ユーザーとして Logistivo に接続します。企業に属さず、スコープの制約を受けず、誰も責任を負わない合成のサービスアカウントが作られることは決してありません。
これは好みではなく、アーキテクチャの問題です。マルチテナントの分離は、すべてユーザーの所属企業に依存しています。企業を持たない主体では分離スコープが機能しなくなり、そのトークンでの誤ったクエリ 1 つで、自分のものではないデータを読めてしまいます。2 つ目の理由は監査です。台帳のユーザー列は「誰がこれを実行したか」を人に結びつけますが、サービスアカウントはその列を無意味にし、請求書を発行する連携から責任者をなくしてしまいます。3 つ目は失効です。トークンが人に属していれば、その人が去ったときに連携は止まります。持ち主のいないブリッジこそ、何年も黙って書き込み続けるブリッジなのです。
実際には、企業はパネルで通常のユーザー(たとえば、特定の従業員が責任を持つ「ERP Bridge」)を作成し、狭いロールを与え、そのユーザーのセッションでトークンを発行して ERP に設定します。
そのユーザーは権限システムで確認でき、権限を絞ることができ、そのトークンだけを個別に失効させることもできます。禁止されているのはアカウントの作成ではなく、テナントに紐づかないアカウントの作成です。
トークン 1 つにつき連携 1 つ。2 つのシステムがトークンを共有すると、失効の粒度が失われます。CRM を切り離すと、ERP も切り離すことになります。
ERP・CRM 連携 — バージョニングと非推奨化
カタログのレスポンスには整数の contract_version が含まれ、コマンドの各行には since、deprecated_at、replaced_by が含まれます。コントラクトバージョンが上がるのは、互換性を壊す変更のときだけです。
バージョンが上がら「ない」もの:新しいコマンド、新しい任意パラメータ、レスポンスの新しいフィールド。利用側は知らないフィールドを無視しなければなりません。未知のフィールドでエラーになるクライアントは仕様に準拠していません。
バージョンが「上がる」もの:コマンドの削除または名前変更、レスポンスフィールドの削除、任意パラメータの必須化、enum の縮小。古い形式は deprecated_at と replaced_by を伴って、少なくとも暦の上で 2 四半期(6 か月)存続します。
非推奨化は変更履歴だけでなく、カタログで告知されます。クライアントはカタログから自身を組み立てるため、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 連携 — 安定した識別子:自動採番 id を ERP にキーとして渡さない
内部の自動採番 id は不透明で、テナントにスコープされています。別の企業の有効な id を指定しても、データではなく「見つかりません」が返ります。しかし、不透明であることは業務キーであることを意味しません。ERP が自分のレコードに保存するものは、業務キーでなければなりません。
貨物:code(顧客コード、例:FSK2158)。loads get はすでに code で動作します。
国:ISO 3166-1 alpha-2。countries search がそのコードを返します。
HS/関税率:コードそのもの。品目分類はすでに国際的に共通です。
請求書:発行後の請求書番号。下書きには画面上の id しかなく、下書きの id は業務キーでは「ありません」。ERP は自社の参照番号を持ち、下書きの id を決して永続化しないでください。
製品、倉庫、取引先:現在は画面上の id のみです。新しいコマンドのルールは明確です。画面上の id を返すコマンドは、ERP 側で照合できるよう、テナント自身の業務キー(SKU、コード、税番号)も返します。
ERP・CRM 連携 — ページネーション、フィルタリング、増分同期
一覧コマンドは limit を受け取り、count を返します。夜間同期のために、コントラクトは以下を約束しています。これを採用した一覧コマンドは JSON Schema で cursor と updated_since を公開します。そうなるまでは、小さなウィンドウとして扱ってください(上限 20 行、カーソルなし)。
リクエスト:limit(1 からコマンドごとの上限まで)と cursor(不透明、前進のみ、サーバーによる署名付き)。offset は使い「ません」。稼働中のテーブルでは offset がずれます。2 つのページの間に挿入されたレコードのせいで、ERP は行を読み飛ばしたり二重に数えたりし、しかもそれは黙って起こります。
レスポンス:{ count, total?, next_cursor|null }。count はこのレスポンスの行数で、next_cursor が null なら一覧は完結しています。next_cursor は変更せずにそのまま返してください。これはページ番号ではなく、あなたが組み立てるものでもありません。
改ざんされたカーソルや他者のカーソルは 422 invalid_request で拒否されます。カーソルはそれを受け取った企業に紐づいており、別テナントのデータをページングすることはできません。
フィルタリング:JSON Schema の名前付きパラメータを AND で組み合わせます。自由なクエリ言語はありません。DSL があれば、守らなければならない 2 つ目のクエリの窓口になってしまうからです。
増分同期:updated_since(ISO-8601、UTC)とカーソル。これまでに見た最新の updated_at を保存し、次回の実行時に渡してください。これがなければ、どの ERP も毎時すべてを再取得することになります。
外部参照:書き込みコマンドは external_ref(自社の伝票キー)を受け付け、これは企業ごとに一意です。同じ external_ref で 2 回目の作成を行うと、重複して作られるのではなく拒否されます。list/get はこれを返すため、自分の側でレコードを照合できます。
ERP・CRM 連携 — レート制限
制限のキーは IP ではなくトークンです。ERP は単一の NAT の背後からアクセスしてくるため、IP ベースの制限では企業全体が 1 人のユーザーとして数えられてしまいます。2 つのキーを持つ 2 つの連携が、互いの割り当てを食い合うことはありません。これが「キー 1 つにつき連携 1 つ」の 2 つ目の理由です。
認証不要のディスカバリー(public/cli/catalog):毎分 30 回。これは辞書であってデータソースではありません。ブリッジを書くときに一度読むだけにし、本番のループの中では決して読まないでください。
カタログエンドポイント(GET common/commands、GET common/commands/{name}):トークンごとに毎分 120 回。カタログはめったに変わらず、If-None-Match には 304 で応答します。コマンドのたびに再取得しないでください。lg はカタログを 1 時間キャッシュします。
読み取りコマンド(read_only: true の POST common/commands/{name}):トークンごとに毎分 120 回。
書き込みコマンド(read_only: false の POST common/commands/{name}。未知の名前もここに数えられます):トークンごとに毎分 30 回。書き込みには副作用があり、暴走したループには課金が発生します。
クレジットを消費するコマンド(カタログ行の credit_cost がゼロでないもの。たとえば tariffs inquiry や export-documents generate):実際の制限はリクエスト数ではなく「クレジット」です。200 のレスポンスでもクレジットを消費している場合があります。
企業ごとの 1 日あたりの上限(パネルと共有):社外の人にメールやプッシュを送るコマンドは 1 日 300 件の外部通知枠を、有料のコンテナ追跡や船舶追跡の開始は 1 日 100 件の枠を消費します。上限を超えると、コマンドは retry_after 付きで DAILY_LIMIT_REACHED を返します。ファイルアップロードには独自の上限があります(「ファイルを受け取るコマンド」を参照)。
429 には常に Retry-After と、ボディ { error_code: "rate_limited", retry_after, limit, bucket } が付きます。固定の待ち時間を自分で決めるのではなく、これに従ってください。カタログは現在の数値を rate_limits の下で公開しています。
ERP・CRM 連携 — 私たちがやらないこと
これはしばしば、コントラクトの中で最も役に立つ部分です。決して実現しないものがわかっていれば、それを前提に設計できます。
サービスアカウントも、テナントに紐づかない主体も作りません。
API やチャットを通じて決済、カード番号、法的同意を扱うことはありません。これらのステップは本人のブラウザに残り、コマンドはそのリンクを渡します。
2 つ目の経路はありません。データベースへの直接アクセスも、シェルアクセスも、単一の適用ポイントを迂回する一括エンドポイントもありません。ロールゲート、確認ゲート、冪等性、監査台帳は、そこでのみ適用されます。
エラーメッセージのテキストによる分岐はサポートしません。テキストはローカライズされ、予告なく変わります。
offset によるページネーションはありません。
画面上の id を ERP の業務キーとして使うことはサポートしません。
送信 Webhook をこのコントラクトに押し込むことはしません。ただし、Webhook は現在「存在し」、このページ(上の Webhook のセクション)で説明しています。カタログはプル型の窓口であり、イベントストリームは「別の」コントラクトです。イベント名とペイロードのスキーマは独自のルールでバージョン管理され、コマンドカタログのコントラクトバージョンには結びついていません。
機械可読なカタログ
このページは人間向けに書かれています。AI アシスタントや自動化されたクライアント向けには、同じ情報が、構造化された認証不要のコピーとして存在します。
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 を AI アシスタントに接続するのは別のチャネルで、専用のページがあります:
カタログは認証不要ですが、実行はそうではありません。エージェントの名義でコマンドを実行する方法はありません。実行されるのは常にユーザー自身の ID です。
Logistivo のパスワード、認証コード、アクセストークンがチャットを通ることは決してありません。それらを求めたり、生成したり、中継したりするフローを作らないでください。
コマンドが取り消せないかどうかはカタログに書かれています。irreversible: true のコマンドで「試してみましょう」と提案しないでください。
credit_cost がゼロでないコマンド(たとえば tariffs inquiry や export-documents generate)は金銭的な結果を伴います。自動化されたループの中で呼び出さないでください。
決済、カード番号、法的同意がチャットやエージェントを通ることは決してありません。代わりに handoff-links generate のリンクを提示し、本人が自分のブラウザでステップを完了します。
ユーザーのキーで動作するエージェントは、最初に users get を呼び出すべきです。ロール、キーのアクセスレベル、実効権限、そして保留中の同意や電話番号認証が書き込みを妨げていないかを返します。拒否を集めるのではなく、予測してください。
このページのプレーンテキスト版は /cli.md にあります。HTML よりも markdown のほうが確実にパースできる場合はこちらを使ってください。
機械可読な定義:OpenAPI 3.1 と Postman
上のカタログは Logistivo 独自の形式です。同じ情報は、お使いのツールがすでに理解できる 2 つの業界標準形式でも公開しています:OpenAPI 3.1 の定義と Postman コレクションです。どちらも手書きではなく、リクエストのたびにライブのコマンドレジストリから生成されるため、古くなることはありません。
定義はカタログ「そのもの」であり、2 つ目の現実ではありません。すべてのコマンドは POST /api/common/commands/ オペレーションとして現れます。ボディのスキーマはそのコマンド自身の JSON Schema(アシスタントが見るものとバイト単位で同一)、レスポンスのスキーマは共通のエンベロープで、ゲートフラグ(read_only、confirmation_needed、irreversible とクレジットバッジ)は x-logistivo 拡張に、業務エラーキーは x-error-keys の下にあります。廃止予定のコマンドには deprecated: true が付き、6 か月の猶予期間中は呼び出し可能なままです。
コマンドの窓口に加えて、連携コントラクトを担う REST エンドポイントも定義に含まれています:増分同期(updated_since + cursor + limit)に対応した 10 個の一覧エンドポイントと、自社のキー(external_ref)を受け付ける 7 個の書き込みエンドポイントです。Logistivo の REST の窓口はそれよりはるかに大きいのですが、残りは「意図的に」除外しています。それらのペイロードは製品自身のコントラクトであり、推測で書いたスキーマは、生成したクライアントを最初の呼び出しで壊してしまいます。そしてあなたは、こちらではなく自分のコードの中にバグを探すことになるでしょう。
定義は、要求した人の「ロール」に合わせて生成されます。別のロールのコマンドがドキュメントに入ることはありません。定義は辞書ではなくコントラクトであり、その中のすべてがそのトークンで呼び出せなければならないからです。認証不要版は 3 つのロールの和集合で、そこでは各オペレーションがどのロールに表示されるかを 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 — 認証不要版で、3 つのロールの和集合です。トークンを入手する前に、ブリッジを設計し、コストを見積もるためのものです。
GET /api/public/cli/postman.json — 認証不要の Postman コレクション。チームにそのまま渡せる 1 つのファイルです。
761 個のオペレーション — 721 個のコマンド + 36 個の REST およびコントロールプレーンのオペレーション + 4 個のカタログ・ID エンドポイント。このページの数値は手入力ではなく、リクエストのたびにライブのドキュメントから数えられています。そのため、コマンドがリリースされた日にはここの数値も増え、合計も一致します。
セキュリティスキーム — bearerAuth:実在するユーザーに対して発行された Passport トークン。read スコープのキーが呼び出せるのは、x-logistivo.read_only: true のフラグが付いたオペレーションだけです。書き込みを試みると確認ゲートの「前に」 403 が返るため、読み取り専用のキーが 409 を目にすることはありません。
すべてのエラー分岐が明記されている — 各オペレーションは 401/403/404/409/422/429/500 を個別に記述しています。409 の 2 つの意味(確認が必要/冪等性の衝突)と 422 の 2 つの意味(スキーマエラー/業務上の拒否)はドキュメント内で区別されているため、ジェネレーターがそれらを 1 つの分岐にまとめてしまうことはありません。
タイムスタンプなし — ドキュメントには生成時刻が含まれません。同じカタログからは同じバイト列が生成されるため、ETag が実際に機能し、バージョン管理にコミットした定義がダウンロードのたびに「変更あり」に見えることもありません。
製品のペイロードをでっち上げていない — REST の書き込みエンドポイントでは、コントラクトのフィールド(external_ref)だけを記述しています。ボディの残りは additionalProperties: true として開いたままにし、読み手には製品ドキュメントを案内しています。不完全でも正しい定義は、完全でもでっち上げた定義に勝ります。
オペレーションごとのエラーキー一覧は網羅的では「ない」 — x-error-keys には、コマンド自身のレコードから確実に導かれるキーだけを列挙し、x-error-keys-exhaustive: false でそのことを明示しています。完全な辞書はドキュメントのルートにあります。認識できないキーは一般的な失敗として扱ってください。でっち上げた「完全な一覧」があれば、default 分岐を書かないように仕向けてしまったでしょう。
ディスカバリー用ツールは定義に含まれない — search_commands、run_command、list_capabilities はチャットのループ内にのみ存在し、HTTP では呼び出せません。もし含めていたら、ジェネレーターは決して動かない 3 つのメソッドを書いていたでしょう。
コード生成:定義から型付きクライアントを
定義は手に入りました。次はそこから動作するコードを生成しましょう。`lg codegen` は OpenAPI ドキュメントを読み込み、依存関係のない単一ファイルのクライアントを書き出します。TypeScript(型宣言と薄い呼び出しラッパー)または PHP(PHPDoc の array shape を備えたクライアントクラス)です。`npm install` も composer も不要です。TypeScript 側は `fetch`、PHP 側は `ext-curl` を使います。
生成はこちらのサーバーではなく、「あなたの」マシンで行われます。これは好みの問題ではありません。定義を一度リポジトリに固定すれば(`lg spec --out=...`)、同じコマンドがビルドのたびにネットワークもトークンもなしで実行されるため、CI がこちらの稼働状況に依存することはありません。さらに、生成されたコードはあなたの ERP の中で「動く」コードなので、API から取得するのではなくリポジトリに置いておけば、すべての変更が `git diff` に現れます。
生成されたクライアントは Logistivo の 3 つの経路(レール)をすべて正しく扱い、どれがどれかを推測ではなくドキュメントから知ります。すべてのオペレーションは `x-logistivo.surface` で自身の経路を宣言しています。コマンドの経路では `{success, data:{…}}` エンベロープを取り外します。REST の同期一覧はエンベロープに包まれて「おらず」、そのまま返されます(取り外すと `next_cursor` が失われます)。REST の書き込みは、そのエンドポイント自身の製品ボディを返します。汎用のジェネレーターはこの区別を知りませんが、私たちのジェネレーターは知っています。
型は推測ではありません。各コマンドの引数インターフェースは、アシスタントが見るのとまったく同じ JSON Schema から生成されます。必須は必須のまま、enum はユニオン型に、ネストしたオブジェクトはネストした型になります。実際には、サーバーが必須とするフィールドを書き忘れた呼び出しは、本番環境で 422 で失敗するのではなく、コンパイル時に失敗します。
ファイルには生成時刻を書き込みません。同じ定義と同じフラグからは同じバイト列が生成されます。そのため再生成しても `git diff` にノイズは出ず、本当に変わったただ 1 つのもの、つまりコントラクトが見えるままになります。
1. 定義を固定する — 定義は自分のロール向けに生成され、その中のすべてのオペレーションはそのトークンで呼び出せます。ファイルをコミットしてください。 lg login --api-key= lg spec --out=logistivo-openapi.json
2. クライアントを生成する — 1 つのファイルが出力され、固定した定義内の「すべての」オペレーションがメソッドとして含まれます:自分のロールで呼び出せるコマンド、連携コントラクトを担う REST エンドポイント、そしてディスカバリー用エンドポイントです。数はプラットフォーム全体ではなく「あなたの」ロールのものです。現在、荷主のキーでは 646 個、運送会社では 621 個、通関業者では 392 個のコマンドメソッドが生成されます。認証不要の公開定義から生成した場合、上限は 761 個のオペレーションです。 lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # or straight from the server, without downloading first: lg codegen ts --out=logistivo-client.ts
3. 検証してから使う — 生成されたコードがコンパイルできない場合、その責任はあなたではなく私たちにあります。定義の整合性は、サーバー上で実行可能なチェックによって守られています。 npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
オペレーションごとに 1 つのメソッド — ドキュメント内のすべてのコマンド、連携コントラクトを担うすべての REST エンドポイント、そしてディスカバリー用エンドポイントです。自分のロールの定義から生成すれば、呼び出せるものだけが得られます(荷主なら 646 個のコマンド)。公開定義から生成すれば、761 個のオペレーションすべてが得られます。サーバーでコマンドが追加された日に再生成すれば、それも取り込まれます。クライアントのリリースを待つ必要はありません。
引数の型 — 各コマンドの `args` スキーマはインターフェース(PHP では array shape)になります。必須フィールドは必須のまま、enum はユニオン型になります。TypeScript では必須フィールドの書き忘れはコンパイルエラーになり、PHP では IDE と PHPStan が同じ形を認識します。
エラークラス — トランスポートの分類(`error_code`)と業務の分類(`error_key`)は別々のフィールドで、確認ゲートとレート制限は別々のエラー型です。エラーキーのユニオン型は未知の値にも開かれているため、サーバーが新しいキーを宣言してもコードがコンパイルできなくなることはなく、`default` 分岐に入ります。
正しい再試行ポリシー — 自動再試行は安全な呼び出し、つまり読み取りと、冪等キーを付けた書き込みにのみ適用されます。キーのない書き込みがタイムアウトしても「何も書き込まれなかった」とは限らないため、クライアントがそれを闇雲に繰り返すことはありません。429 の場合は、待ち時間を自分で決めるのではなく、サーバーの `Retry-After` に従って待機します。
結果のボディには型を付けていない — コマンドの結果は `unknown`(PHP では `mixed`)として返ります。理由は定義そのものと同じで、結果の形はコマンドの業務上の出力であり、コントラクトの一部ではないからです。推測した結果型は、フィールドが初めて移動した時点で嘘をつき始めるでしょう。
生成されたファイルは手で編集しない — それはソースではなく出力です。追加の振る舞いが必要なら、生成されたクラスをラップしてください。その中に書いたものは、次の生成で失われます。
ディスカバリー用ツールは生成されない — `search_commands`、`run_command`、`list_capabilities` はチャットのループ内にのみ存在し、HTTP では呼び出せません。定義に含まれていないため、クライアントにも含まれません。含めていたら、決して動かない 3 つのメソッドを書くことになっていたでしょう。
正直な適用範囲
このセクションは縮めるよりも、むしろ増やしていきたいと考えています。連携コントラクトの価値は、何を約束するかよりも、何を約束しないかをどれだけ明確に述べるかにあります。
CLI はテナントユーザーのコンテキストで動作する — すべてのコマンドは、提示されたトークンのユーザーの企業とロールのもとで実行されます。プラットフォーム運営者モード(企業をまたいで読み取る管理モード)はこの窓口の範囲外であり、ここから開放されることはありません。
コマンド一覧はロールによって異なる — 荷主アカウントには 646 個、運送会社には 621 個、通関業者には 392 個、アフィリエイトには 55 個のコマンドが表示されます。カタログにコマンドが見当たらない場合は、まずロールを確認してください。掲載されているのに拒否される場合は、キーのスコープとアクセスレベルを確認してください。ドライバーアカウントは、この窓口に一切アクセスできません。
クレジットを消費するコマンドがある — 関税率の照会、書類の生成、その他いくつかの AI を利用するコマンドは、プランのクレジット残高を消費します。カタログの各行には credit_cost {mode, credits} が含まれます。fixed は 1 回の呼び出しごとの正確な消費量、read_only は消費なし、computed は消費量が呼び出し内容によって決まることを意味します。その場合 credits は null となり、実際の数値は確認カードに表示されます。プリフライト(dry_run)で、1 回の呼び出しでどれだけ消費するか、残高で足りるかを確認できます。
連携キーではダッシュボードのチャットを操作できない — ダッシュボード内の AI アシスタントは人間のためのものです。連携キーでアシスタントの実行を開始または継続しようとすると、403 で拒否されます。エージェントはコマンドエンドポイント、lg、または MCP チャネルを使います。そこではすべてのコマンドがキーのアクセスレベルで実行され、その書き込みは連携による書き込みとして記録されます。
カタログは既存の REST API を置き換えない — Logistivo の Web アプリとモバイルアプリを支える REST の窓口はそのまま残り、引き続き後方互換性のルールのもとにあります。コマンドカタログはリソースの CRUD を置き換えるものではなく、「動詞」の層、つまり何かを行うための唯一の監査された方法です。
一覧コマンドは現在、小さなウィンドウを返す — 一覧コマンドがスキーマで cursor と updated_since を公開するまでは、上限は 20 行で、カーソルはありません。データの完全なコピーを取り出すための設計ではありません。増分同期はコマンドごとに順次展開中です。
よくある質問
Logistivo CLI は何に使うのですか?
Logistivo アカウントの業務を、ターミナル、スクリプト、または自社の AI エージェントから実行します:貨物と運行、輸送依頼、見積もりと入札、車両、ドライバーとその経費、書類、取引先と取引先元帳、請求書と会計、倉庫と在庫、チームメンバー、HS 関税率とアンチダンピング関税。パネルのすべての書き込み操作にコマンドがあり、決済、法的同意、アカウントの閉鎖は意図的にブラウザに残しています。同じコマンドは、ERP/CRM 連携のために HTTP で、また MCP チャネルからも呼び出せます。
Logistivo CLI のコマンドはどのように命名されていますか?
形は lg --parameter=value です。ドメインは複数形のエンティティ(loads、demands、invoices、export-documents)で、動詞は意図的な判断によってのみ増える閉じた語彙(list、get、create、update、search、set-status、generate など)から選ばれます。1 つのエンティティの動詞はすべて 1 つのドメインにあり、(domain, verb)の組はカタログ全体で一意です。
CLI ではどのように認証しますか?
対話的に使う場合は、lg login が承認コードを表示し、Logistivo にサインインしたあと、ブラウザでそのコードを確認して承認します。ターミナルにパスワードやキーを入力することはなく、セッションは lg logout を実行するまでサインインしたまま維持され、自動で更新されます。lg login --password(メールアドレスとパスワード)は代替手段として引き続き使えます。サーバーや CI では、パネルまたは lg keys create で発行した連携キーを使います。lg login --api-key でローカルのプロファイルに保存するか、LOGISTIVO_TOKEN 環境変数に設定してください。HTTP では、トークンは Authorization: Bearer ヘッダーで送られます。
ERP 連携用にサービスアカウントを作成できますか?
いいえ。連携は、パネルで作成した実在の企業ユーザーのトークンで接続します。企業を持たない合成の主体は、マルチテナントの分離を機能させなくし、監査台帳の「誰がこれを実行したか」の列を無意味にし、持ち主が去っても止まらないブリッジを残してしまいます。正しいパターンは、狭いロールと責任者が明確な専用ユーザーです。
Logistivo にはテスト(サンドボックス)環境がありますか?
はい。セルフサービスで利用できます。自社用に独立したサンドボックステナントが開設されます。コードもコマンドカタログも同じで、クレジット台帳は独自のものです。環境はキーの所属企業から導出され、リクエストで指定することはできません。誤ったプロファイルで行った呼び出しは、サーバー側で 403 ENVIRONMENT_MISMATCH となって停止します。サンドボックスで作成した輸送依頼が実在の運送会社に届くことはなく、サンドボックスのイベントが本番の Webhook 購読に配信されることもなく、本番の残高も動きません。エンドポイント:POST /api/common/integration-sandbox (開設)、POST /api/common/integration-sandbox/keys (キー)、GET /api/common/integration-sandbox/go-live (本番移行チェックリスト)。lg 側では、lg --sandbox と lg --live が 1 回の実行ごとのプロファイル選択子です。
スクリプトで 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 で、そのボディは意図的にエンベロープを持ちません。
同じリクエストを 2 回送ると、レコードが重複しますか?
idempotency_key を送っていれば重複しません。同じキーでの 2 回目の呼び出しはコマンドを再実行せず、最初の結果を status replayed で返します。キーは UUID にすべきで、再試行の間は「同じ」でなければなりません。試行ごとに新しいキーを生成するのは、冪等性を使わないのと同じです。
--yes は何をしますか?
確認ゲートを通過させます。ゲート付きのコマンドを --yes なしで呼び出しても何も変わりません。サーバーはこれから行う内容を 1 文で要約し、取り消せないかどうかを伝えて停止します(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 パラメータを返します。コマンド一覧をハードコードせず、これらからクライアントを組み立ててください。
新しいコマンドが追加されたら、クライアントを更新する必要がありますか?
いいえ。クライアントはコマンド一覧をカタログから取得するため、サーバーで追加されたコマンドは、クライアントの新しいリリースなしに現れます。更新が必要なのは、コントラクトバージョンを上げる互換性のない変更の場合だけで、その場合も古い形式は少なくとも 6 か月間存続します。
CLI は既存の REST API を置き換えますか?
いいえ。Web アプリとモバイルアプリを支える REST の窓口はそのまま残ります。コマンドカタログはリソースの CRUD を置き換えるものではなく、「動詞」の層、つまりロールゲートと確認ゲートを備え、監査される、操作を実行するための唯一の方法です。
Logistivo の API キーはどうやって取得し、何ができますか?
チーム管理権限を持つマネージャーが、パネルの Settings › Integration keys で、またはターミナルから lg keys create で発行します。キーは実在するチームメンバーの代理として動作し、3 つの独立した設定を持ちます:スコープ(read はカタログと書き込みを伴わないコマンドを、write はすべてのコマンドを開放します。確認ゲートはそのまま残ります)、任意のドメイン許可、そしてアクセスレベル(日常業務向けのデフォルトである employee、またはチーム・設定・キー・お金に関わる操作向けの manager)です。キーは一度だけ表示され、サーバーには保存されません。ローテーション、移譲、失効が可能です。代理対象のメンバーが去ると、キーも閉じられます。サービスアカウントはありません。
冪等キーを別のコマンドで再利用するとどうなりますか?
サーバーは 409 idempotency_conflict で応答し、そのキーが最初に使われたコマンドを示します。何も実行されず、何もリプレイされません。キーは自社にスコープされ、1 つのコマンドに紐づき、24 時間ロックされます。その後は、同じキーで新しい実行が始まります。
連携にはどのようにレート制限が適用されますか?
トークンごと、毎分、3 つのバケットで適用されます:カタログの読み取り 120 回、読み取りコマンド 120 回、書き込みコマンド 30 回。429 には常に Retry-After と、retry_after、limit、bucket を含むボディが付きます。その時間だけ待ってから再試行してください。カタログは現在の数値を rate_limits の下で公開しています。
業務上の拒否とトランスポートエラーはどう見分けますか?
まず error_code で分岐します。failed(422)は業務上の拒否で、INSUFFICIENT_CREDITS や NOT_FOUND といった安定した error_key が付きます。server_error(5xx)とネットワークエラーは同じ冪等キーで再試行します。rate_limited(429)は待機してやり過ごします。エラーのテキストで分岐してはいけません。
Logistivo は Webhook を送信しますか?どのイベントについてですか?
はい。https のアドレスを登録し、関心のあるイベントを選ぶと、それが起きたときに署名付きの POST が届きます。現在購読できるイベントは 13 種類です:貨物の作成/ステータス変更/ドライバー割り当て、輸送依頼の作成とステータス変更、見積もりの提出/修正/承認、請求書の下書き/発行/取り消し、倉庫予約の作成/ステータス変更。すべての名前は、実際にディスパッチされるイベントクラスに裏付けられています。告知したのに一度も発火しないものはありません。そのようなイベントは、連携担当者が永遠に待ち続ける、気づかれない失敗だからです。購読は Settings › Integration › Webhooks で、またはターミナルから lg webhooks create で作成します。
Logistivo から届く Webhook の署名は、どのように検証すればよいですか?
すべてのリクエストに X-Logistivo-Signature ヘッダーが付きます:t=,v1=。署名対象の文字列は "."、アルゴリズムは HMAC-SHA256、鍵は購読のシークレットです。ルールは 4 つあります。(1)「生の」バイト列を検証する:ボディをデコードして再シリアライズする(JSON.stringify / json_encode)と、同じデータが異なるバイト列になり、署名が一致しなくなります。これが最もよくある間違いです。(2) タイムスタンプを確認し、署名が正しくても |now − t| > 300 秒のものは破棄する。(3) hash_equals / timingSafeEqual で定数時間比較する。(4) 重複排除は配信 id ではなく event_id で行う:event_id はリプレイ時にも保持されますが、配信 id は変わります。動作する Node と PHP の受信側はリポジトリの examples/webhook-receiver/ にあり、--selftest で自己テストします。
Webhook を配信できなかった場合はどうなりますか?イベントは失われますか?
失われません。受信側が 2xx を返さない場合、配信は再試行スケジュールに入ります:60 · 300 · 1800 · 7200 · 21600 秒、合計 6 回の試行、期間はおよそ 8.6 時間です。410 Gone を除く「すべての」失敗は、4xx も含めて再試行されます。業務イベントを失う損失は、数回の余分なリクエストよりも大きいからです。再試行を使い切った配信が 10 回連続すると購読はミュートされ、その理由が記録されるため、「なぜ何も届かないのか」に答えられる状態が保たれます。配信台帳はすべての試行(ステータスコード、所要時間、エラー)を保持し、パネルまたは lg webhooks replay で 1 件の配信を再送できます。増分同期(updated_since + cursor)も引き続きセーフティネットとして使えます。
自社の AI エージェントは、ユーザーがパネルでできることをすべて行えますか?
ほぼすべて行えます。パネルのすべての書き込み操作にコマンドがあり(パネルの書き込みエンドポイントと照合した結果、対象範囲内のものは 100% カバーされています)、同じコマンドが lg、HTTP、MCP チャネルに開放されています。意図的な例外は、本人確認とお金に関わるステップです。サインイン、パッケージの購入、3D Secure によるカードの追加、法的文書への同意、アカウントの閉鎖は本人のブラウザに残り、lg handoff-links generate がそのためのリンクを返します。連携キー、Webhook、サンドボックスは、シークレットを一度だけ返すため、lg の組み込みコマンドで管理します。
CLI や API から、PDF や写真などのファイルをコマンドに渡せますか?
はい。lg では、ローカルパスの前に @ を付けると (--attachment_uuid=@./cmr.pdf)、lg が先にファイルをアップロードします。コマンドにファイルフィールドが 1 つしかない場合は --file が近道になり、lg upload はアップロードだけを行います。HTTP では、ファイルを multipart で POST /api/common/commands:upload に送り、返された attachment_uuid をコマンドに渡します。MCP クライアントは upload_attachment ツールを使います。ファイル形式は内容から判定され、アップロードしたファイルはユーザーに属し、24 時間利用できます。同じファイルを再度アップロードすると、同じ id が返ります。
employee と manager の連携キーの違いは何ですか?
アクセスレベルは、キーがどれだけ重い作業をしてよいかを決めます。新しいキーのデフォルトである employee キーは、日常業務を実行します:貨物、輸送依頼、見積もり、運行、車両、書類、取引先。manager キーは、管理業務も行えます:チームメンバーとロール、企業設定、連携キー、銀行口座、保存済みカード、アフィリエイトの支払い。キーが代理対象の本人より多くの権限を持つことはなく、employee キーで manager 用のコマンドを呼び出すと INSUFFICIENT_KEY_LEVEL が返ります。レベルはパネルで、または lg keys update --access-level=manager で変更します。
アフィリエイト(紹介パートナー)も CLI を使えますか?
はい。アフィリエイトアカウントには独自のカタログ(紹介、リード、CRM のメモとタスク、営業資料、収益と支払いのための 55 個のコマンド)があり、ほかのロールと同じように lg、HTTP、MCP から利用できます。支払いの申請や取り消し、支払先銀行口座の変更には、manager レベルのキーと確認が必要です。荷主、運送会社、通関業者でもある企業には、両方のカタログが表示されます。
For AI assistants
Logistivo has an MCP server at https://logistivo.com/api/agent/mcp
(streamable HTTP). Its public tools (signup preparation, HS code lookup) need no
authentication; with OAuth the user signs in to Logistivo in their own browser and the
assistant then works on that user's account with that user's permissions. Setup for
Claude, ChatGPT and Gemini: https://logistivo.com/en/mcp .
Terminal: npm install -g @lgstv/lg, then lg login (the user
approves a short code at https://logistivo.com/connect; no password is typed into the
terminal). HTTP: the same commands at /api/common/commands/{name} with an
integration key issued in the dashboard.
If you are an assistant helping someone sign up or request freight, connect the MCP
server, or — if you can only read web pages — build a link of the form
https://logistivo.com/en/ai-kayit?brief=URL_ENCODED_SHIPMENT_BRIEF and give
it to the user. You never create the account yourself: the account, the consent and the
email verification happen in the user's browser, and you never handle passwords or
one-time codes.
Machine-readable content indexes:
https://logistivo.com/llms.txt (curated map) and
https://logistivo.com/llms-full.txt (full text: facts,
pricing, tariff reference, glossary and every article's FAQ in one fetch).
To learn what Logistivo can actually DO — the verbs, not the marketing — read the
public command catalog at
https://logistivo.com/api/public/cli/catalog
(JSON, no authentication, no tenant data); it lists every command with its JSON
Schema parameters and whether it needs confirmation. Human documentation:
https://logistivo.com/en/developers/cli . Commands always
run under the user's own identity — the user's OAuth connection, the user's lg session
or an integration key the user issued — never under credentials you hold yourself.