WMS 开放 API：对接内部业务系统最容易踩的 5 个坑

先说结论：WMS 对接内部业务系统（ERP、OMS、财务系统），翻车从来不是因为 WMS 开放 API 本身有多难，而是因为实施方把"调通接口"当成了"对接完成"。调通一个接口半天，做出生产可用的对接至少两周，中间差的就是下面这 5 个坑。我这 30 多个上线项目里，API 对接环节出问题的超过一半，而出问题的项目里，十个有九个栽在这 5 个坑里。

坑一：主数据没对码，订单推过来全是"野数据"

现象：ERP 的销售订单推到 WMS，WMS 一大半报"物料不存在"；或者更吓人的，物料存在，但是错的——ERP 的 SKU-A 对应 WMS 的 SKU-B，发出去的货不对版。库存回传也一样，WMS 报的可用库存，ERP 那边根本对不上账。

根因：两个系统的主数据从来就没统一过。ERP 的物料编码可能是十年前定的，带着供应商前缀；WMS 上线时重新编了一套内部 SKU；库位、承运商、客户编码，两边各有一套。接口只管传字段，不管字段背后的含义对不对得上。

这个坑我见过三次。印象最深的是一家加州的汽配 3PL，2024 年 11 月旺季前上线。他们的 ERP 用供应商条码做物料主键，WMS 用自编的内部 SKU，上线第一周，将近三成的订单下发失败，卡在异常池里。仓库现场是什么景象？拣选员在系统里看不到任务，主管在 ERP 里看到订单"已下发"，两边互相甩锅。最后救回来的办法很土：连夜建了一张主数据映射表，订单下发前先过一遍映射校验，对不上的进异常池人工处理，同时冻结新订单下发，先把积压的异常清掉。整整折腾了四天，旺季的头四天。

解法：

上线前先建主数据映射表（物料、库位、承运商、客户四张，一个都不能少），映射关系由业务方签字确认，不是 IT 自己拍脑袋。
所有下发接口加前置校验：编码在映射表里不存在，直接拒绝并写异常日志，不许"先传过去再说"。
每天跑一次主数据对账 job，两边新增、停用的编码自动比对，差异发邮件给主数据负责人。
异常池必须有人看：指定责任人、指定处理时限（比如 4 小时内），异常池不是垃圾桶。

检查项：□ 四张映射表已建并经业务签字 □ 下发接口有前置校验 □ 对账 job 已部署并收到过测试差异邮件 □ 异常池责任人和处理时限已明确

坑二：把 API 当实时通道用，旺季第一天就被限流打挂

现象：平时好好的，一到大促或者月末结账，WMS 接口开始大面积超时，订单下发延迟从几秒变成几十分钟，严重的直接触发 WMS 厂商的限流，返回错误码，整个对接停摆。

根因：实施时图省事，内部系统用"轮询"或者"实时推送"直连 WMS 开放 API——每几秒问一次库存，每下一单就调一次下发接口。WMS 的开放 API 都有调用频率上限（具体数字以各厂商文档为准，签合同前就要问清楚），平时调用量小没感觉，业务峰值一来直接撞墙。更糟的是，重试逻辑没做退避，失败了立刻重试，等于在已经过载的接口上再踩一脚油门。

解法：

对接层和 WMS 之间必须加消息队列（用你们内部已有的就行，不用为了这个买新中间件）。内部系统只管往队列里扔，消费端按 WMS 能承受的速率慢慢调接口。峰值来了，队列积压，慢但不断。
库存、订单状态这类查询接口，能用回调（WMS 主动推）就不用轮询。必须轮询的，间隔按业务实际需要定——库存同步 5 分钟一次和 5 秒一次，对仓库作业的影响几乎没有，对接口压力差了几十倍。
所有调用加幂等键：同一笔业务重复推送，WMS 侧只执行一次。网络抖动导致的重复下发，这是唯一的保命手段。
重试必须带退避（第一次等几秒、第二次等几十秒），重试 3 次还失败就进死信队列人工处理，不许无限重试。

检查项：□ 消息队列已部署并做过积压演练 □ 厂商的限流阈值已书面确认 □ 幂等键已全链路实现 □ 重试带退避且有次数上限

系统对接数据流

坑三：只写了正常流程，超时和部分失败直接丢单

现象：这是最阴的坑。接口返回超时，内部系统以为"没发成功"，自动重发；WMS 那边其实已经收到了，只是回包丢了。结果同一单下了两次，仓库拣了两遍。反过来，批量下发 100 单，WMS 只成功了 97 单，接口返回的是整体成功，剩下 3 单无声无息地丢了，对账时才发现。

