先说结论：上线之后接口一断，API/EDI 集成排障的第一原则不是修得快，而是别把事情搞得更糟。我见过最贵的几次事故，根子都不在故障本身，而在有人一慌就全量重发、手工改库存、连重启接口，把一个本来能追踪的故障，折腾成谁都对不上的烂账。这个坑我见过三次，三次剧本都一样：先动手，后找原因，最后花在对账上的时间比修接口多出好几倍。所以动手之前，先把故障定性，再谈怎么修。定性错了，后面每一步都是错的。

先定性：API/EDI 集成排障从四句话开始

断链只有四种可能，你先对号入座，再去翻日志。第一，报文根本没到：对方没发、发错了地址、证书过期、网络断了。第二，报文到了但没处理：卡在校验、映射，或者缺了必填字段。第三，处理了但回执没回去：单据已经建了，对方却以为你没收到，于是又发一遍。第四，各方都觉得自己没错：订单、发货、库存三套系统对同一个词的定义不一样，各自算各自的账。

断链类型 现场长什么样 先查什么
报文没到 对方说发了，你这边连影子都没有 对方发送记录、接收地址、证书有效期
到了没处理 网关有记录，业务单据迟迟不见 校验报错、映射缺失、必填字段
处理了没回执 单据已建，对方却重复发 回执发送记录、对方是否确认收到
各方定义不一 每边数字都对得上，合起来就是对不上 在手、在途、可用的定义是否一致

还有一条铁律：没有证据，别重启生产接口。重启会把在途报文的状态清掉，你本来能顺着链条追下去的线索，重启之后就追不下去了。先留证据，再谈恢复。

很多上线后的麻烦，其实在选型那会儿就埋下了：主数据归谁管、异常由谁先发现，这些责任没写进协议，上线后一出事就互相推。如果你正在回头补这些责任划分，可以对照零售商仓库 API 与 EDI 选型对照里的选型维度，把当初跳过的责任项写进运营协议。

报文丢了别猜：API/EDI 集成排障的五步追踪法

我追报文固定走五步，顺序不能乱。第一步，拿着业务单据号去对方系统，确认发送记录：发了没有、发到哪个地址、对方拿到了什么返回码。第二步，查自己网关的接收记录，确认原始报文有没有存下来。第三步，校验原始报文：是格式问题、编码问题，还是业务规则拦住了它。第四步，看业务处理日志，确认它到底停在哪一步，是系统报错，还是被人工挂起了。第五步，查回执记录：确认有没有发出去，对方认不认。

这里有个反常识的判断：拿到成功返回码，不等于业务做成了。很多接口返回 200 只是说收到了，不是说订单建成了、库存扣对了。我亲眼见过两个团队拿着 200 的日志互相甩了两天，订单却一直躺在中间件队列里没人动。判断标准永远是业务单据的状态，不是返回码。返回码只证明传输没断，证明不了业务做对了。

上线前夜核对单里，必须单独列三项测试：重发测试、乱序报文测试、空字段测试。重发测的是幂等，乱序测的是单据状态机扛不扛得住，空字段测的是系统会大声报错还是悄悄丢单。三者里最可怕的是悄悄丢单：报错至少会有人知道，悄悄丢单要等客户投诉才发现。测试环境只跑顺畅流程的上线，等于没测。

订单卡了，先别手工建单

订单卡住的时候，救急最诱人的办法就是手工建单。我劝你忍住：手工单解了今天的发货，却保证了明天的对账麻烦，不是重复单，就是缺单。卡单先走核对单，每一项都要有证据，日志条目或者单据状态都算，凭感觉说的我不认。对方系统里有这个单据号吗？报文到网关了吗？校验过了吗？产品和库位编码映射上了吗？库存够吗？单据是不是被人工挂起了？六个问题一个一个打勾，卡在哪一步就修哪一步。

去年秋天，加州安大略市郊一家家居用品第三方仓，上线第三周的周二早上，零售商说四百多张订单根本没到仓。当班的人以为接口挂了，连重启了两次，一点变化都没有。查下来才发现，零售商改了一个产品编码的后缀，没告诉仓库。两边都没坏，只是都默认对方什么都没改。最后的办法是先临时映射旧编码保住当天发货，再走正式流程把编码变更通知补上。从那以后，我查问题先看变更记录，再看系统日志。

找到根因之后，修的顺序也有讲究：先保发货，再修数据，最后再论责任。是映射问题，先上临时映射保住今天的发货，正式变更慢慢走流程。是缺货，先确认缺货是真的还是库存数据滞后：数据滞后就走对账流程，真缺货就走缺货流程，硬把订单放出去对谁都没好处。修好一单之后，还要看同一批订单是不是同一个病因，别只修一单就收工。

再算一笔账，你就知道为什么不能靠人手硬扛。假设一天卡住四百单，每单手工核查加处理要八分钟，那就是三千二百分钟，五十多个小时，两个人加班都干不完。卡单量一过某个规模，正确的反应是修链路、批量处理，不是加人。加人是把系统问题变成人力问题，只会越来越贵。

库存对不上，先对定义再对数字

库存对不上的排查，我固定走三步。第一步，对总量：仓库系统的在手数、对方系统的在手数、双方上次达成一致的数，先把差距有多大、从哪天开始出现，说清楚。第二步，对流量：从基线那天到今天，把收货、发货、退货、调整四类分开比，看哪一类的累计差距正好等于总量差距。第三步，对单据：差距最大的那一类里抽几笔，一笔一笔查，是重复、是漏发，还是定义不一样。

芝加哥附近一家小家电仓，上线第一个月库存每天差一百多件，时高时低，整整一周找不出规律。最后查出是两个问题叠在一起：零售商系统把退货收货发了两遍，仓库这边没有按业务单据号去重，同一批退货入了两次账；同时盘点调整直接在仓库系统里改了数，从来没回传给零售商。两边各改各的数，差距越拉越大。修法一点都不花哨：所有重发报文一律按业务单据号去重，所有库存调整一律走接口，不许改完数就走人。这两条从那以后一直写在我的上线前夜核对单上。

定义不一样是最容易被忽略的病因：一边把在途库存算进在手，另一边不算，两边都没错，只不过数的不是同一样东西。对账之前，先把在手、可用、在途这三个词写下来，让两边签字认同。定义没对齐的对账，最后一定是各说各有理。

最后说一句可能不太中听的话：接口不是上线那天就完事了。上线后头三十天风险最高，对方可能改编码、换证书、改发送频率，全都不告诉你。我现在的做法是，第一个月每周对账一次，证书到期前两周就换掉。真正把 API/EDI 集成排障做扎实的办法，从来不是哪次救火救得漂亮，而是这些不起眼的例行动作一次都没落下。明天值班之前，先把定性四句话、报文追踪五步、卡单核对单贴在值班台上，出事按顺序走，别凭手感动手。

作者：林晓｜WMS 实施顾问，做过 30+ 上线项目