Logistivo CLI:在终端和 ERP 中运行您的物流业务

同一份命令目录驱动三个入口:lg 终端客户端、面板内的 AI 助手,以及外部 AI 助手所接入的通道。一项能力只需编写一次,就会同时出现在这三处——而且面板中的每一项写操作现在都有对应的命令,因此您的脚本和您自己的 AI 智能体可以完成团队在屏幕上所做的工作。支付、法律同意和账户注销则有意保留在浏览器中。 本页是一份契约。下方的命令表并非手写,而是在每次请求时从实时命令注册表生成。

什么是 Logistivo CLI?

Logistivo CLI(lg)是一个命令行客户端,可以从终端、脚本或您自己的 AI 智能体运行 Logistivo 账户中的各项工作——运单与行程、询价、报价与招标、车队与司机、单证、联系人与往来账户、发票与会计、仓库与库存、团队成员以及海关税则。命令并没有固化在客户端里:客户端从服务器拉取命令目录,并据此生成自身。同样的命令无需安装任何东西即可通过 HTTP 调用——ERP 和 CRM 集成走的正是这条路径——也可以通过外部 AI 助手所接入的 MCP 通道调用。

哪些已经上线,哪些即将推出

本节特意放在页面顶部。集成文档可能犯下的最昂贵的错误,就是把尚未开放的端点描述得好像已经可用:集成方写好了代码,端点却返回 404,信任从此一去不返。

由于契约已经冻结,您今天编写的集成代码在其余部分陆续开放时仍可继续工作。不认识的字段必须忽略;正是这条规则让我们能够新增内容而不破坏现有集成。

与众不同之处:客户端不内置任何命令,而是根据目录生成命令

正是这一个决定,让本页其余内容有了意义。在普通的 CLI 中,命令存在于客户端内部;而在 Logistivo 中,命令存在于服务器上。

在传统的架构中,服务器每获得一项新能力,客户端就需要发布新版本,用户还需要安装它。在此期间,两端所知的内容并不一致——而这正是集成中最隐蔽的故障模式:脚本照常运行,退出码为 0,可命令根本没有反映出服务器能做什么。

在 Logistivo 中,一条命令的定义就是一条记录:它的名称、作用、JSON Schema 参数、哪些角色可以看到它、是否需要确认,以及其效果是否可撤销。lg 启动时会拉取这份目录,并据此生成帮助文本、选项和输入校验。服务器上一旦新增命令,lg 立即就能识别——无需更新客户端。

同一份目录还驱动着面板中的 AI 助手,以及外部 AI 助手所接入的通道。一项能力只编写一次,就会出现在三个地方——而且三者都经过同一个角色关卡、同一个确认关卡和同一份审计台账。不存在单独的 CLI 命令清单;如果有,这三个入口会在六个月之内悄然分道扬镳。

命名规则——命令名称如何扩展

目录会不断增长。新命令不是随意命名的,而是遵循六条规则。我们在这里公布这些规则,因为这些名称将在您的集成中被书写多年,它们的可预测性对您很有价值。

覆盖范围:面板中的一切,都能通过命令完成

许多团队把 Logistivo 接入自己的 AI 智能体或自动化框架,而智能体只有能把工作做完才有用。因此规则很简单:办公室用户能在面板中更改的任何东西,命令也能更改——并且经过同样的角色关卡、同样的确认关卡和同样的审计台账。

这是测量出来的,而不是断言出来的。面板背后的每个写入端点都会与命令注册表进行核对,只有当某条命令将该端点声明为自己的 HTTP 镜像,或调用同一个共享服务时,该端点才算被覆盖。在范围内的写入端点中,100% 已被覆盖,没有一个未经证实。每个被排除的端点都附有书面理由——身份和支付步骤、集成控制平面、司机 App 自身的端点、客户端遥测、没有调用方的废弃副本——其中与集成方相关的端点列在下方。

需要文件的命令也遵循同样的规则:表中有 38 条命令需要单证或照片,它们全部可以通过 lg、HTTP 和 MCP 使用(参见“需要文件的命令”)。

管理工作同样被覆盖,只是需要更高级别的密钥:表中有 87 条命令——团队成员和角色、公司设置、银行账户、已保存的银行卡、集成密钥——需要 manager 级集成密钥。employee 级密钥是默认级别,负责日常运营,调用这些命令时会以 INSUFFICIENT_KEY_LEVEL 被拒绝。

