TMS 回传一断，运费对账就对不上：WMS-TMS 对接的三个断点

一家 Fontana 的 3PL 客户，去年 11 月对账时发现 10 月的运费多了小 4000 美金。查了两周才找到原因：承运商 45 天前调整了偏远地区附加费的计费规则，TMS 这边没人去更新，WMS 的报价引擎还在按旧规则发运单。货是正常发的，钱是默默多付的，账单晚到了 45 天才发现。这件事之后我养成一个习惯：凡是做 WMS-TMS 对接的项目，验收时先看回传链路，不看推送链路。推送谁都会做，断的地方全在回传。

整条链路其实很简单：WMS 把运单信息推送给 TMS 或承运商，承运商提货、运输、签收，状态和账单再一层层回传回来。断点就藏在这三个来回里。

回单断了，订单在 WMS 里永远"在途"

最常见的场面：货早就送到了，客户电话进来问签收情况，客服在 WMS 里一查——状态还停在"在途"，两天没动过。TMS 那边的 webhook 没发出来，或者承运商的 POD（签收凭证）根本没回传。WMS 里的订单就这么卡着，库存占用不释放，对账时一堆"已发货"单据浮在空中，月底结账全靠人工一票一票去 TMS 里翻。

根子在状态机设计得太糙。很多对接只做了"已推送 / 已完成"两个状态，TMS 回来的 in transit、out for delivery、delivered 全被粗暴地映射成"已完成"，异常件（returned、voided、damaged）甚至没有单独的回传通道。我现在的做法是：WMS 的运单状态至少拆成已推送、已提货、在途、已签收、异常五个，TMS 的每一个状态码都要有明确的映射归属，落不进这五个的进异常池人工看。

映射表我建议长这样：TMS 的 picked_up、departed 对应 WMS 的已提货；in_transit、arrived_at_hub、out_for_delivery 对应 WMS 的在途；delivered 对应已签收；exception、returned_to_sender、voided、damaged、lost 全部进异常，不许自动流转到已签收。这条红线一定要守住：异常件一旦被误标成已签收，客服、财务、库存三边同时错，查起来是三倍的工作量。

再加一道保险：webhook 和定时拉取双保险。webhook 负责实时，兜底的定时任务每小时扫一次——凡是超过 24 小时没更新的"在途"单，主动向 TMS 拉一次最新状态。这条兜底任务的代码量不大，但它是我见过性价比最高的对接补丁。另外给 webhook 接收端加一条监控：连续 30 分钟没收到任何回传就告警。回传链路是静默断的，没人盯着，它能悄无声息地断三天。

账单回来晚、字段对不上，月底差出几千美金

承运商的账单普遍 T+30 甚至 T+45 才到，燃油附加费表、偏远地区附加费规则说变就变。对账时 WMS 的预估费用和账单对不上，财务第一反应永远是"WMS 的数错了"。其实多数时候是规则版本没同步。

先把对接字段映射清单钉死，这是对账的地基：

WMS 字段	TMS / 承运商账单字段	说明
运单号	tracking number / PRO number	全链路唯一键，对账主键
计费重量	billed weight	注意实重与体积重的取大规则
目的地区域	zone	分区表变更要留版本
服务等级	service level	ground / 2-day / overnight 等
燃油附加费	fuel surcharge	按账单日期匹配费率版本
附加费明细	accessorial charges	偏远地区、超尺寸、住宅派送等逐项
发运时报价	quoted amount	WMS/TMS 下单时的预估
账单实收	invoiced amount	承运商最终账单
账单日期	invoice date	决定适用哪一版费率规则

具体费率数字我一律不写死——各家承运商的费率表和附加费政策年年变，以承运商官网最新政策为准。系统里要建的是一张"规则版本表"：每条费率规则带生效日期，对账时按账单日期去匹配当时的版本。Fontana 那家客户的 4000 美金，就是栽在没有规则版本表上。

再给两个对账窗口，别等到月底一次对。发运后 7 天做预估对账：WMS 预估费用 vs TMS 回传费用，偏差超过 5% 的标红先查；账单到后 3 天内做终审对账。两个窗口分开，问题票在第一周就冒头，不会攒到 45 天后。

预估对账还有个附带好处：能提前发现报价引擎的系统性偏差。如果某一类服务等级（比如 overnight）的预估连续两周都比回传费用低 8% 以上，基本可以断定是报价规则里漏了一项附加费，早调早省钱。终审对账的重点则不同：只看账单实收和回传费用是否一致，不一致的直接进争议流程，向承运商申诉。承运商的账单纠错窗口通常是有限的，拖过窗口多付的钱就真要不回来了——具体以各家承运商官网最新政策为准。

TMS 对账场景

重试没做幂等，同一票货被推了三次

网络抖动了一下，WMS 没收到 TMS 的确认，就按老逻辑重推了一次。结果 TMS 其实收到了第一次请求，只是回包丢了——同一票货在 TMS 里躺了三条，有的承运商会实打实地下三个面单。更隐蔽的是重复推送覆盖了第一次的报价，账单回来对哪条都对不上。

解法就两条，缺一不可。推送时带全局唯一的请求 ID，TMS 和承运商侧按这个 ID 去重，收到重复 ID 直接返回第一次的结果，不再执行业务动作。重试策略用"固定间隔加指数退避"，比如 5 分钟、30 分钟、2 小时三档，超过次数转人工队列，绝不无限重试。发送前先查本地的"已发送登记表"，登记表里有记录的请求一律不重发。幂等这件事，设计时多花半天，省的是事后查三天账。

还有个容易被忽略的细节：重试时千万别改请求 ID。正确的做法是同一票货的每一次重试都用同一个请求 ID，这样 TMS 侧的去重才能生效。我见过有系统每次重试重新生成 ID，去重逻辑形同虚设。另外，超时时间的设置也有讲究：承运商 API 在旺季经常响应慢，把超时设得太短（比如 5 秒），重试会被频繁触发；设到 30 秒左右再配合退避，误重试能少一大半。