开发者 · 集成

把按订单行路由接进你的 OMS/ERP:与中国履约仓之间的集成数据契约(设计伙伴阶段 + AEO FAQ)

作者 Alice Zhou2026-09-129 分钟阅读

WooliiPorter把按订单行路由接进你的 OMS/ERP:与中国履约仓之间的集成数据契约(设计伙伴阶段 + AEO FAQ)

先给结论:按订单行路由不是后台里的一个开关,而是一份数据契约。只要一张订单里可能同时存在“备货行”(在中国仓收货、留证、合箱后出库)和“供应商直发行”,你的 OMS/ERP 就必须把每个订单行当成独立路由的对象来处理:独立状态、独立追踪、独立异常路径。本文讲的是实现层——要定义哪些对象和字段、事件语义怎么设计才不会被重复发货和状态乱序拖垮,以及今天能接什么、不能承诺什么。

如果“要不要按行建模”还没想清楚,先读备货履约 vs 供应商直发与混合订单按行路由;如果方向已定但不确定先清理哪些数据,看接入前要准备的 5 类主数据;如果关注自动化交换的字段清单,看MCP/API 时代的履约数据。本文假设业务决策已经完成,你手上正拿着一份表结构图。

为什么“按行”必须是数据模型的属性,而不是界面上的一列

举个例子:一张订单里,某个 SKU 的 6 件已经在中国仓备货,另一个 SKU 的 2 件只能由供应商直发。同一个订单号,两套履约模型,两个追踪号,两个异常责任人。如果你的订单表只有一个发货状态字段,你无法表达“第 1 行已出库、第 2 行还在等供应商交运”这件事,最后只能把它塞进备注文本,让客服、财务对账和你的看板各自去猜。

后果很具体:客服无法自动回答“我的货到哪了”;部分退款会被归到错误的行;你的系统与履约方之间的账目悄悄漂移,直到旺季才暴露。

所以路由模式要落在行上:每一行携带一个 routing_mode(备货履约 / 供应商直发),在订单进入时确定,之后只能通过可审计的变更事件修改。

集成数据契约:写代码前先定下来的对象

下面这些对象是我们与集成伙伴逐项过一遍的内容。字段命名由你决定,语义不能省。

对象	关键字段	归属	为什么重要
SKU ↔ 供应商 ↔ 路由映射	sku、supplier_id、routing_mode、是否可合箱、电池/危险品标记、尺寸与重量来源	商户(我方校验)	让路由成为一次查表,而不是打包时的临场判断
订单行	order_id、line_id(稳定)、sku、订购数量、已出库数量、routing_mode、拆分序号、状态	商户 OMS	稳定的 line_id 才能在改单、拆行、取消后仍然对得上
包裹 / 货件	shipment_id、关联 line_ids、模式、实际重量、尺寸、封箱时间、出库时间	履约方	追踪号挂在这里,不是挂在订单上
证据记录	evidence_id、parcel_id、类型(拍照/点数/称重)、采集时间、操作人引用	履约方	让证据链可以被系统读取,而不只是给人看图
追踪记录	shipment_id、承运商、tracking_number、tracking_url、首次揽收扫描时间、状态	承运商(经履约方)	按包裹回写,读取时再聚合到订单行
异常事件	exception_id、关联 line_id 或 parcel_id、异常类型、发现时间、需要谁处理	双方共享	短装、破损、地址不可达、清关卡点、供应商延迟都有主

其中两点值得特别强调。第一,SKU 到供应商的映射由商户维护:你知道哪个供应商做哪个 SKU、哪些 SKU 你希望备货;我们负责用实际收到的包裹去校验这份映射,并对冲突(一个 SKU 映射到两个供应商、SKU 缺失、数量不符)提出反馈。第二,尺寸与重量的来源必须事先声明:是以你提供的数据为准,还是以我方入仓实测为准,两者混用会让对账无从下手。

状态机与追踪号回写:两条路径不要混用一套状态

履约模式	状态序列	终态
备货履约	已收货 → 已留证 → 待合箱 → 已合箱 → 已出库 → 运输中 → 已妥投	已妥投、已取消、已退回
供应商直发	指令已发出 → 供应商已确认 → 已揽收 → 运输中 → 已妥投	已妥投、已取消、异常终止

每一次状态迁移都应带上时间戳、触发方(仓库扫描 / 商户接口 / 承运商)与来源系统。不要让系统只靠追踪号去反推状态:追踪号告诉你运输发生了什么,它不会告诉你包裹是否已入仓、是否完成留证、是否还在等待合箱。