联盟推广(推荐合作方)账户拥有自己的目录:20 个域中的 55 条命令——推荐、潜在客户、CRM 备注与任务、销售演示文稿、收益与提现,外加每个角色都有的账户和团队命令。仅限联盟推广账户的命令不在下方的公开表格中,该表格列出的是三个面板角色;联盟推广账户可以在 GET /api/common/commands 和 lg commands 中看到它们。既是联盟推广账户、又是货主、承运商或报关行的公司,可以看到两套命令。

智能体应从 lg users get(API 名称 get_current_user)开始:它会返回角色、当前所用密钥的访问级别、实际生效的权限,以及当前是否有待处理的法律批准或未验证的手机号码正在阻止写入——这样智能体就能提前预判拒绝,而不是一次次去碰壁。

覆盖范围由一份将命令注册表与面板写入端点进行比较的报告来测量;没有对应命令就新增的面板端点,会在报告中显示为未经证实。如果您发现某个面板操作无法通过命令完成,请向支持团队报告。

安装与身份

lg 是一个单文件、无依赖的 Node 脚本(Node 18+),以 @lgstv/lg 的名称发布在 npm 上。该软件包会安装两个完全相同的命令: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(设置 › 集成密钥 › AI 与 CLI 连接)下将其移除。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 打印单条命令的完整参数列表,包括类型以及哪些参数为必填。这些文本没有一处存在于客户端内部——全部来自目录。请记住,列表取决于您的角色:同一个域的动词对承运商和货主并不相同(例如 loads set-status 仅存在于承运商目录中)。如果缺少某个动词,请先检查您的角色,再检查安装。

切勿将密钥放入版本控制、CI 日志或聊天窗口。如果您是通过批准码或集成密钥登录的,lg logout 也会在服务器上将其结束;在密码会话中(lg login --password),它只删除“本地”副本,并会明确说明这一点。审计台账会保存您的参数,但会将名称中包含 token、password、IBAN、card 或 OTP 的字段,以及命令声明为机密的每一个参数,掩码为 ***。

客户端易用性

这些功能让日常使用 `lg` 客户端更加轻松。它们都不会改变 HTTP 契约——如果您直接通过 HTTP 集成,可以跳过本节。

使用 API 密钥连接

ERP、CRM、脚本或 AI 智能体通过在面板中或使用 lg keys create 签发的集成密钥连接 Logistivo。密钥代表一名真实的团队成员行事:此人的角色决定命令列表,密钥的访问级别决定工作可以有多重,而当此人离开团队时,密钥也随之失效。没有合成的“服务账户”,将来也不会有——多租户隔离绑定在用户身上,而没有主人的桥接程序,正是那种会悄无声息地持续写入多年的桥接程序。

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,只读密钥也允许)。作用域、域授权和访问级别是三条相互独立的轴,必须全部通过:读取密钥即使是 manager 级也无法写入,employee 写入密钥无法管理团队,loads:write 域授权也不会开放管理工作。请代表能满足您需求的、权限最小的成员签发密钥:角色决定了您究竟能看到哪些记录。

最初的十分钟:从面板到您的第一次调用

集成中最昂贵的几分钟,就是最初的十分钟。下面四个步骤按顺序铺开了这条路径;面板中也以向导的形式提供了同样的顺序(Settings › Integration › Setup wizard,即“设置 › 集成 › 设置向导”),而且该向导调用的正是这里描述的端点。无法使用向导的开发者,阅读本节也能到达同一个地方。

这四个步骤没有一个以“我已经发出去了”作为结束。密钥是否真的可用,由请求台账来回答;webhook 是否真的送达,由投递台账来回答。两者在面板和 lg 中都可以查看。一套从未被测量过的配置,只是一套被“相信”能工作的配置。

沙箱:练习写入,不触碰生产环境

预检(dry_run)告诉您一条命令“将会”做什么;但幂等性是否真的会重放、webhook 是否真的会被投递、错误分支是什么样子、点数从哪里扣除,只有在“真实”的写入中才能看到。这正是沙箱的用途:一个镜像您公司的独立租户——相同的代码、相同的命令目录——永远不会触碰您的线上台账。

沙箱不是一个请求标志,而是一个“租户”。它是为您的公司开设的一家独立的 Logistivo 公司:有自己的用户、自己的套餐、自己的点数台账、自己的 webhook 订阅。环境由密钥所属的公司“推导”得出,调用方无法指定,因此即使您选错了配置档,请求也会在服务器端以 403 ENVIRONMENT_MISMATCH 中止。“我以为在往沙箱里写,结果写进了生产环境”在结构上就不可能发生。

