和 ERP 对接订单:异步审核、幂等推送与同步日志
直接回答: 平台和 ERP 对接,最常见的误解是把“ERP 收下了订单”当成“订单成功了”。很多 ERP 收单之后还要人工审核、出库记账,平台只能等。我们的做法是:每次推送带稳定的业务键,可以安全重试;状态靠定时回查,不靠一次调用的返回值;每个同步动作写进同步日志;再用每日对账找出两边不一致的单据。
1.0 先把业务链路画出来
写第一行对接代码之前,和 ERP 实施方、业务方坐下来,把订单从下单到开票的每一步写下来,标出每一步发生在哪一边、是自动还是人工。一条典型链路:客户建档 → 推送订单 → ERP 审核 → 出库记账 → 发货与物流单号 → 收款确认 → 回拉发票。
人工环节一定要标出来。平台上显示“处理中”的单子,可能正躺在 ERP 那边某个人的待办里,平台怎么重试都没用。界面和告警要能区分“我们在等 ERP”和“推送失败了”,否则运营会把两类问题混在一起找开发。
2.0 推送要能安全重试
网络超时最麻烦:请求可能到了,也可能没到。重试时 ERP 如果再建一张单,就是重复订单。
- 每张单据带一个稳定的业务键,通常是平台订单号,ERP 按它去重。ERP 不支持去重的,推送前先查询这张单是否已经存在。
- 有依赖的主数据先推:新客户先建档,再推订单。依赖没就绪,单据就停在本地队列里,不要硬推。
- 编码对不上是常态,不是例外。商品或客户在 ERP 里还没建档时传什么、由哪一边补,要事先约定并写进文档。
- ERP 的错误常常藏在 HTTP 200 的消息体里。客户端统一识别这些错误语义,不让每个调用点各自判断。
3.0 状态靠回查
推送接口的返回只能说明“收到了”。之后的状态用定时任务回查:
| 设计点 | 我们的选择 |
|---|---|
| 扫描方式 | 按主键做键集分页,不用 OFFSET;单据多了也稳定,不会因为翻页漏单 |
| 扫描顺序 | 游标循环推进,每轮从上次停下的位置继续,避免反复处理同一批失败单 |
| 退避 | 连续失败的单据拉长回查间隔,设上限,超过上限转人工 |
| 并发 | 同一张单同一时间只有一个任务在处理,用行锁或租约保证 |
4.0 同步日志是排障的第一入口
每次调用写一行:单据号、动作、请求摘要、返回码、ERP 返回的消息、耗时、第几次尝试。密码、令牌和完整的个人信息不进日志。
有了这张表,“这张单为什么还没发货”可以先查日志,而不是翻应用日志、找 ERP 那边要截图。我们还会维护一份排障手册:每解决一个新问题,记下现象、根因、修法和诊断用的查询语句,新条目放最前面。ERP 对接的问题大多会以不同面目反复出现,这份手册比任何监控面板都管用。
5.0 对账
即使每一步都做对了,两边仍会慢慢不一致:有人在 ERP 里手工改了单、取消了单,或者某次回查结果没写进去。每天跑一次对账,比对订单状态、金额和发票,差异列成清单交给人处理。对账任务不自动“修正”任何一边,它的产出是一张待办清单。
6.0 开发和测试
- ERP 适配器做成接口,本地和 CI 用模拟实现,整个订单生命周期包括开票都能离线跑通。
- ERP 的测试环境往往和生产不一致,甚至没有。联调时把每个接口的真实请求和返回脱敏后存成样例,作为回归用例。
- 上线初期把对账频率调高,尽早暴露测试环境没覆盖到的情况。
已有订货系统要接 ERP,或者现有对接经常出问题,见 Web、云端与设备管理。也可以直接聊聊项目。
参考资料
- Stripe,幂等请求:https://docs.stripe.com/api/idempotent_requests
- Use The Index, Luke,键集分页:https://use-the-index-luke.com/no-offset
常见问题
ERP 只开放数据库视图、没有接口,还能对接吗?
只读视图拿来拉商品和库存问题不大。往 ERP 库里直接写单据风险高:它绕过了 ERP 自己的校验,出了问题很难界定责任。写入尽量走 ERP 提供的接口或导入功能,读写边界要先和 ERP 实施方确认。
库存多久同步一次合适?
看超卖的代价和 ERP 能承受的调用频率。下单时再实时校验一次库存,通常比把定时同步的频率拉得很高更可靠,也更省 ERP 的资源。
ERP 那边审核慢,客户一直看到“处理中”怎么办?
在界面上如实显示卡在哪一步,比如“等待 ERP 审核”,并给出业务方约定的处理时限。平台替代不了 ERP 里的审核,能做的是让等待可见,超时自动提醒负责人。
以后换 ERP,平台要重写吗?
对接代码集中在适配器里的话,换 ERP 主要是重写适配器、重新做编码映射和联调。业务代码到处直接调 ERP 接口的,改动面就大得多,这也是一开始就做适配层的原因。