追踪号的规则只有一条:一张订单可以有 N 个包裹、N 个追踪号。追踪号存在包裹层,在读取时聚合到行,永远不要用一个订单级字段去覆盖它。

关于重量:合箱可能改变一个货件的体积重,从而可能改变计费结果,但这不等于运费一定会下降,具体取决于包裹的实际构成与承运商的计费规则。机制细节见体积重与计费重。

异常事件建议至少覆盖这几类:入仓短装(实收数量小于预期)、收货破损、地址不可达、清关或单证卡点、供应商未按时交运。每一条异常都要有一个“下一步由谁处理”的字段,否则它只会变成一封邮件。

事件设计与幂等:避免重复发货、状态乱序、追踪号错配

事件信封:每条事件包含 event_id、event_type、occurred_at(UTC)、关联实体、state_version 与载荷。消费方按 event_id 去重,按 state_version 应用,这样乱序到达的事件不会把状态回滚到旧值。
命令要带幂等键:创建收货指令、修改行、取消行、改地址、请求出库这类命令都应携带幂等键。重试一次命令,不应产生第二个包裹或第二次出库。
部分数量要能表达:按行记录已出库数量,直到已出库数量等于订购数量,或剩余部分被明确取消,这一行才关闭。出库之后再取消不是取消,而是退货。
证据链要可被读取:拍照、点数、称重都生成为带时间戳与关联包裹的结构化记录,让商户系统可以直接渲染“这一件是什么时候、由谁、以什么结果核验的”。

上线前的测试用例建议至少覆盖这些场景,它们恰好是最容易出问题的地方:

混合订单在收货后修改某一行的数量;
两行订单中取消其中一行;
一行拆成两个包裹分别出库;
入仓短装,实收小于预期;
收货后、出库前修改收件地址;
同一条事件被重复投递;
事件乱序到达(出库事件早于留证事件);
已妥投但追踪号尚未回写;
供应商直发行长时间没有承运商扫描。

同时,把“验收通过”的定义写成文字:哪些事件、哪些字段、哪些异常类型、哪些测试用例通过才算完成。这件事在小规模试点阶段做掉,比在旺季前补要便宜得多。

当前接入边界:设计伙伴阶段能做什么、不能承诺什么

为了不让自动化承诺跑在能力前面,这里把口径说清楚:当前集成接口以设计伙伴 / 私有试点的方式推进,我们不承诺公开可申请的 API 密钥,也不承诺面向所有商户的生产级 webhook 或平台应用。渠道状态只按已核实事实陈述:我们的 WooCommerce 插件当前在 WordPress.org 目录中有 listing(目录 listing 与 WooCommerce Marketplace 上架不是一回事);Shopify 与 Amazon FBA 渠道,我们只陈述已核实的进展状态,在该渠道完成首单真实妥投之前,不会描述为“已全面可用”。

实际路径是:先在 /request-workflow-review 提交工作流评审 → 我们一起过订单入口、路由规则、异常处理与数据归属 → 再做字段映射 → 进入范围明确的试点交换 → 双方按约定用例验收。这个顺序不是流程形式主义:路由类项目翻车,多数时候翻在数据契约而不是翻在接口本身。

FAQ:集成工程师常问的六个问题

没有任何平台应用,还能不能接?

可以。试点集成按伙伴逐个定义:约定字段映射、约定事件集合、约定测试用例。这些都不依赖某个已发布的应用。

SKU 映射谁负责维护?

你负责。你知道哪个供应商生产哪个 SKU、哪些 SKU 希望备货。我们负责用实际收到的包裹校验映射并反馈冲突。货权始终归你,我们不向你的供应商采购,也不经手任何货款。

MCP/API 到底交换哪些数据?

入仓与收货状态、证据事件(拍照/点数/称重)、合箱事件、出库与追踪回写、以及带“需要谁处理”字段的异常事件。不交换付款信息,也不交换你的供应商采购单。

验收周期多长?

我们不给固定天数,因为它由范围决定。顺序是评审 → 映射 → 测试用例 → 验收,开工前先把“完成”的定义写成文字并双方确认。

一张订单能同时走两种模式吗?

能,这正是这份契约存在的理由。按行记录数量、状态与追踪,是整个设计的前提。

某一行按计划发不出来会怎样?

它会变成一条异常事件,带有责任人字段和下一步动作,而不是一个悄悄变化的状态。

如果你准备把这份契约对照自己的表结构过一遍,可以从 /developers 开始,并在 /request-workflow-review 提交一次工作流评审。仍在评估履约模式的话,/for-merchants 与 /how-it-works 讲的是运营侧,/integrations 只列示各渠道已核实的接入状态。