接口面完全相同——这是测量过的:沙箱密钥获取的目录与您的线上密钥获取的目录是同一份(对于货主密钥,两边都是 646 条命令)。在沙箱中能工作的桥接程序,在生产环境中也能工作;您学到的任何东西都不必再学第二遍。

沙箱开通时并不是空的:其中包含生成的(而“非”复制的)种子数据——联系人、双向的运单以及询价。名称是公开编造的,电子邮件地址都位于 @sandbox.invalid 域;任何真实租户的数据行都绝不会被读取、克隆或用作模板。

我们有意不提供重置按钮,也绝不会删除任何记录、文件或单证。如果您想重新开始,续期会开启一个新的代,旧的一代则保留下来并退役。积累下来的几百行演练数据不值一提,远比不上一个误接到错误租户上的删除例程所带来的代价。

命令模型

语法只有一种,而且没有例外。要知道如何调用一条命令,您只需要知道目录对它的描述。

lg loads list --status=in_transport --limit=20 --json

选项名称就是 schema 的参数名,并且 lg 接受两种拼写:--load_code 和 --load-code 指向同一个字段(lg help 打印的是 kebab-case 形式)。因此,看到一个选项就能知道它落到哪个 JSON 字段,从 CLI 迁移到 HTTP 时也无需转换名称。不带值的布尔参数表示 true(--only_open);相反的写法是 --no-only_open。值以短横线开头的参数请写成 --flag=value 的形式,否则一个遗漏了值的选项会悄悄把下一个选项吞作自己的值。在需要文件的命令中,请在本地路径前加上 @,例如 --attachment_uuid=@./cmr.pdf ——参见“需要文件的命令”一节。

真实示例

以下每条命令目前都存在于目录中;这里没有任何名称或参数是编造的。输出已作删节。输出展示的是 `data.result` 层级;通过 HTTP 调用时,同一个对象位于 `{success, data:{…}}` 信封之内(参见 HTTP 命令 API)。

不用客户端: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。

需要文件的命令

表中有 38 条命令需要单证或照片:为运单附加 CMR、从发票中读取 HS 编码、根据车辆登记证创建车辆、根据照片估算托盘、上传公司单证、将发票与装箱单进行交叉核对。在浏览器中,您只需把文件拖进表单;在其他任何地方,都需要两个步骤——先上传文件,再把它的 id 传给命令。

当参数名以 attachment_uuid 或 attachment_uuids 结尾时,该参数接受文件——列表中的 photos[].attachment_uuid,支票上的 front_attachment_uuid。您不必记住这些:每个目录行都带有 file_params,其中给出确切的路径;schema 会标记这些字段(format: uuid, x-logistivo-file: true);目录响应中还带有一个 attachments 块,包含上传地址、接受的类型、大小限制和存活时间。lg help 也会显示它们。

上传是一种写入,因此只读作用域的密钥无法上传;任何写入作用域的密钥都可以上传,无论访问级别如何。上传的文件属于用户,而不属于密钥:同一用户的两个密钥看到的是相同的上传文件,任何人都无法使用别人的文件。未知、已过期或不属于您的 id 只会被视为找不到,原因不会被透露。

面板聊天附件和命令上传是两个独立的空间:在助手聊天中附加的文件无法通过 id 传给命令,命令上传的文件也永远不会出现在聊天线程中。

上传不是命令,本身也没有任何业务效果:在某条命令使用这个 id 之前,您的数据不会发生任何变化。这也是上传从不请求确认的原因——由消费该文件的命令来承担关卡。

确认关卡与不可撤销的命令

目录中的每条命令都带有两个标志:confirmation_needed(执行前是否需要明确批准)和 irreversible(其效果能否撤销)。这是两个独立的问题,而且两者都在服务器端强制执行,而不是寄望于客户端的自觉。

这道关卡关乎责任,而不是业务规则。提交报价是迈向运输合同的第一步;开具发票会产生一笔会计分录;库存变动会改变一本台账。这些操作都不应该因为意外而被执行两次。

关卡读取的是“实际生效”的命令。当一条命令包装另一条命令时——比如聊天中的通用执行器——关卡取自真正将要运行的那条命令的标志,而不是包装器的标志。如果使用固定的标志,两种失败中必有一种无法避免:要么开票命令在未经确认的情况下运行,要么每一次国家查询都会弹出一张确认卡片。

