Logistivo CLI:在终端和 ERP 中运行您的物流业务
同一份命令目录驱动三个入口:lg 终端客户端、面板内的 AI 助手,以及外部 AI 助手所接入的通道。一项能力只需编写一次,就会同时出现在这三处——而且面板中的每一项写操作现在都有对应的命令,因此您的脚本和您自己的 AI 智能体可以完成团队在屏幕上所做的工作。支付、法律同意和账户注销则有意保留在浏览器中。 本页是一份契约。下方的命令表并非手写,而是在每次请求时从实时命令注册表生成。
什么是 Logistivo CLI?
Logistivo CLI(lg)是一个命令行客户端,可以从终端、脚本或您自己的 AI 智能体运行 Logistivo 账户中的各项工作——运单与行程、询价、报价与招标、车队与司机、单证、联系人与往来账户、发票与会计、仓库与库存、团队成员以及海关税则。命令并没有固化在客户端里:客户端从服务器拉取命令目录,并据此生成自身。同样的命令无需安装任何东西即可通过 HTTP 调用——ERP 和 CRM 集成走的正是这条路径——也可以通过外部 AI 助手所接入的 MCP 通道调用。
所有命令都采用 lg --parameter=value 这一种形式。目前目录包含 175 个域中的 721 条命令;单个角色能看到的最大列表为 165 个域中的 646 条命令。
面板中的每一项写操作都有对应的命令——以面板的写入端点为基准衡量,范围内的端点 100% 已覆盖。支付(3D Secure)、法律同意和账户注销有意保留在浏览器中;对于这些操作,命令会返回一个链接。
需要单证或照片的命令在浏览器之外同样可用:写成 --attachment_uuid=@./cmr.pdf 即可,lg 会先上传该文件;通过 HTTP 时,先将文件上传到 /api/common/commands:upload 端点,再传入返回的 attachment_uuid。
集成密钥带有访问级别:employee(新密钥的默认级别)用于日常运营,manager 用于团队、设置、密钥和资金相关的工作。密钥的权限永远不会超过它所代表的那个人。
选项从不凭空编造:每个选项都是该命令自身 JSON Schema 中的参数名,选项的类型以及是否必填也同样来自该 Schema。
写入类命令会请求确认;不可撤销的命令未经确认绝不会执行(HTTP 409,CLI 退出码 4)。
重试不会产生重复:携带 idempotency_key 的调用最多只执行一次。
每一次执行都会记入同一份审计台账——无论它来自终端、聊天还是助手,都有据可查。
哪些已经上线,哪些即将推出
本节特意放在页面顶部。集成文档可能犯下的最昂贵的错误,就是把尚未开放的端点描述得好像已经可用:集成方写好了代码,端点却返回 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} 三个端点。角色关卡、确认关卡、幂等性和审计台账都位于同一个强制执行点,聊天和终端也同样要经过这里。
面板覆盖:每一项写操作都有命令 — 175 个域中的 721 条命令已与面板的写入端点逐一核对:范围内的每个端点都有命令支撑(该端点的镜像命令,或调用同一共享服务的命令),没有一个未经证实。有意排除在范围之外的有:使用 3D Secure 的支付、法律同意、账户注销和登录——它们保留在浏览器中;密钥、webhook 和沙箱管理——它们是 lg 的内置命令;以及司机 App 自身的端点。
预检(dry_run):只看结果,不实际执行 — 在请求体中加入 dry_run: true 后,命令不会执行:校验、角色/作用域关卡、目标解析和点数计算全部照常运行,并返回一份预览;不写入任何内容,不消耗点数,也不占用幂等键。批量端点同样支持该参数,按批次生效。预检从不进入命令的处理程序;该功能上线时,对当时目录中每一条写入命令进行的 178 次预检,没有产生一条写入语句。
集成密钥 — 代表一名真实团队成员行事的 API 密钥,可在面板中签发,也可以通过 lg keys create 签发:读/写作用域、访问级别(默认 employee,或 manager)、有效期、最近使用时间、轮换、转移和吊销。lg login --api-key、lg whoami 以及会在服务器端吊销密钥的 lg logout 都构建于其上。
沙箱——演练写入,不触碰生产环境 — 每家公司拥有一个独立的沙箱租户,命令目录完全相同;可自助开通,并签发自己的密钥。点数、交易市场和 webhook 路由在两个环境之间相互隔离;环境由密钥所属的公司推导得出,无法随请求指定。
版本管理、错误分类、幂等性与速率限制 — 命令带有 since / deprecated_at / replaced_by / aliases 字段,已弃用的命令会返回 X-Deprecated 头。业务失败除传输层的 error_code 之外,还带有稳定的 error_key,键字典在目录中公布。幂等键的作用范围限于您的公司,绑定到一条命令,并锁定 24 小时。速率限制按令牌计算,分为三个桶,每个 429 响应都带有 Retry-After。
外发 webhook:事件发生时向您发送 POST — 签名推送已对 13 个事件上线。订阅可在面板中或通过 lg webhooks 管理;签名中包含自身的时间戳,重试时间表为 60 · 300 · 1800 · 7200 · 21600 秒,静默原因始终会被记录。每个事件名都对应一个真正会被派发的事件类——不存在宣布了却从不发送的事件。拉取通道(updated_since + cursor)并没有被移除:推送是在它旁边新增的,而不是取而代之。
需要文件的命令 — 38 条命令需要单证或照片——CMR、发票、车辆登记证、托盘照片。只需上传一次到 POST /api/common/commands:upload 端点,或者让 lg 通过 --attachment_uuid=@./file.pdf 代劳,然后传入返回的 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 + 不透明的签名游标、next_cursor、updated_since)已经固定,正在逐步推广到各个列表命令。在某个列表命令于其 JSON Schema 中声明 cursor 和 updated_since 之前,请把它视为一个小窗口:上限 20 行,没有游标。
与众不同之处:客户端不内置任何命令,而是根据目录生成命令
正是这一个决定,让本页其余内容有了意义。在普通的 CLI 中,命令存在于客户端内部;而在 Logistivo 中,命令存在于服务器上。
在传统的架构中,服务器每获得一项新能力,客户端就需要发布新版本,用户还需要安装它。在此期间,两端所知的内容并不一致——而这正是集成中最隐蔽的故障模式:脚本照常运行,退出码为 0,可命令根本没有反映出服务器能做什么。
在 Logistivo 中,一条命令的定义就是一条记录:它的名称、作用、JSON Schema 参数、哪些角色可以看到它、是否需要确认,以及其效果是否可撤销。lg 启动时会拉取这份目录,并据此生成帮助文本、选项和输入校验。服务器上一旦新增命令,lg 立即就能识别——无需更新客户端。
同一份目录还驱动着面板中的 AI 助手,以及外部 AI 助手所接入的通道。一项能力只编写一次,就会出现在三个地方——而且三者都经过同一个角色关卡、同一个确认关卡和同一份审计台账。不存在单独的 CLI 命令清单;如果有,这三个入口会在六个月之内悄然分道扬镳。
没有版本漂移 — 客户端所知的命令列表,从构造上就等于服务器拥有的列表。“哪个 lg 版本有这条命令?”这个问题根本不存在。
选项名称从不靠猜 — 一条命令的选项恰好就是其 JSON Schema 中的参数名。了解一条命令接受什么,靠的不是阅读文档,而是读取目录——而目录始终是最新的。
您的 CLI 与您的账户一样大 — 目录按角色过滤:您的角色看不到的命令,永远不会出现在您的列表中。承运商账户可看到 621 条命令,货主可看到 646 条,报关行可看到 392 条,而联盟推广(affiliate,即推荐合作方)账户拥有一套自己的命令,共 55 条。
文档不会落后 — 本页上的命令表来自同一个注册表。任何地方都不存在需要人工与现实保持同步的列表。
命名规则——命令名称如何扩展
目录会不断增长。新命令不是随意命名的,而是遵循六条规则。我们在这里公布这些规则,因为这些名称将在您的集成中被书写多年,它们的可预测性对您很有价值。
域是复数形式的实体 — loads、demands、invoices、export-documents。由两个单词组成的域使用 kebab-case。唯一的例外是不可数名词:stock 永远不用复数,因为 “stocks” 是另一个意思。
同一实体的所有动词都位于同一个域中 — loads 承载所有作用于运单的动词:create、list、get、update、set-status、assign-driver、list-problems、archive 等等。如果每个动词都新开一个域(load-statuses、load-drivers),用户就得在三个地方寻找同一个实体。
动词从不渗入域名;域是被“改变”的那个对象 — 指派司机改变的是运单,而不是司机,因此命令是 lg loads assign-driver。间接宾语(-driver)附加在动词上,从不附加在域上。
子资源永远不会拥有自己的域 — 发票行和单证条目无法单独列出;它们要通过其所有者来访问——lg invoices add-line、lg export-documents add-item。判断标准只有一个:如果某个东西无法独立地被 list 或 get,它就不是一个域。
缩小范围用选项,而不是新动词 — lg fleet-documents list --days=30 才是正确写法;不存在单独的 “list-expiring” 动词,因为时间窗口本身已经是一个参数。只有当返回的行不是该域的实体时,才使用限定动词:loads list-problems 返回的是问题标记,而不是运单。
(domain, verb) 组合在整个目录中唯一 — 即使两条命令的角色从不重叠也是如此。如果同一组合被分配给两条命令,您的集成代码看到的是同一个名称,而 CLI 却会因调用者不同而执行不同的操作。
覆盖范围:面板中的一切,都能通过命令完成
许多团队把 Logistivo 接入自己的 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)开始:它会返回角色、当前所用密钥的访问级别、实际生效的权限,以及当前是否有待处理的法律批准或未验证的手机号码正在阻止写入——这样智能体就能提前预判拒绝,而不是一次次去碰壁。
覆盖范围由一份将命令注册表与面板写入端点进行比较的报告来测量;没有对应命令就新增的面板端点,会在报告中显示为未经证实。如果您发现某个面板操作无法通过命令完成,请向支持团队报告。
1. 请求链接 — 必须在本人自己的浏览器会话中完成的工作不是命令,但命令接口面知道它的存在。lg handoff-links generate(API 名称 get_browser_handoff_link)会针对您的角色所允许的用途返回一个 logistivo.com 链接:package_purchase、payment_cards、legal_documents、integration_keys、affiliate_demo_accounts 和 account_close。它是免费的,不写入任何内容,链接也不携带任何机密——本人照常登录即可。
2. 交给本人 — 把链接展示给用户,或通过您自己的渠道发送。用户会在那里完成这一步:套餐的合同批准和 3D Secure 支付、添加银行卡、批准待处理的法律文本、签发一个其机密只显示一次的 API 密钥,或注销自己的账户。
3. 用命令读取结果 — 这一步完成后,其结果会再次对命令可见:套餐和点数余额、已保存的银行卡(已掩码,仅显示后四位)、密钥列表中的新密钥。智能体永远不会在聊天中接收卡号、支付或同意。
支付与 3D Secure — 购买或升级套餐以及添加银行卡,都需要在浏览器中完成 3D Secure。命令可以列出套餐和价格、读取余额及其历史、列出已保存的银行卡(已掩码)、设置默认银行卡以及删除银行卡;购买本身则通过交接链接完成。
法律同意 — 批准法律文本由本人在浏览器中完成。lg users get 会告诉您有一项批准正在等待处理;没有任何命令能够代为批准。
账户注销、登录与密码 — 注销自己的账户、登录以及修改密码都属于身份步骤,保留在浏览器中。lg user-accounts preview 会展示注销账户意味着什么,但不会实际执行。
集成密钥、webhook 与沙箱 — 管理它们会返回必须只在您的终端中显示一次的机密,因此它们是基于各自 HTTP 端点的 lg 内置命令(lg keys、lg webhooks、lg sandbox),而不是目录命令。目录中只包含两条不涉及机密的密钥命令:integration-keys list 和 integration-keys revoke。
面板助手聊天 — 集成密钥无法驱动面板内的 AI 助手聊天;用密钥启动或继续一次运行会返回 403。智能体应改为通过命令端点、lg 或 MCP 通道连接——在那里,每条命令都以密钥的访问级别运行,其写入会被记录为集成写入。
司机 App — 司机账户没有命令目录,司机 App 保留其自身的端点。办公室用户通过命令管理司机及其单证、费用和行程。
安装与身份
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 的字段,以及命令声明为机密的每一个参数,掩码为 ***。
LOGISTIVO_TOKEN — 个人访问令牌。设置后,配置文件永远不会被读取——这是 CI 和服务器上的首选方式。
LOGISTIVO_BASE_URL — 服务器根地址。默认指向 https://logistivo.com 这一地址。只有在指向您自己的环境时才需要修改;--base-url 选项对单条命令起同样的作用。
LOGISTIVO_HOME — 存放配置文件和目录缓存的目录。默认为 ~/.logistivo。如果您在一台机器上使用两个账户,请将它们分开。
LOGISTIVO_PROFILE — 以哪个配置档(profile)运行。`lg profile use` 是持久性的选择;此变量只作用于单次运行,是在 CI 中切换线上配置档与沙箱配置档的最简便方式。未知的配置档名称不会被静默忽略——会直接报错。
NO_COLOR — 设置后不输出任何 ANSI 颜色(相当于永久启用 `--no-color` 选项)。如果桥接程序会写入日志文件或 CI 输出,请开启它;颜色转义序列会破坏之后读取这些日志的工具。
客户端易用性
这些功能让日常使用 `lg` 客户端更加轻松。它们都不会改变 HTTP 契约——如果您直接通过 HTTP 集成,可以跳过本节。
多环境与多密钥 — 将预发布环境和生产环境,或者您的客户桥接与承运商桥接,分别保存在不同的配置档中。配置档列表从不打印令牌;每一行显示的是令牌的 sha256 指纹。命令目录按配置档、主机和令牌分别缓存,因此两个角色永远看不到彼此的命令列表。
增量同步:lg sync — 用一条命令运行实践手册中的同步循环:按实体记录的水位线、带游标的 updated_since、JSONL 输出以及五分钟的安全余量。首次回填请使用 --full。该命令是只读的;没有 --write 选项。lg sync --list 会根据目录推导出您的角色可同步的实体。
错误体验与 shell 补全 — 遇到 422 时,客户端会以您输入的选项形式指出被拒绝的字段,并给出稳定的 error_key 以及目录对它的解释。遇到 409 时,它会打印出现成的 --yes 命令行;遇到 429 时,它会等待 Retry-After 指定的时间。Shell 补全覆盖域、动词、选项和枚举值,并且可以离线使用。
机密参数永远不出现在命令行上 — 少数命令需要机密信息——例如,连接 Paraşüt 会计集成时,需要该系统的客户端凭据和密码。lg 从不接受以选项形式传入此类值,因为它会留在您的 shell 历史和 ps 输出中:lg 会以不回显的方式询问,或者从 ---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 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 域授权也不会开放管理工作。请代表能满足您需求的、权限最小的成员签发密钥:角色决定了您究竟能看到哪些记录。
read — 命令目录以及不写入的命令(list、search、preview)。写入命令会返回 403 forbidden——在确认关卡之前;只读密钥甚至永远看不到 409。适用于夜间同步和报表。
write — 所有命令。需要确认的命令仍会以 409 请求确认;confirm: true(CLI 中为 --yes)的作用与以前完全相同。作用域永远不会放宽确认关卡。
employee — 每个新密钥的默认级别。日常运营:运单、询价、报价、行程、车队与车队单证、单证、联系人——所有不需要管理权限的命令,外加车队相关权限。需要更高级别的命令会返回 422,并带有 error_key INSUFFICIENT_KEY_LEVEL 和 required_key_level: manager;对应的 REST 端点则以相同的键返回 403。这是 ERP 夜间同步、车载信息(telematics)桥接或运营脚本的合适级别。
manager — 密钥所代表的人可以做的一切,包括管理工作:团队成员和角色、公司设置、集成密钥、银行账户及其验证、已保存的银行卡、公司间关系、联盟推广提现。manager 密钥永远不会增加此人本身不具备的权限——没有团队管理权限,它依然无法管理团队。在引入访问级别之前就已存在的密钥都是 manager 密钥,因此它们的行为与以前完全相同。
一个集成一个密钥 — 如果 CRM 和 ERP 共用一个密钥,切断其中一个就意味着切断另一个。请为每个桥接程序配备独立的密钥;反正列表会按名称显示它们。
轮换 — 签发新令牌并立即吊销旧令牌;剩余有效期保持不变。在怀疑泄露时以及定期使用它。在用新令牌更新之前,集成会收到 401。
吊销 — 密钥被永久关闭;此操作无法撤销,如有需要请签发新密钥。如果密钥所代表的成员被移出团队或被停用,密钥会自动失效。
有效期与数量上限 — 默认有效期为 180 天;您可以在创建时缩短它,但永远不能延长。一名用户最多可持有 10 个有效密钥。列表中可以看到最近使用时间;从未使用过的密钥会明确标示这一点。
谁来管理 — 签发、轮换、转移和吊销向拥有团队管理权限的管理者开放——与添加或移除团队成员是同一道关卡——并且,当通过集成密钥执行这些操作时,该密钥必须是 manager 级。管理者可以代表其他成员签发密钥;对于桥接程序,建议使用一名专用的、权限范围很窄的成员。
最初的十分钟:从面板到您的第一次调用
集成中最昂贵的几分钟,就是最初的十分钟。下面四个步骤按顺序铺开了这条路径;面板中也以向导的形式提供了同样的顺序(Settings › Integration › Setup wizard,即“设置 › 集成 › 设置向导”),而且该向导调用的正是这里描述的端点。无法使用向导的开发者,阅读本节也能到达同一个地方。
这四个步骤没有一个以“我已经发出去了”作为结束。密钥是否真的可用,由请求台账来回答;webhook 是否真的送达,由投递台账来回答。两者在面板和 lg 中都可以查看。一套从未被测量过的配置,只是一套被“相信”能工作的配置。
1. 决定要做什么——先设定作用域 — 不存在事后再决定密钥能看到什么的情况:您在签发密钥时就要选择作用域。作用域有两条轴。粗粒度作用域(read / write)只回答“能否写入”。细粒度作用域(域授权:loads:read、invoices:write)说明它可以触及哪些域,一旦设定,密钥就变为默认拒绝(fail-closed)——您未选择的每个域,以及每个不对应任何域的端点,都会返回 403。面板中的域列表不是手写的;它由您角色的实时命令目录推导而来,并显示每个域开放了多少条命令和 REST 端点。命令目录、“我是谁”(current)和“退出登录”端点始终不受作用域限制:密钥必须始终能够描述并关闭自身。第三条轴是访问级别:employee(默认)执行日常运营,manager 还可以处理团队、设置、密钥和资金相关的工作。除非桥接程序要做管理工作,否则请选择 employee。
2. 签发密钥——令牌只显示一次 — Settings › Integration › New key(设置 › 集成 › 新建密钥)。为它起个名字(“ERP nightly sync”),选择它所代表的用户和访问级别,如果需要还可以缩短有效期。原始令牌只在那一次响应中返回;服务器不会存储它,面板中也没有“再次显示”。如果丢失,请轮换以获取新令牌,旧令牌会立即失效。切勿将令牌放入版本控制、CI 日志或聊天窗口;请把它放进目标系统的机密存储中。
3. 发起第一次调用——并确认它“真的”到达了 — 两个请求就足够了。第一个请求证明您的身份(它不受作用域限制,任何密钥都能使用):作用域是否符合预期,状态是否为 active,expires_at 是否临近。第二个请求从您选择的域中读取真实数据。如果通过,说明身份、作用域、邮箱关卡和网络路径都是正确的。如果没有通过,不要靠猜:密钥自己的请求台账会逐行显示哪个端点以哪个状态码、哪个稳定错误键(INSUFFICIENT_SCOPE、IP_NOT_ALLOWED、KEY_ACTOR_BLOCKED …)被拒绝。在面板中,这份台账就是 “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. 开通沙箱 — 每家公司一个沙箱。该端点需要团队管理权限(team.manage),因此由贵公司的管理员来执行这一步。如果沙箱已经存在,同一个端点通过 GET 会返回其状态:公司 id、剩余点数、有效密钥数量、订阅、生成历史以及各项上限。
2. 签发沙箱密钥,并将其保存为第二个配置档 — 该密钥代表沙箱自己的桥接用户签发,返回时带有 environment: sandbox 标记;原始令牌只出现在那一次响应中。在 lg 一侧,不要替换您的线上密钥——请将“两者”分别保存为独立的配置档;--sandbox 和 --live 是单次运行的选择器。
3. 真正地写入 — 这里不用 --dry-run;写入才是重点。把同一个幂等键发送两次,看第二次响应以 status: replayed 返回——这就是在沙箱中测得的结果。故意在未确认的情况下调用受关卡保护的命令,读一读 409 响应体;尝试调用一条超出作用域的命令,读一读拒绝信息。这一切都不会在您的线上台账中留下痕迹:在同一次运行中,您的线上余额保持不变。
4. 上线前阅读检查清单 — 上线(go-live)端点根据您在沙箱中“实际”做过的事情作答:您是否写入过,是否见过错误分支,是否有 webhook 被投递,是否已把接收端从演练地址移走,是否为密钥设置了到期时间。每一项都会以 pass / todo / unknown 返回。同一响应还带有一份根据您实际调用过的命令推导出的“作用域建议”——用它来签发您的线上密钥,使其范围不超出您的需要。
点数与开票 — 沙箱有自己的点数台账,您的线上余额不会变动。这是结构上的保证,而不是一项检查:点数按公司计算,而沙箱是一家独立的公司。它以免费档位开通,没有支付方式,并且处于月度收款窗口之外——无论通过哪条路径,它都不可能产生发票。
交易市场 — 您在沙箱中创建的询价“不会”出现在真实承运商的屏幕上,也“不会”进入他们的电子邮件或推送收件箱;您也看不到真实的询价。这种隔离是对称的,并在两个独立的查询中强制执行:一条询价对谁“可见”和发送“给”谁,是两个不同的问题。
Webhook — 订阅同样带有环境标记。沙箱事件永远不会投递到线上订阅,线上事件也永远不会到达沙箱订阅;对于标记发生偏移的订阅,根本不会创建任何投递。由于订阅上限按公司计算,您的演练订阅不会占用您的线上配额。
种子数据 — 沙箱中的样例记录是“生成”的,绝不是从真实租户复制而来。生成种子数据是幂等的:第二次调用不会在您自己的记录上再铺一层种子数据。
同一份目录 — 您的角色在沙箱中依然是您的角色,命令列表完全相同——经过测量,两边都是 646 条命令。沙箱不是一个缩水的演示;它是您公司的孪生体。
当前的限制:无法用沙箱密钥管理 webhook 订阅 — 订阅端点需要团队管理权限(team.manage),而沙箱的桥接用户没有任何团队角色,因此 `lg --sandbox webhooks …` 目前会返回 403。整个命令接口面都可以正常工作——限制仅在于订阅台账。如果您想在沙箱中演练 webhook,请联系支持团队;这一点已经过测量,并作为一个未解决的缺口记录在案。
GET /api/common/integration-sandbox — 状态:是否存在、属于哪家公司、剩余点数、有效密钥数量和订阅数量、生成历史、各项上限,以及一份触发指南,说明哪条命令会引发哪个事件。
POST /api/common/integration-sandbox — 开通沙箱(每家公司一个,幂等)。需要 team.manage 权限。
POST /api/common/integration-sandbox/keys — 201 + 密钥和原始令牌(仅在此处出现,仅出现一次)。environment: sandbox 标记由公司推导得出;调用方无法指定。
GET /api/common/integration-sandbox/go-live — 上线检查清单和作用域建议——根据您在沙箱中的真实流量计算得出。
POST /api/common/integration-sandbox/renew — 开启一个新的沙箱“代”,并让上一代退役。
命令模型
语法只有一种,而且没有例外。要知道如何调用一条命令,您只需要知道目录对它的描述。
lg loads list --status=in_transport --limit=20 --json
选项名称就是 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 ——参见“需要文件的命令”一节。
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 中的参数名完全一致,其值必须符合 schema 中的类型。枚举字段上的无效值永远不会到达服务器。
--limit=20 — 列表命令返回的行数。上限写在每条命令的参数描述中——普通列表调用通常为 20,同步模式(带 cursor 或 updated_since)下最多为 100。
--json — 原始 JSON 输出。
--json — 输出原始 JSON。这是脚本唯一正确的使用形式:默认的对齐表格是给人看的,它会根据数据挑选列,并可能在不另行通知的情况下改变布局。切勿编写解析表格输出的脚本。
--yes, -y — 通过确认关卡(HTTP 中为 confirm: true)。只在清楚知道自己将要做什么的脚本中使用;对于不可撤销的命令,这个选项就等于“无法撤销”。
--idempotency-key= — 让重试写入命令变得安全。使用相同键的第二次调用不会重新执行命令,而是返回第一次的结果。如果您要构建重试循环,请由您自己生成这个键,并在每次尝试时发送同一个键。
--dry-run — 执行预检而不是命令本身:校验、各道关卡和点数计算照常运行,但不写入任何内容(参见预检一节)。对每条命令以及 lg batch 均有效。
--refresh — 强制刷新目录。lg 会将目录缓存一小时;如果您知道服务器上刚刚新增了一条命令,请使用此选项,而不必等待。
--help, -h — 打印该命令在目录中的描述、每个参数、参数类型、枚举值以及是否必填。客户端内部没有帮助文件。
--profile=, --sandbox, --live — 本次调用以哪个配置档运行。--sandbox 和 --live 会选取持有沙箱密钥或线上密钥的配置档;环境在服务器端由密钥推导得出,因此不匹配时会以 403 ENVIRONMENT_MISMATCH 中止,而不会写入错误的地方。
--base-url, --timeout, --verbose, --no-color, --version — 依次为:将单条命令指向另一台服务器、以秒为单位的超时、请求/响应详情、禁用 ANSI 颜色,以及客户端版本。
真实示例
以下每条命令目前都存在于目录中;这里没有任何名称或参数是编造的。输出已作删节。输出展示的是 `data.result` 层级;通过 HTTP 调用时,同一个对象位于 `{success, data:{…}}` 信封之内(参见 HTTP 命令 API)。
当前在途的运单 — lg loads list --status=in_transport --limit=20
单条运单的完整内容,原始 JSON — lg loads get --load_code=FSK2158 --json
未处理的单证一致性标记 — lg loads list-problems --only_open=true --limit=10
解析国家 — lg countries search --query=Germany --json
用解析出的 id 进行筛选 — lg loads list --receiving_country_id=57 --date_from=2026-09-01 --limit=20
根据商品名称查找 HS 编码 — lg tariffs search --query="aluminium profile"
推进运单状态(仅限承运商角色) — lg loads set-status --load_code=FSK2158 --status=transit --date=2026-08-21 --yes
草稿 — lg export-documents create --doc_type=proforma-invoice --currency_code=EUR --json
生成(受关卡保护) — lg export-documents generate --document_id=8412 --yes
不用客户端:HTTP 命令 API
lg 只是一种便利,而不是唯一的入口。目录和执行都通过三个 HTTP 端点完成(文件还有第四个端点,即上传端点——参见“需要文件的命令”);ERP 或 CRM 集成直接连接到这里。身份凭证是一个通过 Authorization: Bearer 携带的个人访问令牌。每一个响应都使用同一个信封返回:`{ "success": bool, "data": { … }, "code": "…", "message": { … } }`。整个契约都位于 `data` 之内——`contract_version`、`command`、`status`,以及作为命令输出的 `result`;失败时则是 `error_code`、`error_key` 和 `error`。为节省篇幅,本页的响应示例展示的是 `data` 对象而不是整个信封;在您自己的代码中别忘了解开 `data`。`lg --json` 打印的也是整个信封,这就是 jq 路径以 `.data.result…` 开头的原因。唯一的例外是 `/api/public/status`:该端点不使用信封,以便监控程序无需解析即可告警。
用 200 + ok:false 来请求确认是被禁止的,也永远不会发生。原因很简单:客户端会把 200 当作成功,因此以 200 返回的确认请求会悄无声息地中断流程,而且没有人会察觉。确认请求始终是 409。
GET /api/common/commands — 您的角色可见的完整目录:contract_version;每条命令的 name、domain、verb、description、JSON Schema、read_only、confirmation_needed、irreversible、credit_cost、since、deprecated_at、replaced_by、aliases,以及访问字段 key_level、permission、file_params、secret_parameters 和 cli_only;顶层则包括 error_keys 字典、rate_limits、idempotency_ttl_hours、您的目录角色、附件(上传)契约,以及您调用时所用密钥的访问级别。会发送 ETag;If-None-Match 会得到 304。?domain= 也能匹配旧的(别名)域。请据此生成您的客户端;不要硬编码命令列表。
GET /api/common/commands/{name} — 单条命令的完整信息。name 是目录中冻结的命令名称(list_loads),而不是 CLI 身份。已弃用的命令会返回 X-Deprecated 头。
POST /api/common/commands/{name} — 执行。请求体:{ args, confirm?, idempotency_key? }。响应的 HTTP 状态本身就是结果——任何非 200 的状态都是信息,而不是噪音。错误带有 error_code(传输层),对于业务拒绝还带有 error_key。
需要文件的命令
表中有 38 条命令需要单证或照片:为运单附加 CMR、从发票中读取 HS 编码、根据车辆登记证创建车辆、根据照片估算托盘、上传公司单证、将发票与装箱单进行交叉核对。在浏览器中,您只需把文件拖进表单;在其他任何地方,都需要两个步骤——先上传文件,再把它的 id 传给命令。
当参数名以 attachment_uuid 或 attachment_uuids 结尾时,该参数接受文件——列表中的 photos[].attachment_uuid,支票上的 front_attachment_uuid。您不必记住这些:每个目录行都带有 file_params,其中给出确切的路径;schema 会标记这些字段(format: uuid, x-logistivo-file: true);目录响应中还带有一个 attachments 块,包含上传地址、接受的类型、大小限制和存活时间。lg help 也会显示它们。
上传是一种写入,因此只读作用域的密钥无法上传;任何写入作用域的密钥都可以上传,无论访问级别如何。上传的文件属于用户,而不属于密钥:同一用户的两个密钥看到的是相同的上传文件,任何人都无法使用别人的文件。未知、已过期或不属于您的 id 只会被视为找不到,原因不会被透露。
面板聊天附件和命令上传是两个独立的空间:在助手聊天中附加的文件无法通过 id 传给命令,命令上传的文件也永远不会出现在聊天线程中。
上传不是命令,本身也没有任何业务效果:在某条命令使用这个 id 之前,您的数据不会发生任何变化。这也是上传从不请求确认的原因——由消费该文件的命令来承担关卡。
1. lg:在本地路径前加上 @ — lg 会先上传文件,然后用返回的 id 运行命令;不带 @ 的值是您之前上传过的某个文件的 id。列表接受以逗号分隔的路径或重复的选项,嵌套字段接受 JSON,而当命令恰好只有一个顶层文件字段时,--file 是一种简便写法。在发送任何内容之前,lg 会在本地验证每个文件(是否存在、大小、类型),而 lg batch 会在批处理运行之前把每个不同的文件上传一次。
2. HTTP:先上传,再传入 attachment_uuid — 以 multipart/form-data 形式发送文件,字段名为 file。新的上传返回 201;同一用户再次上传同一文件时返回 200,状态为 replayed,id 相同,并且不会写入任何内容。与本页其他地方一样,示例展示的是信封内的 data 对象。
3. MCP:upload_attachment 工具 — MCP 客户端无法发送 multipart,因此该通道额外提供了一个不在目录中的工具:upload_attachment 接受文件名和 base64 编码的内容,并返回同样的 attachment_uuid。它调用的是与 HTTP 上传相同的服务,遵循相同的规则。
类型取决于内容 — 文件名和声明的类型都会被忽略;存储的扩展名是检测出的扩展名。允许上传的类型:jpg, jpeg, png, webp, heic, heif, pdf, xlsx, xls, csv, txt, doc, docx, xml, zip。随后,每条命令会在运行任何操作之前应用自己更窄的列表,并以 UNSUPPORTED_FILE_TYPE(附带接受的类型)或 FILE_TOO_LARGE 作答。
大小 — 图片最大 10 MB,其他文件最大 15 MB。
存活时间 — 上传的文件可在 24 小时内使用。此后它将不再被解析(ATTACHMENT_NOT_FOUND)——但并不会被删除。如果命令因此失败,请重新上传。
同一文件,同一 id — 再次上传同一文件(相同的名称、大小和内容)时,只要原上传至少还剩一小时的有效期,就会返回现有的 id,而不会写入新的文件,并且不会占用您的每日上限。
每日上限 — 每名用户每天 300 次上传(TOO_MANY_FILES),每家公司每天 2 GB(DAILY_LIMIT_REACHED);两者都会返回 429 并附带 retry_after。
POST /api/common/commands:upload — 在字段 file 中进行 multipart 上传。新的上传返回 201,同一文件返回 200 且状态为 replayed。返回 data.attachment:attachment_uuid、filename、mime_type、size_bytes、sha256、extraction_status、expires_at 和 reused。
确认关卡与不可撤销的命令
目录中的每条命令都带有两个标志:confirmation_needed(执行前是否需要明确批准)和 irreversible(其效果能否撤销)。这是两个独立的问题,而且两者都在服务器端强制执行,而不是寄望于客户端的自觉。
这道关卡关乎责任,而不是业务规则。提交报价是迈向运输合同的第一步;开具发票会产生一笔会计分录;库存变动会改变一本台账。这些操作都不应该因为意外而被执行两次。
关卡读取的是“实际生效”的命令。当一条命令包装另一条命令时——比如聊天中的通用执行器——关卡取自真正将要运行的那条命令的标志,而不是包装器的标志。如果使用固定的标志,两种失败中必有一种无法避免:要么开票命令在未经确认的情况下运行,要么每一次国家查询都会弹出一张确认卡片。
read_only 与不受关卡限制并不是一回事。共有三种不同的状态:invoices preview 不受关卡限制,也不写入任何内容;loads create 受关卡保护,并且会写入;invoices create 不受关卡限制,但会写入——会生成一份草稿。只需一个测试就能判定:命令返回时,数据库中是否有某一行发生了变化?
有些操作不在这道关卡之后,因为它们根本就不是命令:购买套餐、通过 3D Secure 添加银行卡、批准法律文本以及注销账户,都在本人自己的浏览器中进行。对于这些操作,lg handoff-links generate 会返回一个 logistivo.com 链接——免费、不写入任何内容、不携带任何机密——由本人在那里完成这一步。无论标志如何设置,都无法把一笔支付或一次同意变成 API 调用。
从技术上讲,集成可以在每次调用时自动通过关卡,但这并不可取。正确的做法是只对您确知可以撤销的命令自动通过关卡,而把不可撤销的命令转入人工处理队列。
1. 调用 — 在不带 confirm 的情况下调用受关卡保护的命令。什么都不会改变。
2. 阅读概述 — 您会收到一个 409;响应体中的 confirmation.summary 是一句写给人看的话(“About to issue an invoice: X Ltd, 1,200.00 TRY”),而不是原始参数的转储。涉及金额的命令还会带有结构化的预览:明细行、合计和警告。
3. 确认 — 使用 confirm: true(CLI 中为 --yes)重复同一次调用。不可撤销的命令带有相应的标记,确保它们最多只运行一次。
预检:在不执行的情况下查看写入命令会做什么
搭建 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 步骤中是一道有意义的关卡。
1. 带上 dry_run 调用 — 在请求体中加入 "dry_run": true。校验、角色和作用域关卡、目标解析以及点数计算都会运行;命令本身不会运行。
2. 读取 would_execute — 这是唯一需要据以分支的标志。当它为 false 时,would_stop.at 会指出真实调用将在何处停止:idempotency、target_precheck、confirmation_gate 或 arguments。
3. 修正请求体 — arguments.ignored 列出会被悄悄丢弃的字段,missing_required 列出您遗漏的必填字段,would_charge 则说明将扣除多少点数,以及余额是否足够。
4. 去掉 dry_run — 重复上述步骤直到 would_execute 为 true,然后移除该标志并发起真实调用。您在预检期间发送的幂等键并未被占用,因此真实调用会正常运行。
HTTP 始终为 200 — “命令将会失败”永远不会以 4xx 的形式返回——预检本身是成功的,预测结果在响应体中。例外是传输层的拒绝,此时它的行为与真实调用完全一样:404 表示未知命令,403 表示角色/作用域问题,429 表示速率限制。
只读作用域的密钥无法对写入命令进行预检 — 它会收到 403。预检回答的是“如果我现在用这个密钥调用它,会发生什么”;如果给读密钥亮绿灯,而真实调用却返回 403,那恰恰就是预检要防止的意外。
幂等键不会被占用 — 预检期间发送的键不会在台账中创建任何行,已过期的锁也不会被释放。所以请发送您准备在真实调用中使用的那个键:预检会告诉您它是否仍然空闲、是否会重放之前的某次运行,或者是否与另一条命令冲突。
可与 confirm 组合使用 — 同时发送 dry_run 和 confirm,问题就变成了“如果我确认,会发生什么?”。依然不会运行任何东西。
批量预检按批次进行 — commands:batch 也接受 dry_run,但该标志属于批次,而不属于单个条目(在条目上发送会得到 422)。您会得到逐条目的报告以及该批次的总点数消耗;余额不足会被报告,而不是被拒绝。
预检并非免费 — 每次预检都会执行真实的查询(预览、余额),并计入速率限制。不要在每次部署时预检整个目录;只预检您改动过的命令。
幂等性:为什么重试不会产生重复
ERP 不会阅读您的错误消息,看不到您的屏幕,并且会在超时后重新发送同一个请求。本节正是为应对这种行为而存在的。
携带 idempotency_key 的调用最多只运行一次。第二次调用不会重新执行命令,而是返回已记录的结果,状态为 replayed。当网络中断、请求超时,或者队列把同一个任务取了两次时,您得到的是第一次的结果,而不是一张重复的发票。
每条写入命令都应使用一个键。目录中的 read_only 字段免费为您提供了这种区分:每一条 read_only: false 的命令都应该带上幂等键(idempotency key)。
您的重试策略应使用指数退避,并在每次尝试时携带同一个键。每次尝试都生成一个新键,等同于根本没有使用幂等性。不要并行发送同一个键:“最多一次”的保证针对的是顺序重试,而不是两个相互竞争的请求。
陷阱 1——失败也会被锁定 — 如果第一次执行被业务规则拒绝(failed),使用同一个键的第二次调用会返回相同的错误和相同的 error_key,而不会重试。修正参数后再次尝试需要一个新的键。一个键代表的是一次尝试,而不是一个意图。
陷阱 2——较大的结果在重放时没有响应体 — 台账只保存小于 64 KB 的结果。更大的结果在重放时状态为 replayed,但响应体为空。您的集成应依赖 “replayed” 这一信号而不是响应体,并用对应的 get 命令获取数据。
陷阱 3——一个键只属于一条命令 — 用不同的命令发送同一个键会返回 409 idempotency_conflict 以及 conflicting_command;不会运行任何内容,也不会重放任何内容。在两个动词之间共用一个键的客户端是有缺陷的,它会从一个错误中得知这一点,而不是从一次静默的重放中。
陷阱 4——锁定持续 24 小时,而不是永久 — 24 小时之后,同一个键将作为一次新的执行。网络重试会在几分钟内到达;而 ERP 每年循环使用的单据编号不能永远停留在 “replayed” 状态。目录以 idempotency_ttl_hours 公布这一时间窗口。
陷阱 5——服务器错误不会锁定键 — 5xx server_error 不是业务拒绝:键不会被绑定,因此使用同一个键重试时,命令会真正运行。只有 failed 才会锁定(陷阱 1)。
作用范围与格式——您的公司、任意字符串、首选 UUID — 唯一性在(您的公司, 键)上强制执行:其他租户的 INV-1001 永远不会与您的冲突,也永远无法重放您的结果。请使用普通的 UUID,或者在构造上就唯一的组合键,例如 {ERP-document-no}:{verb}。
增量同步与分页
ERP/CRM 桥接程序应该拉取发生变化的内容,而不是每小时拉取全部内容。每个列表命令——loads list、demands list-own、contacts list、invoices list、teammates list、load-groups list、reservations list、drivers list、tenders list、products search、warehouses search——都接受两个共用参数,并返回一个共用字段。
为什么没有 offset:在一张实时变化的表上,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。请根据键做分支,切勿根据文本。
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 中的业务键;它们是不透明的,并且仅属于您的公司。运单、询价、联系人、发票、商品和仓库可以携带您自己的键。
写入时设置 — 以下写入命令都接受可选的 external_ref(最多 120 个字符),并会原样返回它:loads create、demands create、contacts create 和 contacts update,以及 invoices create。
读取时使用 — loads get --external_ref=ORD-2026-0917, invoices get --external_ref=..., contacts get --external_ref=..., demands get --external_ref=... 都可以使用;在 list 和 search 命令上,--external_ref= 是精确匹配的筛选条件。
每家公司内唯一 — 具有相同键的第二条记录会以 422 被拒绝,且 result.error_key = DUPLICATE_EXTERNAL_REF;其他公司的键对您来说会返回“未找到”。匹配不区分大小写(ord-1 = ORD-1)。已归档的记录会保留其键;如需重新使用该键,请先恢复该记录。
同时发送 idempotency_key — 网络超时后的重试会返回第一次的结果,而不是创建重复记录。两者不能互相替代:external_ref 是您的业务键,idempotency_key 标识的是一次尝试。
外发 webhook:事件发生时由我们向您发送 POST
到此为止的一切都是拉取:您提问,我们回答。过去,ERP 桥接程序必须每分钟询问一次,才能得知某个运单的状态发生了变化、某张发票已经开具,或者收到了一份报价。现在不必了:注册一个 https 地址,选择您关心的事件,事件发生时就会收到一个签名的 POST。
推送是在拉取“旁边”新增的,而不是取而代之。增量同步(updated_since + cursor)原封未动,依然是合适的工具:首次完整加载、回填历史数据以及回答“我有没有漏掉什么”,都在那里完成。webhook 将延迟从分钟级缩短到秒级。健康的桥接程序两者并用——webhook 作为触发器,同步作为安全网。
payload 是一个“信号”,而不是记录的副本。它携带标识信息(id、您自己的 external_ref、状态、时间);您用自己的密钥通过 GET 获取详情,而这个调用本身就会经过您自己的授权关卡。因此,暴露面始终停留在标识符层面。有两个字段被有意省略:提交报价的公司身份(盲报价在面板中以化名显示;把身份放进 webhook,会通过第二条通道打破这种隐私)以及预订的联系人信息(没有必要让个人数据多走一条通道)。
事件名称是冻结的。如果某个名称的含义发生变化,就会启用一个新名称,旧名称则会在弃用窗口期内继续存在。向 payload 添加新字段不会提升契约版本——消费方必须忽略它不认识的字段。
GET /api/common/integration-webhooks — 台账,以及事件目录、限制和头名称。每一行都带有其静默原因和 7 天投递摘要。
POST /api/common/integration-webhooks — 201 + { webhook, secret, shown_once: true }。签名密钥只在这里出现。
PATCH /api/common/integration-webhooks/{uuid} — 名称 / 地址 / 事件 / 启用标志。“不会”影响签名密钥。
DELETE /api/common/integration-webhooks/{uuid} — 删除订阅:该行被软删除(历史记录仍可查询),待处理的投递会被取消。
POST /api/common/integration-webhooks/{uuid}/rotate-secret — 201 + 一个新的签名密钥。旧值在那一刻失效。
POST /api/common/integration-webhooks/{uuid}/test — 一个 ping 事件——真实的签名、真实的路径、真实的重试时间表。
GET /api/common/integration-webhooks/{uuid}/deliveries — 最近的投递:状态、尝试序号、HTTP 状态码、耗时、错误标签。
POST /api/common/integration-webhooks/deliveries/{uuid}/replay — 重新发送单次投递:event_id 被“保留”,投递 id 是新的,payload 原样复制。
事件目录
下面 13 个事件中的每一个,都对应一个“真正”会被派发的事件类。目录里没有“有了更好”的名称:一个宣布了却从未触发的事件,就是集成方要永远等待的事件,而这种失败是无声的。这张表同样不是手写的——每次加载页面时都从实时目录中生成。
invoice.payment_recorded 被有意排除在外:该事件类存在于代码中,但没有任何地方派发它。付款事件会在该类真正被触发的那一天加入——不会提前。过早宣布一个事件,比永远不加入它更糟糕。
load.created — A load became visible to your company (created by you or shared with you). (load)
load.status_changed — A load moved to a new status (pending, in_transport, transit, done). (load)
load.driver_assigned — A driver was assigned to a load. (load)
demand.created — A freight demand was created by your company. (demand)
demand.status_changed — A freight demand changed status. (demand)
demand_bid.created — A bid was placed on a demand you are party to. (demand_bid)
demand_bid.revised — A bid was revised (a new revision replaced the previous one). (demand_bid)
demand_bid.accepted — A bid was accepted. (demand_bid)
invoice.created — An invoice draft was created. (invoice)
invoice.issued — An invoice was issued (it now carries an invoice number). (invoice)
invoice.cancelled — An invoice was cancelled. (invoice)
warehouse_reservation.created — A warehouse dock/area reservation was created. (warehouse)
warehouse_reservation.status_changed — A warehouse reservation was approved, rejected or otherwise moved. (warehouse)
验证签名
每个请求都带有 X-Logistivo-Signature 头:t=,v1=。被签名的字符串是 ".",算法为 HMAC-SHA256。v1 前缀使该方案可以进行版本演进:如果将来出现第二种方案,头中会携带 t=…,v1=…,v2=…,您选择自己认识的那一个即可。
我们发布了两个无依赖的参考接收端,一个用于 Node,一个用于纯 PHP。两者都应用了上述四条规则,并可通过 --selftest 自测:有效签名、被篡改的请求体、错误的签名密钥、超出窗口的时间戳、格式错误的头、重新序列化陷阱,以及两种重复(同一次投递 / 同一个事实)。验证器与我们自己使用的代码完全对应——我们自己也在消费我们发布的契约。
验证原始(RAW)请求体 — 签名是基于字节计算的。对请求体进行解码再重新序列化(JSON.stringify(req.body)、json_encode($request->all())),会把相同的“数据”变成不同的“字节”,签名就不再匹配。在 Node 中,陷阱在于数字格式(线路上的 1.50 会变成 1.5;大整数会丢失精度);在 PHP 中,陷阱在于字符转义(/ 会变成 \/,İ 会变成 \u0130)。在 Express 中请使用 express.raw,在 Laravel 中请使用 $request->getContent()。这是编写接收端时最常见的错误。
检查时间戳 — t 位于签名“之内”。只验证签名的话,任何截获了有效请求的人都可以在几小时后重放它,而接收端会把它当作一个经过验证的事件。即使签名正确,也请丢弃任何 |now − t| > 容差的请求。建议的窗口为 300 秒。
以恒定时间比较 — hash_equals / timingSafeEqual。使用 == 比较会让攻击者逐字节猜出签名。
按 event_id 去重,而不是按 id — event_id 标识的是“事实”:两个订阅者收到同一事件时它是相同的,并且在重放时会被“保留”。id(= X-Logistivo-Delivery)标识的是“投递”,在重放时会改变。请用 event_id 回答“我是否已经处理过这个”;若用 id 来回答,重放就会让同一项工作执行两次。
投递、重试与静默
您的接收端并不总是在线。这条通道考虑到了这一点:暂时性的失败会进入重试时间表,永久性的失败会使订阅被静默——而静默的“原因”始终会被记录。
静默原因是机器可读且稳定的(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 等内部后缀会被拒绝——在查看解析结果之前就拒绝这种意图,因此分离视图(split-horizon)DNS 无法突破这道关卡;
IP 字面量以及 DNS 解析的“所有”记录都必须是公网地址。如果一个名称同时解析到公网地址和私网地址,没有人会问我们该选哪一个 → 该名称直接被拒绝;
在投递时,地址只解析一次,连接被固定到经过验证的地址上:DNS 重绑定的窗口因此被关闭;
接收端的响应“正文”永远不会存储在任何地方(只保存状态码、耗时和简短的错误标签)——因此,地址关卡漏洞真正的价值所在,即“读取”路径,始终是关闭的。
我们有意不提供“允许私网地址”的配置开关:这样的开关总有一天会被意外地开着。
只返回“一次”,仅在创建订阅时以及执行 rotate-secret 时返回。它在服务器上加密存储,永远无法读回;没有“再次显示”。
lg 会把它打印到屏幕上并就此留在那里——不会把它写入任何配置文件或缓存文件。
如果丢失,请轮换它;旧值会“在那一刻”失效。为了实现无缝切换,您的接收端应在过渡期间同时尝试新旧两个密钥。
更改地址“不会”影响签名密钥:像“URL 搬家了”这样的日常维护,不应破坏接收端的验证。
健康与状态:桥接程序悄然停摆,不应由别人先于您发现
集成桥接程序很少会轰轰烈烈地宕掉。它通常是在凌晨悄无声息地停下来:令牌过期了,密钥所代表的那个人离开了团队,作用域被收窄了,或者接收端点开始返回 403。最先察觉的几乎总是客户。lg status 的存在,就是为了扭转这个顺序。
一条命令同时回答两个问题,因为在故障期间这两个问题会在同一时刻被提出:平台是否正常运行,以及我的桥接程序是否健康。平台状态这一行无需令牌即可使用——故障期间,令牌本身就是首要怀疑对象,如果把状态查询与令牌绑定,恰恰会在您最需要答案的时候得不到答案。
健康摘要不维护新的台账;它把三个现有来源汇总成一句话:每日使用计数器(您调用了多少次、失败了多少次)、请求台账(哪个请求、何时、因何被拒绝)以及外发 webhook 投递台账(事件是否到达了接收端)。错误率始终从每日计数器读取;明细台账设有上限,达到上限时会明确说明。
同样的摘要也会出现在面板中:在 Settings › Integration › Keys(设置 › 集成 › 密钥)下,每一行都带有一个徽章,下方注明原因。阈值不在客户端计算;服务器判定的级别是什么,面板和 lg status 就显示什么,因此两个界面对同一个密钥永远不会给出不同的说法。
您的监控程序不需要令牌。该端点只返回状态词;不包含版本、主机名、队列名称、任务数量、错误文本或客户数据——也不可能包含。
健康摘要每次请求只执行固定数量的查询;查询次数不会随密钥数量的增加而增长。如需详情,请用 lg logs 查看该密钥最近的请求,用 lg webhooks list 查看外发桥接。
健康 — 没有测得任何故障,并且我们掌握成功的证据:台账中有一次成功的调用,或者计数器中的流量始终没有错误。
需要关注 — 某些东西开始出问题了:错误率或连续失败次数越过了阈值,请求在关卡处被拒绝,密钥即将过期,或者一个原本定期通信的桥接程序沉默了。
故障 — 桥接程序此刻无法正常工作:令牌被意外吊销,已关闭的密钥仍在被调用,连续五次失败,错误率超过百分之五十,或者某个 webhook 订阅被静默。
已关闭 — 密钥是被有意关闭的,并且没有人在调用它。这是一个决定,而不是故障——所以不会显示为红色。
无数据 — 没有任何测量数据:该密钥从未被调用过,或者测量本身失败了。这两种情况都不是绿色。
不出现虚假的绿色。健康徽章需要经过测量的成功证据;一个从未被调用过的密钥永远不会变绿,因为没有任何一次测量能证明它可以工作。
不出现虚假的红色。您有意关闭的密钥显示为“已关闭”。把一切都涂成红色会让红色失去意义;已关闭的密钥只有在关闭后仍被调用时才会变红——而那时,确实有一个桥接程序坏了。
“无法测量”与“没有数据”不是一回事。如果服务器端的查询失败,该行不会悄悄显示为零;它会说明测量无法进行。
沉默总会被报告,但从不会被盲目地变成警告。一个只在月末运行的桥接程序沉默三十个小时是正常的;而一个在过去七天中至少有五天都在通信的桥接程序沉默下来,就是故障。节奏是测量出来的,而不是假定的。
状态查询本身不会污染健康数据。lg status 发出的调用会出现在请求台账中,但不计入健康统计——否则,您自己那次成功的状态查询就会重置连续失败计数,掩盖掉这个界面本应展示的故障。
每一行都是测量出来的:对数据库执行一次真实查询,真正构建一次命令目录,真正读取队列工作进程的实时记录。没有任何东西是假定的。
响应本身也是一次测量:如果您能读到响应体,就说明 Web 层在运行。
顶层状态只由必需组件推导。队列停止时,答案是 degraded(性能下降),而不是 down(宕机)——同步的 API 调用并不需要队列,宣布平台宕机会是一次误报。
当队列状态无法测量时,顶层状态保持不变:不知道,并不等于测得某样东西坏了。
如果平台宕机,该端点返回 HTTP 503。响应体不使用信封,以便监控工具无需解析即可告警,并且该响应永远不会被存入任何缓存。
错误与退出码
机器据以分支的是稳定的字符串。error 字段中的文本面向人类,经过本地化,并且会在不另行通知的情况下变化——基于消息文本做分支的集成不受支持,它因此出现故障也不算缺陷。
两套分类,两个字段。error_code 是传输层(上表),是您首先要据以分支的字段。error_key 是 failed 内部稳定的业务规则键——INSUFFICIENT_CREDITS、NOT_FOUND、DUPLICATE_CONTACT、INSUFFICIENT_STOCK——它以字典形式发布在目录中(error_keys)以及下方。尚未输出键的命令会返回 error_key: null;请将字典中不存在的键视为一般性失败。
ok — HTTP 200 · error_code — · CLI 0 · —
replayed — HTTP 200 · error_code — · CLI 0 · 幂等重放;工作“没有”再次执行。
failed — HTTP 422 · error_code failed · CLI 1 · 不可以——被业务规则拒绝(参见 error_key)。在参数改变之前重试毫无意义。
needs_confirmation — HTTP 409 · error_code needs_confirmation · CLI 4 · 可以,带上 confirm: true 即可。
idempotency_conflict — HTTP 409 · error_code idempotency_conflict · CLI 2 · 不可以——该键最初用于另一条命令(conflicting_command)。请生成一个新键。
forbidden — HTTP 403 · error_code forbidden · CLI 3 · 不可以——被角色关卡拦截,或者用只读作用域的密钥调用了写入命令。
not_found — HTTP 404 · error_code not_found · CLI 2 · 不可以——命令名称错误或已被移除。
(schema 校验) — HTTP 422 · error_code invalid_request · CLI 2 · 不可以——请求体或某个参数未通过 schema 校验(errors{});这不是业务规则问题。
server_error — HTTP 500 · error_code server_error · CLI 6 · 可以——使用同一个幂等键进行指数退避重试;该键没有被锁定。
401 unauthenticated — 令牌已过期或已被吊销。重试无济于事;必须更换令牌。
429 rate_limited — 该令牌受到速率限制。响应始终带有 Retry-After,以及包含 retry_after、limit 和 bucket 的响应体;请遵守它,而不要自己设定固定的延迟。lg 会等待并最多重试三次,然后以退出码 5 退出。
5xx server_error / 网络错误 — 使用指数退避和同一个幂等键重试。更换键会重新执行服务器可能已经完成的工作。lg 会重试三次(1 s、2 s、4 s),然后以退出码 6 退出,error_code 为 network_error 或 server_error。
稳定性承诺
集成契约中最昂贵的问题是:“我今天写的代码明天还能运行吗?”一个数字就能回答它:目录中的 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 也是如此——两者都会发出警告。
不变 — 新命令 · 新的可选参数 · 新的响应字段 · 新的错误键 · 新的端点 — 什么都不用做。您必须忽略不认识的字段;遇到未知字段就失败的解析器不符合规范。
不变 — 弃用“公告”:通知某条命令即将移除 — 您的代码继续运行。请在日历中记下一项任务——窗口期至少为 6 个月。
增加 — 移除命令 · 停用旧的 CLI 名称 · 删除响应字段 · 将可选参数改为必填 · 收窄枚举 — 这意味着您错过了窗口期;通知曾通过三个不同的地方送达您。
命令的 API 名称(例如 list_loads)永久冻结;HTTP 调用中使用的就是这个名称。
error_code(传输层)和 error_key(业务规则)是稳定的字符串。可能会出现新的值——请将字典中找不到的键视为一般性失败,而不是破坏性变更。
HTTP 状态与响应体中 status 字段之间的对应关系是固定的。
版本号永远不会减小,并且在每个响应中都可读取——包括没有响应体的 304 和 429。
错误和描述的“文本”。它经过本地化,并会在不另行通知的情况下变化;不支持根据消息文本做分支。
“响应中不会出现您不认识的字段”这一假设。添加字段并不会提升版本。
把自增 id 当作业务键。请用 external_ref 携带您自己的键。
由类名派生的动态错误键;它们不属于契约的一部分。
命令身份表
下表并非手写:每次提供本页时,都会从实时命令注册表生成。服务器上新增的命令会自动出现在这里。“关卡”列告诉您一条命令是否请求确认,以及其效果能否撤销;“角色”列告诉您哪些账户类型会在其目录中找到它。徽章标出了需要 manager 级密钥的命令、需要文件的命令,以及只能从 lg 运行的命令。
命令按功能分组,每个功能有独立页面。选择一个功能即可打开其命令表。
API 名称(list_loads)是冻结的,永远不会改变;HTTP 调用中使用的就是这个名称。CLI 身份(loads list)受版本管理策略约束:一旦公告,只能随着版本提升和迁移窗口而改变,在此期间目录会以别名形式继续提供旧的组合。这里的描述来自每条命令自身的记录,并经过缩短——如需完整文本、参数类型和枚举值,请读取目录端点或运行 lg help 。仅限联盟推广账户的命令未在此列出;联盟推广账户可在自己的目录中看到它们。
货物与跟踪 — 创建货物、相关方、单证、跟踪链接、签收、预计到达时间与异常。 115 个命令 — /zh/developers/cli/loads
边境与海关 — 过境准备检查、边境与港口等待时间、出口单证、U-ETDS 申报。 42 个命令 — /zh/developers/cli/border
询价与报价 — 发布运输需求、征集与提交报价、招标、网络中的承运人。 42 个命令 — /zh/developers/cli/quotes
运价卡与销售报价 — 约定运价卡、报价瀑布流以及给客户的销售报价。 57 个命令 — /zh/developers/cli/pricing
车队与司机 — 司机、车辆、费用票据、司机账户、行程规划与申根天数。 115 个命令 — /zh/developers/cli/fleet
仓库与库存 — 仓库、预约、月台预约、门岗屏幕、产品、库存与托盘。 69 个命令 — /zh/developers/cli/warehouse
会计与开票 — 发票、采购发票审核、Paraşüt、记账凭证、收款与付款、利润率。 95 个命令 — /zh/developers/cli/finance
消息与邮件 — 货物聊天、私信、邮件草稿与收件箱、通知。 58 个命令 — /zh/developers/cli/messages
关税与贸易措施 — HS 编码搜索、进口关税、反倾销措施、碳排放报告。 20 个命令 — /zh/developers/cli/tariffs
公司与团队 — 公司通讯录、合作关系与文件、子公司、团队成员与邀请。 65 个命令 — /zh/developers/cli/contacts
自动化与报表 — 自动化规则、自定义报表、Excel 与 PDF 文件、工作计划。 27 个命令 — /zh/developers/cli/automation
账户与集成 — 账户与语言设置、集成密钥、套餐、积分与钱包。 16 个命令 — /zh/developers/cli/account
ERP 与 CRM 集成 — 身份:没有服务账户,而是使用真实用户
ERP 或 CRM 以一名真实公司用户的身份连接 Logistivo,持有一个从面板签发的个人访问令牌。我们绝不会创建合成的服务账户——不属于任何公司、不受作用域约束、无人对其负责。
这是架构问题,而不是偏好问题。多租户隔离完全建立在用户所属的公司之上;对于没有公司的身份,隔离作用域就会失效,而该令牌上的一次错误查询就会读取到不属于它的数据。第二个原因是审计:台账中的用户列把“谁执行了这个”与一个人联系起来;服务账户会让这一列失去意义,并让一个负责开票的集成无人负责。第三个原因是吊销:如果令牌属于某个人,那么当这个人离开时,集成也会随之沉默。没有主人的桥接程序,正是那种会悄无声息地持续写入多年的桥接程序。
实践中:公司在面板中创建一个普通用户(例如由一名具名员工负责的 “ERP Bridge”),为其分配一个范围很窄的角色,从该用户的会话中签发令牌,并将其放入 ERP。
该用户在权限系统中可见,其权限可以被裁减,其令牌也可以单独吊销。被禁止的不是创建账户——而是创建一个不绑定到租户的账户。
一个令牌只用于一个集成。如果两个系统共用一个令牌,吊销的粒度就不复存在:切断 CRM 就意味着同时切断 ERP。
ERP 与 CRM 集成 — 版本管理与弃用
目录响应带有一个整数 contract_version;命令条目带有 since、deprecated_at 和 replaced_by。契约版本只会因破坏性变更而提升。
以下情况版本“不会”提升:新命令、新的可选参数、响应中的新字段。消费方必须忽略它不认识的字段;遇到未知字段就报错的客户端不符合规范。
以下情况版本“会”提升:移除或重命名命令、删除响应字段、将可选参数改为必填、收窄枚举。旧的形式会借助 deprecated_at 和 replaced_by 继续存在至少两个日历季度(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 的命令,也会返回租户自己的业务键(SKU、代码、税号),以便 ERP 在自己一侧进行匹配。
ERP 与 CRM 集成 — 分页、筛选与增量同步
列表命令接受 limit 并返回 count。对于夜间同步,契约承诺以下内容;已采用该契约的列表命令会在其 JSON Schema 中声明 cursor 和 updated_since,在此之前,请把它视为一个小窗口(上限 20 行,没有游标)。
请求:limit(1 到该命令的上限)加上 cursor(不透明、只能向前、由服务器签名)。“不”使用 offset——在实时变化的表中,offset 会发生偏移;在两页之间插入的记录会让 ERP 跳过一行或重复统计一行,而且是悄无声息的。
响应:{ count, total?, next_cursor|null }。count 是本次响应中的行数;当 next_cursor 为 null 时,列表已完整。请将 next_cursor 原样传回——它不是页码,也不该由您来构造。
被篡改或来自他处的游标会以 422 invalid_request 被拒绝;游标绑定到接收它的公司,无法用于翻阅其他租户的数据。
筛选:使用 JSON Schema 中的具名参数,以 AND 组合。没有自由的查询语言——DSL 会成为我们必须防御的第二个查询面。
增量同步:updated_since(ISO-8601,UTC)加上游标。保存您见过的最新 updated_at,并在下一次运行时传回;否则,每个 ERP 每小时都会重新获取全部内容。
外部引用:写入命令接受 external_ref(您自己的单据键),在每家公司内唯一;使用相同 external_ref 的第二次创建会被拒绝,而不是生成重复记录,list/get 也会返回它,以便您在自己一侧匹配记录。
ERP 与 CRM 集成 — 速率限制
限制的键是令牌,而不是 IP:ERP 是从单一 NAT 后面访问的,基于 IP 的限制会把整个公司算作一个用户。两个集成使用两个密钥,就永远不会互相消耗对方的配额——这是“一个集成一个密钥”的第二个理由。
无需认证的发现(public/cli/catalog):每分钟 30 次。它是一本字典,而不是数据源;在编写桥接程序时读取一次即可,切勿在生产循环中读取。
目录端点(GET common/commands、GET common/commands/{name}):每个令牌每分钟 120 次。目录很少变化,对 If-None-Match 会返回 304;不要在每条命令之前都重新获取它——lg 会将其缓存一小时。
读取命令(read_only: true 的 POST common/commands/{name}):每个令牌每分钟 120 次。
写入命令(read_only: false 的 POST common/commands/{name};未知名称也计入此类):每个令牌每分钟 30 次。写入有副作用;失控的循环会被计费。
消耗点数的命令(目录行中的 credit_cost 不为零——例如 tariffs inquiry 和 export-documents generate):真正的限制是“点数”,而不是请求次数。一个 200 响应可能已经消耗了点数。
每家公司的每日上限,与面板共享:向公司外部人员发送电子邮件或推送的命令共用每天 300 条外发通知的额度,启动付费集装箱或船舶追踪的命令共用每天 100 次的额度。超过上限时,命令会返回 DAILY_LIMIT_REACHED 以及 retry_after;文件上传有自己的上限(参见“需要文件的命令”)。
429 始终带有 Retry-After 以及响应体 { error_code: "rate_limited", retry_after, limit, bucket };请遵守它,而不要自己设定固定的延迟。目录在 rate_limits 下公布当前的数值。
ERP 与 CRM 集成 — 我们不会做的事
这往往是契约中最有用的部分:知道什么永远不会到来,您就可以围绕它进行设计。
没有服务账户,也没有任何不绑定到租户的主体。
不通过 API 或聊天处理支付、卡号或法律同意。这些步骤保留在本人的浏览器中;命令会把链接交给您。
没有第二条路径:没有直接的数据库访问,没有 shell 访问,也没有绕过唯一强制执行点的批量端点。角色关卡、确认关卡、幂等性和审计台账只在那里强制执行。
不支持根据错误消息文本做分支;文本经过本地化,并会在不另行通知的情况下变化。
没有 offset 分页。
不支持在您的 ERP 中把表层 id 用作业务键。
外发 webhook 不会被硬塞进这份契约——但它们现在已经“存在”,并在本页中有文档说明(见上文的 webhook 一节)。目录是一个“拉取”接口,而事件流是一份“独立”的契约:事件名称和 payload schema 按各自的规则进行版本管理,与命令目录的契约版本无关。
机器可读的目录
本页是为人编写的。对于 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 助手以进行注册和货运询价,是一个独立的通道,有自己的页面:
目录无需认证;执行则需要认证。不存在代表智能体运行命令的途径——运行时使用的始终是用户自己的身份。
Logistivo 的密码、验证码或访问令牌永远不会经过聊天。请勿构建任何索要、生成或转交它们的流程。
一条命令是否不可撤销,写在目录中。对于 irreversible: true 的命令,切勿建议“我们试试看”。
credit_cost 不为零的命令(例如 tariffs inquiry 和 export-documents generate)会产生金钱上的结果;请勿在自动化循环中调用它们。
支付、卡号和法律同意永远不经过聊天或智能体。请改为提供 handoff-links generate 返回的链接;由本人在自己的浏览器中完成这一步。
使用用户密钥行事的智能体应首先调用 users get:它会返回角色、密钥的访问级别、实际生效的权限,以及是否有待处理的同意或手机验证正在阻止写入——提前预判拒绝,而不是一次次去碰壁。
本页的纯文本副本发布在 /cli.md 上;如果您解析 markdown 比解析 HTML 更可靠,请使用它。
机器可读的定义:OpenAPI 3.1 与 Postman
上面的目录是 Logistivo 自有的格式。同样的信息还以两种您的工具早已熟悉的行业标准格式发布:OpenAPI 3.1 定义和 Postman 集合。两者都不是手写的——都在每次请求时从实时命令注册表生成,因此不会过时。
这份定义“就是”目录,而不是第二个现实。每条命令都以一个 POST /api/common/commands/ 操作出现;请求体 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 可以零警告通过。
GET /api/common/spec/openapi.json — 适用于您令牌所属角色的 OpenAPI 3.1 定义。带有 ETag;If-None-Match 会得到 304,因此您不必在每次构建时都重新下载。
GET /api/common/spec/postman.json — 范围相同的 Postman v2.1 集合,带有 base_url 和 token 变量,文件夹已按命令域分组。
GET /api/public/cli/openapi.json — 无需认证的版本——三个角色的并集。用于在拿到令牌之前设计桥接程序并估算成本。
GET /api/public/cli/postman.json — 无需认证的 Postman 集合:一个可以直接交给团队的文件。
761 个操作 — 721 条命令 + 36 个 REST 与控制平面操作 + 4 个目录与身份端点。本页上的数字不是手工输入的;它们在每次请求时从实时文档中统计得出,因此某条命令上线的当天,这里的数字也会随之增加——而且加起来是吻合的。
安全方案 — bearerAuth:为真实用户签发的 Passport 令牌。只读作用域的密钥只能调用标记为 x-logistivo.read_only: true 的操作;写入尝试会在确认关卡“之前”返回 403,因此只读密钥永远不会看到 409。
每个错误分支都写得清清楚楚 — 每个操作都分别描述 401/403/404/409/422/429/500。409 的两种含义(需要确认 / 幂等冲突)以及 422 的两种含义(schema 错误 / 业务拒绝)在文档中是分开的,因此您的生成器不会把它们合并成一个分支。
没有时间戳 — 文档不包含生成时间。相同的目录会产生相同的字节,这正是 ETag 真正起作用的原因,也是您提交到版本控制中的定义不会在每次下载后看起来都“有变化”的原因。
我们没有编造产品 payload — 在 REST 写入端点上,只描述了契约字段(external_ref);请求体的其余部分以 additionalProperties: true 保持开放,并引导读者参阅产品文档。一份不完整但真实的定义,胜过一份完整但编造的定义。
每个操作的错误键列表“并不”详尽 — x-error-keys 只列出从命令自身记录中可以确定推出的键,并通过 x-error-keys-exhaustive: false 声明这一点。完整的字典位于文档根部;请将任何您不认识的键视为一般性失败。一份捏造的“完整列表”会诱使您永远不写 default 分支。
发现工具不在定义中 — search_commands、run_command 和 list_capabilities 只存在于聊天循环内部,无法通过 HTTP 调用。如果把它们包括进来,您的生成器就会写出三个永远无法工作的方法。
代码生成:从定义生成类型化客户端
您已经有了定义;现在用它生成可运行的代码。`lg codegen` 读取 OpenAPI 文档,并写出一个单文件、无依赖的客户端——TypeScript(类型声明加上一层轻量的调用封装)或 PHP(带有 PHPDoc 数组形状的客户端类)。无需 `npm install`,也无需 composer: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` 中制造噪音,而真正发生变化的那一件事——契约——始终清晰可见。
1. 固定定义 — 定义按您的角色生成;其中的每个操作都可以用该令牌调用。请提交该文件。 lg login --api-key= lg spec --out=logistivo-openapi.json
2. 生成客户端 — 输出一个文件,把您所固定的定义中的“每一个”操作都作为方法包含在内:您的角色可调用的命令、承载集成契约的 REST 端点,以及发现端点。数量取决于“您的”角色,而不是平台总数——目前,货主密钥会生成 646 个命令方法,承运商为 621 个,报关行为 392 个。如果从无需认证的公开定义生成,上限为 761 个操作。 lg codegen ts --from=logistivo-openapi.json --out=logistivo-client.ts lg codegen php --from=logistivo-openapi.json --out=LogistivoClient.php --namespace="Acme\\Logistivo" # or straight from the server, without downloading first: lg codegen ts --out=logistivo-client.ts
3. 先验证,再使用 — 如果生成的代码无法编译,问题出在我们而不是您:定义的完整性由服务器上一项可运行的检查来保障。 npx tsc --noEmit --strict --target ES2022 --module ESNext --moduleResolution bundler logistivo-client.ts php -l LogistivoClient.php
每个操作一个方法 — 文档中的每条命令、每个承载集成契约的 REST 端点,以及发现端点。从您角色的定义生成,您只会得到您可以调用的内容(货主为 646 条命令);从公开定义生成,您会得到全部 761 个操作。服务器上新增命令的当天,重新生成即可将其纳入;无需等待客户端发布。
参数类型 — 每条命令的 `args` schema 都会变成一个接口(在 PHP 中为数组形状)。必填字段保持必填,枚举变为联合类型。在 TypeScript 中,遗漏必填字段会产生编译错误;在 PHP 中,您的 IDE 和 PHPStan 会看到相同的形状。
错误类 — 传输层分类(`error_code`)和业务分类(`error_key`)是两个独立的字段;确认关卡和速率限制是两种独立的错误类型。错误键联合类型对未知值保持开放——当服务器声明一个新键时,您的代码不会因此无法编译,而是落入 `default` 分支。
正确的重试策略 — 自动重试只适用于安全的调用:读取,以及携带幂等键的写入。一次没有键的写入超时,并不意味着“什么都没写入”,因此客户端永远不会盲目地重复它。遇到 429 时,它会等待服务器给出的 `Retry-After`,而不是自己编造一个延迟。
结果体没有类型 — 命令结果以 `unknown`(在 PHP 中为 `mixed`)返回,原因与定义本身相同:结果的形状是命令的业务输出,不属于契约的一部分。一个靠猜测得出的结果类型,在某个字段第一次移动时就会开始说谎。
生成的文件不应手工编辑 — 它是输出,而不是源代码。如果您需要额外的行为,请包装生成的类;您在其中写的任何内容都会在下一次生成时丢失。
不生成发现工具 — `search_commands`、`run_command` 和 `list_capabilities` 只存在于聊天循环内部,无法通过 HTTP 调用;它们不在定义中,因此也不在客户端中。如果把它们包括进来,就意味着要写出三个永远无法工作的方法。
诚实的范围说明
我们宁愿让这一节变长,也不愿让它变短。一份集成契约的价值,与其说在于它承诺了什么,不如说在于它多么清楚地说明了自己不做什么。
CLI 在租户用户的上下文中运行 — 每条命令都在所出示令牌对应用户的公司和角色下运行。平台运营者模式——一种跨公司读取的管理模式——不在这个接口面之内,也不会从这里开放。
您的命令列表取决于您的角色 — 货主账户可看到 646 条命令,承运商 621 条,报关行 392 条,联盟推广账户 55 条。如果您的目录中缺少某条命令,请先检查角色;如果命令已列出却被拒绝,请检查密钥的作用域和访问级别。司机账户完全无法访问这个接口面。
部分命令会消耗点数 — 税则查询、单证生成以及其他少数由 AI 支持的命令,会从您套餐的点数余额中扣除。每个目录行都带有 credit_cost {mode, credits}:fixed 表示每次调用的确切扣费,read_only 永不扣费,computed 表示扣费取决于具体调用——此时 credits 为 null,真实数字会显示在确认卡片上。预检(dry_run)会告诉您一次调用将扣除多少点数,以及您的余额是否足够。
集成密钥无法驱动面板聊天 — 面板内的 AI 助手是给人用的。用集成密钥启动或继续一次助手运行会以 403 被拒绝;智能体应使用命令端点、lg 或 MCP 通道,在那里每条命令都以密钥的访问级别运行,其写入会被记录为集成写入。
目录并不取代现有的 REST API — 支撑 Logistivo Web 和移动应用的 REST 接口面保持原样,并继续遵守向后兼容规则。命令目录不取代资源的 CRUD;它是“动词”层——完成一件事的唯一的、经过审计的途径。
列表命令目前返回小窗口 — 在某个列表命令于其 schema 中声明 cursor 和 updated_since 之前,它的上限是 20 行,且没有游标。它并非为提取您数据的完整副本而设计;增量同步正在逐条命令地推广。
常见问题
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.