根因：开发只测了正常流程，超时的语义没人定义：超时到底算成功还是失败？部分成功时，接口返回体里每个单据的状态有没有逐条检查？没人写，测试也没覆盖。上线前大家只关心"通没通"，没人问"断了怎么办"。

解法：

给每个接口定义超时语义并写进对接文档：查询类超时可以安全重试；下单、确认收货这类写操作，超时后必须先查状态再决定重不重发，绝不盲重发。
批量接口的返回必须逐条解析，每条单据成功还是失败都要落库记录，整体返回"成功"不代表每条都成功。
每天跑一次业务对账：内部系统的单据状态对照 WMS 的单据状态，状态不一致的自动预警。这是兜底中的兜底，再忙也要做。
关键接口（下发订单、确认发货、库存调整）做端到端演练：拔网线、杀进程、模拟超时返回，看系统能不能自己恢复。

检查项：□ 每个写接口的超时语义已文档化 □ 批量返回逐条解析已实现 □ 每日业务对账 job 已部署 □ 做过断网/超时演练并记录恢复过程

坑四：权限和密钥后补，一个密钥走天下

现象：上线前一周才想起来 API 要鉴权，图省事生成一个密钥，硬编码在对接程序的配置文件里，ERP、OMS、财务系统全用这一个密钥。半年后对接的开发离职了，密钥还在他手里，谁也不敢换——因为不知道换了会影响几个系统。

根因：安全永远排在功能后面。项目初期"先跑起来再说"，密钥的事一拖就拖到上线，上线后更不敢动。

解法：

按调用方分配独立的密钥或者账号：ERP 一个，OMS 一个，财务系统一个。哪个系统出问题，吊销哪个，不影响其他。
每个密钥只给最小权限：只查库存的密钥，就不给它下发订单的权限。WMS 厂商的开放平台一般都支持按接口授权，不支持就记下来，下次选型时这是减分项。
密钥写进密钥管理（你们内部用的任何一种都行），不许出现在代码仓库和配置文件明文里。
定好轮换周期（比如每半年），第一次轮换在上线后第一个月就做一次，把流程跑通，免得半年后没人会换。

检查项：□ 每个调用方独立密钥 □ 最小权限已配置 □ 密钥已入密钥管理、代码库无明文 □ 轮换流程已演练过一次

坑五：沙箱调通了就敢上线，生产环境当晚爆雷

现象：沙箱里 200 单跑得好好的，上线当晚 2000 单直接把对接程序打挂；或者沙箱的 WMS 版本和生产差了一个小版本，某个字段的行为变了，生产环境批量报错。

根因：沙箱和生产是两个世界：数据量级差十倍、数据干净程度天差地别、网络环境也不一样。只在沙箱里调通，等于只在驾校场地里练过车就直接上高速。

解法：

上线前做一次全链路压测，量级按历史峰值的 1.5 倍打。压测的不是 WMS，是你们自己的对接程序和队列——先找到自己的瓶颈。
用生产脱敏数据在沙箱跑一遍全量回归，重点看脏数据：编码缺失、特殊字符、超长字段，生产环境的脏数据永远比你想象的多。
确认沙箱和生产的 WMS 版本一致，接口行为有变更的一定要拿到厂商的变更说明。
准备回滚方案并演练：对接挂了，能不能一键切回人工/旧流程？切回去的数据怎么补？这两个问题的答案，上线前夜必须人人清楚。

检查项：□ 压测已做（1.5 倍峰值）并记录瓶颈 □ 生产脱敏数据回归已跑 □ 沙箱生产版本一致性已确认 □ 回滚方案已演练

一个反常识的判断

API 文档最全、接口数量最多的 WMS，对接时坑反而最多。

这话听起来反直觉，但我 30 多个项目看下来就是这样。文档写得全的厂商，接口粒度往往很细，一个"下发订单"拆成五六个接口，每个接口一堆可选字段。实施方照着文档"全量对接"，对接面铺得越大，坑越多——每个字段的语义都要对，每个异常分支都要处理。反倒是文档薄、只开放二三十个核心接口的 WMS，逼着你只对接"下发、回传、查库存"这几件生死攸关的事，对接面小，出事的概率反而低。

所以选型时别被"我们开放 200+ 接口"忽悠。问厂商三个问题：第一，核心对接（订单下发、状态回传、库存同步）最少要调几个接口？第二，限流阈值是多少，写进合同吗？第三，沙箱和生产的行为差异，有没有书面保证？答不上来的，接口再多也是摆设。

权衡关系就一句话：对接的深度和对接的成本永远成正比。能只用 5 个核心接口解决的，就别为了"一步到位"去对 50 个。对接面上线后是持续维护成本，不是交钥匙工程。