read_only 与不受关卡限制并不是一回事。共有三种不同的状态:invoices preview 不受关卡限制,也不写入任何内容;loads create 受关卡保护,并且会写入;invoices create 不受关卡限制,但会写入——会生成一份草稿。只需一个测试就能判定:命令返回时,数据库中是否有某一行发生了变化?

有些操作不在这道关卡之后,因为它们根本就不是命令:购买套餐、通过 3D Secure 添加银行卡、批准法律文本以及注销账户,都在本人自己的浏览器中进行。对于这些操作,lg handoff-links generate 会返回一个 logistivo.com 链接——免费、不写入任何内容、不携带任何机密——由本人在那里完成这一步。无论标志如何设置,都无法把一笔支付或一次同意变成 API 调用。

从技术上讲,集成可以在每次调用时自动通过关卡,但这并不可取。正确的做法是只对您确知可以撤销的命令自动通过关卡,而把不可撤销的命令转入人工处理队列。

预检:在不执行的情况下查看写入命令会做什么

搭建 ERP 桥接程序时最昂贵的一步,是通过“真正”执行命令来确认请求体是否正确:线上台账里多出一张草稿发票、白白消耗的点数、手动清理。dry_run 终结了这一切——您在请求中加一个字段,命令不会运行,而您可以读到将会发生什么。

注册表目前有 721 条命令;其中 327 条只读取、不写入任何内容。在其余 394 条写入命令中,有 346 条受关卡保护:不带 confirm 调用时,它们本来就会返回 409 并描述将要做什么。缺口在于另外 48 条——发票草稿、出口单证草稿、明细行:恰恰是桥接程序最先接入的那条链路。对于这些命令,调用即执行。

即使对于受关卡保护的命令,也存在第二个缺口:schema 校验是在关卡之后才运行的。因此,缺少参数的调用会先收到确认卡片,确认之后才被告知“缺少这个字段”。一次预检就能在一个往返中回答这两个问题。

而最常见——也是最晚才被发现的——桥接错误是这样的:您发送了一个 schema 中不存在的字段(本应是 recipient_contact_id 的地方写成了 customer_id),服务器悄悄丢弃了它,命令返回 200,记录却落到了错误的地方。预检响应会在 arguments.ignored 下按名称列出这些字段;任何错误消息都不会告诉您这些。

预检不写入任何内容,这首先是由结构保证的,其次才是测量结果:预检路径从不进入命令的处理程序,因此这一点对每条命令都成立,包括以后新增的命令。该功能上线时也进行了测量:对当时目录中的每条写入命令进行预检(两组参数、两个角色、共 178 次预检)期间发出的每一条 SQL 语句都被捕获了下来。没有一条 INSERT/UPDATE/DELETE,没有一个排队的任务,没有一封邮件;31 张表的行数和点数余额都没有变化。

退出码与真实调用会产生的退出码相同——可以运行时为 0,停在确认关卡时为 4,幂等冲突时为 2,其他情况为 1——因此 “lg … --dry-run || exit” 在 CI 步骤中是一道有意义的关卡。

幂等性:为什么重试不会产生重复

ERP 不会阅读您的错误消息,看不到您的屏幕,并且会在超时后重新发送同一个请求。本节正是为应对这种行为而存在的。

携带 idempotency_key 的调用最多只运行一次。第二次调用不会重新执行命令,而是返回已记录的结果,状态为 replayed。当网络中断、请求超时,或者队列把同一个任务取了两次时,您得到的是第一次的结果,而不是一张重复的发票。

每条写入命令都应使用一个键。目录中的 read_only 字段免费为您提供了这种区分:每一条 read_only: false 的命令都应该带上幂等键(idempotency key)。

您的重试策略应使用指数退避,并在每次尝试时携带同一个键。每次尝试都生成一个新键,等同于根本没有使用幂等性。不要并行发送同一个键:“最多一次”的保证针对的是顺序重试,而不是两个相互竞争的请求。

增量同步与分页

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:在一张实时变化的表上,offset 会发生漂移。在两页之间插入的一行,会让您悄无声息地跳过或重复统计一条记录。游标只能向前移动,因此在遍历过程中插入或更新的记录会落到列表末尾:不会丢失任何内容,也不会重复任何内容。

完整的初始加载也使用同一机制:从 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。时间戳精度为一秒,因此恰好位于边界上的记录可能会到达两次——只要您在自己一侧按 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。请根据键做分支,切勿根据文本。

您自己的键:external_ref

