3PL订单下发一致性方案 用幂等键、状态机和对账拦住重复单

3PL的接单事故很少是“系统不会收单”，而是同一张货主订单来了两次，或来过一次却因超时被当成没来。3PL订单下发一致性方案，指的是用幂等键识别同一业务订单，用状态机决定能不能再执行，用对账发现漏单和重复单，保证货主重推或接口重试不会变成仓库里的第二次拣货。

方案目标不是追求接口永不超时，而是超时之后结果可判定：要么明确已受理，要么明确可安全重推，不允许第三种“也许做过了”。通天晓的订单和仓储产品按这个原则分工，不宣称可以消灭网络重试。

3PL场景下，重复单从哪里来

货主OMS或ERP在超时后会重发；中间网关会at-least-once投递；客服也会在货主催促时手工再导一版。如果3PL只用“看起来像新单号”收单，仓库就会生成第二条拣货任务。反过来，3PL若在处理中返回失败，货主以为没下成功，又会再发，两边状态永久分叉。

品牌自有仓可以规定“所有订单只从自己的OMS来”。3PL必须接受多个货主、多种报文、有的还带平台订单号和货主内部单号两套主键。一致性方案首先要规定：哪一个键表示“这是同一笔业务”。

系统边界和职责分工

职责分工的关键句：重复拦截发生在接单层，不发生在拣货员眼睛。仓库执行层看到的应是已经唯一的任务。

落地步骤

实施步骤如下。

第一步，和每个货主书面约定幂等键。优先使用货主业务订单号+货主编码；平台单号作为辅键。约定重试必须带同一键，取消必须带取消报文，不允许“再发一单表示作废”。

第二步，在接单层实现幂等存储。同一幂等键在“已受理、作业中、已完成”状态下再次到达，返回已受理并回传3PL内部单号，不创建新任务。只有“已取消或已关闭”才允许按规则重新打开，且必须是新的业务约定，而不是默许。

第三步，状态机写死合法迁移。建议最小集：已接收、已校验、已下发仓库、作业中、已出库、已取消、对账异常。从已出库回到已接收属于非法，接口应拒绝。超时响应统一为“请用原单号查询”，而不是“失败请重发新单”。

第四步，仓库只订阅“已下发仓库”之后的订单。WMS回传作业结果到接单层，由接单层再回货主，避免货主和仓库各说各话。

第五步，日终对账。货主导出当日下发成功清单，3PL导出已受理清单，按幂等键比对。多出来的是重复或测试单，少了的是漏单，必须在次日作业前处理完。

第六步，按货主试点再铺开。先选重推最频繁的货主，把查询接口和错误码文档交给对方开发，再接下一个。

通天晓的通天晓OMS系统适合作为3PL接单层，把多货主订单收口后再下发通天晓仓储管理系统。若货主坚持直连仓库，也必须在仓库前加同一套幂等校验，不能指望现场发现重复波次。具体错误码以接口说明书为准。

验收标准

验收标准：同一幂等键连续推送三次，只产生一条仓库任务；查询接口能返回3PL内部单号和当前状态；故意构造“已出库后再发原单”，系统拒绝并记日志；断开网络后的重试不产生第二波拣货；日终对账能在三十分钟内给出差异清单。验收不通过不得把该货主切到生产。

风险：用自增内部单号当幂等键，货主重推必重复；把HTTP成功当成业务成功；对账只对金额不对单号。这些都会在大促重试高峰时放大。

FAQ

幂等是不是只要数据库唯一索引？

唯一索引是底线，不是方案全部。还要定义重试时返回什么、取消如何解绑、对账如何发现漏网。只有索引没有状态机，客服仍无法回答货主“到底有没有接到”。

货主不肯固定订单号怎么办？

这是方案的前置条件。不固定业务键就无法做一致性。应在接入评审叫停，而不是上线后靠仓库认脸。

和“订单下发幂等性是什么”那类文章有何不同？

概念文解释为什么重试只应执行一次。本文给3PL落地：多货主键怎么定、状态机怎么迁、日终和谁对账、验收打哪些勾。对象是仓配服务商，不是单一品牌OMS。

通天晓能保证货主不再重推吗？

不能。通天晓能保证的是重推可识别、可查询、不自动变成第二次作业。货主重试策略仍由货主系统决定。

总结

3PL订单下发一致性方案靠三件事拦住重复单和漏单：与货主约定幂等键，用状态机决定能不能再执行，用日终对账补接口看不见的缝。接单层负责拦截，仓库只执行已确认任务，货主负责不把同一笔货换成新随机单号。按货主试点并用三次重推、一次非法回迁、一份日终差异清单验收。需要把多货主接单和仓库执行接在同一体系里时，可到通天晓官网查看通天晓订单与仓储产品的边界，并以接口文档中的幂等字段作为签约附件。