WMS 与 ERP 集成：接口设计的八个坑

开篇：接口不是「连上就行」

一家制造企业，WMS 项目计划 6 个月上线，第 7 个月还在联调。复盘发现：WMS 本体 3 个月就调通了，剩下 4 个月全耗在和 ERP 的接口上。我的经验是：WMS 上线延期，70% 的问题出在接口。接口设计不是「连上就行」，魔鬼全在细节里。下面八个坑，踩过三个以上，项目必延期。

八个坑

坑一：主数据谁说了算没定

物料、客户、供应商主数据以 ERP 为准，WMS 只读；库位、批次规则、策略参数以 WMS 为准。最怕的是「双向写」——两边都能改物料主数据，对不上是迟早的事。原则：一份主数据只有一个主人。

坑二：单据状态机没对齐

ERP 的「已审核」到 WMS 是「可执行」，但中间可能差着「已分配」「已释放」好几个状态。状态断层的结果是单据卡死：ERP 以为发出去了，WMS 说没收到。动手前，先画一张两边的状态映射表，逐状态确认。

坑三：接口没有幂等设计

网络抖动导致重试，同一张收货单被执行两次——库存凭空多出一批货。所有写接口必须用业务主键去重（入库单号+行号），重复调用返回第一次的结果。这是铁律，没有例外。

坑四：批次/序列号规则字段没对全

ERP 只管批次号存在，WMS 要管批次属性：效期、检验状态、冻结原因。字段映射表必须逐字段确认，特别是「ERP 有、WMS 没有」和「WMS 要、ERP 不给」的字段，提前定好默认值或补录流程。

坑五：库存同步时机选错

实时同步听起来美好，但每天 10 万+ 笔库存变动会直接压垮 ERP。实战组合是「增量推送 + 定时对账」：WMS 实时推送增量，ERP 侧每 4 小时对一次账，差异超阈值告警。

坑六：异常没有标准回传

WMS 的短收、破损、拒收，要有标准回传码，ERP 侧必须有对应的处理流程（补单、索赔、报废）。否则差异单在 WMS 里堆积，财务月底对不上账，两个部门互相甩锅。

坑七：接口没有监控

每个接口都要有重发机制、死信队列和告警阈值。上线第一周每天对账，稳定后降到每周。没有监控的接口，出问题都是业务先发现、IT 后知道——这是最贵的发现方式。

坑八：切换期没有双跑

老系统和新 WMS 并行 1~2 周，每天日结对账，库存差异 <0.5% 才算达到切换标准。直接切换的勇气值得敬佩，但代价可能是停线。

对策一览表

| 坑 | 典型表现 | 对策 | |---|---|---| | 主数据归属 | 两边数据对不上 | 一份主数据只有一个主人 | | 状态机断层 | 单据卡死 | 先画状态映射表 | | 无幂等 | 重复收发货 | 业务主键去重 | | 批次字段缺失 | 效期管不住 | 逐字段映射表 | | 同步时机 | ERP 被压垮 | 增量推送+定时对账 | | 异常无回传 | 差异单堆积 | 标准回传码+处理流程 | | 无监控 | 业务先发现故障 | 重发+死信队列+告警 | | 无双跑 | 切换即停线 | 并行 1~2 周，日结对账 |

实战案例：返工三次才稳定的教训

某制造企业，WMS 与 SAP 集成返工三次：第一次状态机没对齐，单据卡死；第二次批次字段缺失，效期管理瘫痪；第三次才把幂等和监控补上。根因是联调环境搭晚了——ERP 侧测试环境排期拖了两个月，接口设计全靠文档想象。教训：联调环境和主数据映射表，是项目的第一优先级，不是附带工作。

避坑提醒

接口文档先行，代码后行。字段映射表、状态映射表、异常码表三张表，双方签字后再开发。
给接口留出至少 30% 的项目时间预算。WMS 本体只占 40%，接口和联调占 30%，切换和稳定期占 30%——这是健康的时间分配。
ERP 厂商的配合度要写进合同。很多延期是因为 ERP 侧排期跟不上，口头承诺不作数。

项目启动第一周：先拉接口清单

WMS 项目启动第一周，别写代码，先拉接口清单：

| 编号 | 接口 | 方向 | 频率 | 日数据量 | 业务负责人 | IT 负责人 | |---|---|---|---|---|---|---| | IF-01 | 采购订单下发 | ERP→WMS | 实时 | 500 单 | 计划部 | IT 部 | | IF-02 | 收货回传 | WMS→ERP | 实时 | 500 单 | 仓储部 | IT 部 | | IF-03 | 库存同步 | WMS→ERP | 每 4 小时 | 10 万笔 | 财务部 | IT 部 |

清单拉完，按「数据量 × 复杂度」排序，先啃硬骨头。原则：核心单据接口（收、发、库存）先行，报表查询类接口后行；每个接口明确业务和 IT 双负责人，出了问题知道找谁。

这张表是项目的早期预警雷达：哪个接口的业务负责人迟迟定不下来，哪个就是未来的延期点。