不要把我们的自增 id(invoice_id、contact_id)用作您 ERP 中的业务键;它们是不透明的,并且仅属于您的公司。运单、询价、联系人、发票、商品和仓库可以携带您自己的键。

外发 webhook:事件发生时由我们向您发送 POST

到此为止的一切都是拉取:您提问,我们回答。过去,ERP 桥接程序必须每分钟询问一次,才能得知某个运单的状态发生了变化、某张发票已经开具,或者收到了一份报价。现在不必了:注册一个 https 地址,选择您关心的事件,事件发生时就会收到一个签名的 POST。

推送是在拉取“旁边”新增的,而不是取而代之。增量同步(updated_since + cursor)原封未动,依然是合适的工具:首次完整加载、回填历史数据以及回答“我有没有漏掉什么”,都在那里完成。webhook 将延迟从分钟级缩短到秒级。健康的桥接程序两者并用——webhook 作为触发器,同步作为安全网。

payload 是一个“信号”,而不是记录的副本。它携带标识信息(id、您自己的 external_ref、状态、时间);您用自己的密钥通过 GET 获取详情,而这个调用本身就会经过您自己的授权关卡。因此,暴露面始终停留在标识符层面。有两个字段被有意省略:提交报价的公司身份(盲报价在面板中以化名显示;把身份放进 webhook,会通过第二条通道打破这种隐私)以及预订的联系人信息(没有必要让个人数据多走一条通道)。

事件名称是冻结的。如果某个名称的含义发生变化,就会启用一个新名称,旧名称则会在弃用窗口期内继续存在。向 payload 添加新字段不会提升契约版本——消费方必须忽略它不认识的字段。

事件目录

下面 13 个事件中的每一个,都对应一个“真正”会被派发的事件类。目录里没有“有了更好”的名称:一个宣布了却从未触发的事件,就是集成方要永远等待的事件,而这种失败是无声的。这张表同样不是手写的——每次加载页面时都从实时目录中生成。

invoice.payment_recorded 被有意排除在外:该事件类存在于代码中,但没有任何地方派发它。付款事件会在该类真正被触发的那一天加入——不会提前。过早宣布一个事件,比永远不加入它更糟糕。

验证签名

每个请求都带有 X-Logistivo-Signature 头:t=,v1=。被签名的字符串是 ".",算法为 HMAC-SHA256。v1 前缀使该方案可以进行版本演进:如果将来出现第二种方案,头中会携带 t=…,v1=…,v2=…,您选择自己认识的那一个即可。

我们发布了两个无依赖的参考接收端,一个用于 Node,一个用于纯 PHP。两者都应用了上述四条规则,并可通过 --selftest 自测:有效签名、被篡改的请求体、错误的签名密钥、超出窗口的时间戳、格式错误的头、重新序列化陷阱,以及两种重复(同一次投递 / 同一个事实)。验证器与我们自己使用的代码完全对应——我们自己也在消费我们发布的契约。

投递、重试与静默

您的接收端并不总是在线。这条通道考虑到了这一点:暂时性的失败会进入重试时间表,永久性的失败会使订阅被静默——而静默的“原因”始终会被记录。

静默原因是机器可读且稳定的(delivery_failures、endpoint_gone、unsafe_target、key_revoked、by_user),会同时显示在面板和 `lg webhooks list` 中。如果静默没有原因,“为什么什么都收不到”就无从回答。重新启用会重置计数器和时间戳。

地址由您填写;请求由“我们的”服务器发出。如果没有关卡,一个填入云元数据地址的租户就能让我们从自己的网络内部发出请求。因此,地址在注册时以及“每一次”投递时都会被检查:

健康与状态:桥接程序悄然停摆,不应由别人先于您发现

集成桥接程序很少会轰轰烈烈地宕掉。它通常是在凌晨悄无声息地停下来:令牌过期了,密钥所代表的那个人离开了团队,作用域被收窄了,或者接收端点开始返回 403。最先察觉的几乎总是客户。lg status 的存在,就是为了扭转这个顺序。

一条命令同时回答两个问题,因为在故障期间这两个问题会在同一时刻被提出:平台是否正常运行,以及我的桥接程序是否健康。平台状态这一行无需令牌即可使用——故障期间,令牌本身就是首要怀疑对象,如果把状态查询与令牌绑定,恰恰会在您最需要答案的时候得不到答案。

健康摘要不维护新的台账;它把三个现有来源汇总成一句话:每日使用计数器(您调用了多少次、失败了多少次)、请求台账(哪个请求、何时、因何被拒绝)以及外发 webhook 投递台账(事件是否到达了接收端)。错误率始终从每日计数器读取;明细台账设有上限,达到上限时会明确说明。

同样的摘要也会出现在面板中:在 Settings › Integration › Keys(设置 › 集成 › 密钥)下,每一行都带有一个徽章,下方注明原因。阈值不在客户端计算;服务器判定的级别是什么,面板和 lg status 就显示什么,因此两个界面对同一个密钥永远不会给出不同的说法。

您的监控程序不需要令牌。该端点只返回状态词;不包含版本、主机名、队列名称、任务数量、错误文本或客户数据——也不可能包含。

健康摘要每次请求只执行固定数量的查询;查询次数不会随密钥数量的增加而增长。如需详情,请用 lg logs 查看该密钥最近的请求,用 lg webhooks list 查看外发桥接。

错误与退出码

机器据以分支的是稳定的字符串。error 字段中的文本面向人类,经过本地化,并且会在不另行通知的情况下变化——基于消息文本做分支的集成不受支持,它因此出现故障也不算缺陷。

两套分类,两个字段。error_code 是传输层(上表),是您首先要据以分支的字段。error_key 是 failed 内部稳定的业务规则键——INSUFFICIENT_CREDITS、NOT_FOUND、DUPLICATE_CONTACT、INSUFFICIENT_STOCK——它以字典形式发布在目录中(error_keys)以及下方。尚未输出键的命令会返回 error_key: null;请将字典中不存在的键视为一般性失败。

稳定性承诺

集成契约中最昂贵的问题是:“我今天写的代码明天还能运行吗?”一个数字就能回答它:目录中的 contract_version,以及每个响应中的 X-Contract-Version 头。它只回答一个问题——之前写的代码能否原封不动地继续运行?如果这个数字没有增加,答案是能。如果增加了,答案是不能:您所依赖的某样东西被移除或收窄了。

因为公告并不移除任何东西:在公告发布后的第二天,您现有的代码依然与之前完全一样地运行。如果在公告时就提升版本,同一次变更就会发出两个信号,并训练您忽略第一个——从而削弱真正重要的那个信号。公告已经随您正在进行的调用一起送达:目录行上的 deprecated_at 和 replaced_by,该命令响应中的 X-Deprecated 头以及 deprecated 块,如果您使用 lg,还会有一行 stderr 警告。您无需做任何事就能得知某样东西即将移除;它已经在您的日志里了。

从公告到移除之间至少相隔两个日历季度。在整个窗口期内,旧命令依然会响应,并在每次调用时发出警告。当一个 CLI 名称被停用时,它的继任者会以别名的形式接管该名称:在窗口期内,旧名称调用的是旧命令;而在它被移除的那一天,同样的调用会落到新命令上——无需您发布任何客户端版本。

preview_invoice → get_invoice(2026 年 9 月 3 日公告)。get_invoice 返回相同的预览块,并增加了明细行、税额明细、已记录的付款、剩余余额,以及通过您自己的 ERP 键(external_ref)进行寻址。preview_invoice 依然有效,lg invoices preview 也是如此——两者都会发出警告。

命令身份表

下表并非手写:每次提供本页时,都会从实时命令注册表生成。服务器上新增的命令会自动出现在这里。“关卡”列告诉您一条命令是否请求确认,以及其效果能否撤销;“角色”列告诉您哪些账户类型会在其目录中找到它。徽章标出了需要 manager 级密钥的命令、需要文件的命令,以及只能从 lg 运行的命令。

命令按功能分组,每个功能有独立页面。选择一个功能即可打开其命令表。

API 名称(list_loads)是冻结的,永远不会改变;HTTP 调用中使用的就是这个名称。CLI 身份(loads list)受版本管理策略约束:一旦公告,只能随着版本提升和迁移窗口而改变,在此期间目录会以别名形式继续提供旧的组合。这里的描述来自每条命令自身的记录,并经过缩短——如需完整文本、参数类型和枚举值,请读取目录端点或运行 lg help 。仅限联盟推广账户的命令未在此列出;联盟推广账户可在自己的目录中看到它们。

ERP 与 CRM 集成 — 身份:没有服务账户,而是使用真实用户

ERP 或 CRM 以一名真实公司用户的身份连接 Logistivo,持有一个从面板签发的个人访问令牌。我们绝不会创建合成的服务账户——不属于任何公司、不受作用域约束、无人对其负责。

这是架构问题,而不是偏好问题。多租户隔离完全建立在用户所属的公司之上;对于没有公司的身份,隔离作用域就会失效,而该令牌上的一次错误查询就会读取到不属于它的数据。第二个原因是审计:台账中的用户列把“谁执行了这个”与一个人联系起来;服务账户会让这一列失去意义,并让一个负责开票的集成无人负责。第三个原因是吊销:如果令牌属于某个人,那么当这个人离开时,集成也会随之沉默。没有主人的桥接程序,正是那种会悄无声息地持续写入多年的桥接程序。

ERP 与 CRM 集成 — 版本管理与弃用

目录响应带有一个整数 contract_version;命令条目带有 since、deprecated_at 和 replaced_by。契约版本只会因破坏性变更而提升。

ERP 与 CRM 集成 — 稳定标识符:切勿把自增 id 交给 ERP 用作键

内部自增 id 是不透明的,并按租户限定范围:其他公司的有效 id 对您返回的是“未找到”,而不是数据。但不透明并不会让它们成为业务键。ERP 保存在自己记录中的,必须是业务键。

ERP 与 CRM 集成 — 分页、筛选与增量同步

列表命令接受 limit 并返回 count。对于夜间同步,契约承诺以下内容;已采用该契约的列表命令会在其 JSON Schema 中声明 cursor 和 updated_since,在此之前,请把它视为一个小窗口(上限 20 行,没有游标)。

ERP 与 CRM 集成 — 速率限制

限制的键是令牌,而不是 IP:ERP 是从单一 NAT 后面访问的,基于 IP 的限制会把整个公司算作一个用户。两个集成使用两个密钥,就永远不会互相消耗对方的配额——这是“一个集成一个密钥”的第二个理由。

ERP 与 CRM 集成 — 我们不会做的事

这往往是契约中最有用的部分:知道什么永远不会到来,您就可以围绕它进行设计。

机器可读的目录

本页是为人编写的。对于 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 助手以进行注册和货运询价,是一个独立的通道,有自己的页面:

机器可读的定义:OpenAPI 3.1 与 Postman

上面的目录是 Logistivo 自有的格式。同样的信息还以两种您的工具早已熟悉的行业标准格式发布:OpenAPI 3.1 定义和 Postman 集合。两者都不是手写的——都在每次请求时从实时命令注册表生成,因此不会过时。

这份定义“就是”目录,而不是第二个现实。每条命令都以一个 POST /api/common/commands/ 操作出现;请求体 schema 就是该命令自身的 JSON Schema(与助手看到的逐字节一致),响应 schema 是共用的信封,关卡标志(read_only、confirmation_needed、irreversible 以及点数徽章)位于 x-logistivo 扩展中,业务错误键位于 x-error-keys 之下。已停用的命令会被标记为 deprecated: true,并在其六个月的窗口期内仍可调用。

除命令接口之外,承载集成契约的 REST 端点也包含在定义中:10 个支持增量同步(updated_since + cursor + limit)的列表端点,以及 7 个接受您自己的键(external_ref)的写入端点。Logistivo 的 REST 接口面远不止这些;其余部分是“有意”排除的。那些 payload 是产品自身的契约,凭猜测写出的 schema 会让您生成的客户端在第一次调用时就出错——而您会在自己的代码里寻找缺陷,而不是在我们的代码里。

定义是按请求者的“角色”生成的:其他角色的命令永远不会进入文档,因为定义是一份契约而不是一本字典,其中的一切都必须能用该令牌调用。无需认证的版本是三个角色的并集,其中每个操作都会在 x-logistivo.roles 下注明哪些角色可以看到它。

不必轻信我们的说法——请自行验证:npx @redocly/cli lint logistivo-openapi.json 可以零警告通过。

代码生成:从定义生成类型化客户端

您已经有了定义;现在用它生成可运行的代码。`lg codegen` 读取 OpenAPI 文档,并写出一个单文件、无依赖的客户端——TypeScript(类型声明加上一层轻量的调用封装)或 PHP(带有 PHPDoc 数组形状的客户端类)。无需 `npm install`,也无需 composer:TypeScript 一侧使用 `fetch`,PHP 一侧使用 `ext-curl`。

生成过程发生在“您的”机器上,而不是我们的服务器上。这不是偏好问题:只需在您的代码仓库中固定一次定义(`lg spec --out=...`),同一条命令就能在每次构建时运行,无需网络也无需令牌,因此您的 CI 永远不依赖我们的可用性。而且,由于生成的代码是要在您的 ERP 中“运行”的代码,把它保存在您的仓库中而不是从 API 拉取,意味着每一处变化都会出现在 `git diff` 中。

生成的客户端能正确处理 Logistivo 的全部三条通道,并且是从文档中得知哪条是哪条,而不是靠猜测:每个操作都在 `x-logistivo.surface` 中声明了自己所属的通道。命令通道会解开 `{success, data:{…}}` 信封;REST 同步列表“没有”信封,会按原样返回(解开它会丢掉 `next_cursor`);REST 写入返回端点自身的产品响应体。通用的生成器不了解这种区别——我们的生成器了解。

类型不是猜出来的:每条命令的参数接口都由助手所看到的那份 JSON Schema 生成。必填的保持必填,枚举变为联合类型,嵌套对象变为嵌套类型。在实践中:如果服务器要求某个字段,遗漏它的调用不会在生产环境中以 422 失败——而是在编译时就失败。

文件中不会写入生成时间戳:相同的定义加上相同的选项,会产生相同的字节。因此,重新生成不会在 `git diff` 中制造噪音,而真正发生变化的那一件事——契约——始终清晰可见。

诚实的范围说明

我们宁愿让这一节变长,也不愿让它变短。一份集成契约的价值,与其说在于它承诺了什么,不如说在于它多么清楚地说明了自己不做什么。

常见问题

Logistivo CLI 有什么用途?

它可以从终端、脚本或您自己的 AI 智能体运行您 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(邮箱和密码)作为备用方式仍然保留。在服务器和 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 是单次运行的配置档选择器。

如何在脚本中读取 lg --json 的输出?

输出是完整的 HTTP 信封:{ "success": bool, "data": { "contract_version", "command", "status", "result" }, "code", "message" }。业务 payload 位于 .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 吗?

不会。支撑 Web 和移动应用的 REST 接口面保持不变。命令目录不取代资源的 CRUD;它是动词层——执行一项操作的唯一途径,并且经过角色关卡、确认关卡和审计。

如何获取 Logistivo API 密钥,它能做什么?

拥有团队管理权限的管理者可以在面板的 Settings › Integration keys(设置 › 集成密钥)下签发,也可以在终端中通过 lg keys create 签发。密钥代表一名真实的团队成员行事,并有三项相互独立的设置:作用域(read 开放目录和不写入的命令,write 开放所有命令——确认关卡保持不变)、可选的域授权,以及访问级别——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 会发送 webhook 吗?针对哪些事件?

会。您注册一个 https 地址并选择您关心的事件;事件发生时会收到一个签名的 POST。目前可订阅 13 个事件:运单已创建/状态已变更/司机已指派,询价已创建和状态已变更,报价已提交/已修改/已接受,发票草稿/已开具/已取消,以及仓库预订已创建/状态已变更。每个名称都对应一个真正会被派发的事件类——不存在宣布了却从未触发的事件,因为这样的事件是一种无声的失败,集成方会永远等待下去。订阅可在 Settings › Integration › Webhooks(设置 › 集成 › Webhooks)下创建,也可以在终端中通过 lg webhooks create 创建。

如何验证 Logistivo webhook 签名?

每个请求都带有 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 在重放时保持不变,而投递 id 会改变。可直接运行的 Node 和 PHP 接收端位于代码仓库的 examples/webhook-receiver/ 目录中,并可通过 --selftest 自测。

如果 webhook 无法投递怎么办?我会丢失事件吗?

不会。如果您的接收端没有返回 2xx,该投递会进入重试时间表:60 · 300 · 1800 · 7200 · 21600 秒,总共 6 次尝试,时间窗口约为 8.6 小时。除 410 Gone 之外的“所有”失败都会重试,包括 4xx——丢失一个业务事件的代价,远高于多发几次请求。连续 10 次投递用尽所有重试后,订阅会被静默,原因也会被记录,因此“为什么什么都收不到”始终可以得到回答。投递台账会保存每一次尝试(状态码、耗时、错误),您可以在面板中或通过 lg webhooks replay 重新发送单次投递。增量同步(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 就会先上传该文件;当命令只有一个文件字段时,--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 更改级别。

联盟推广(affiliate,即推荐合作方)账户可以使用 CLI 吗?

可以。联盟推广账户拥有自己的目录——55 条命令,涵盖推荐、潜在客户、CRM 备注与任务、销售演示文稿、收益与提现——并像其他任何角色一样,通过 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.