先说结论：电商平台 API 升级不是技术部门自己的事，是仓库的运营风险。 升级当天如果没有人盯着接口日志，就等于裸奔。仓库和平台之间通常就三条线——订单流入、库存回写、物流单号回传。任何一条断了，仓库该干的活就停了，但货还在那儿，客户可不会等你。
这个坑我见过三次。每次的剧本都一样：平台发了 deprecation 公告，开发扫了一眼说"知道了"，然后升级那天凌晨，订单停止流入 WMS，早上开工才发现，仓里已经乱了。
平台 API 为什么总在升级
电商平台的 API 是有生命周期的。以 Shopify 为例，每个季度发布一个新版本，每个版本至少支持 12 个月（以 Shopify 官网 developer changelog 为准）。老版本到期就关——你还在调它，接口直接返回 404 或者 410，订单一单都进不来。
Amazon 那边，老的 MWS 接口已经退役，全线迁移到 SP-API（以 Amazon 官网迁移公告为准）。迁移不只是"换个地址"，鉴权方式、权限 scope、字段定义全变了。
所以这不是"会不会升级"的问题，是"什么时候轮到你"的问题。多数平台会提前 60～90 天发 deprecation 公告（以各平台官网为准）。公告发出那天起，倒计时就开始了。
真实项目故事一：凌晨两点，订单停了
2024 年 3 月，洛杉矶附近一家 DTC 服装仓，日均 5000 单，Shopify 接 WMS 跑了三年，一直很稳。
那次 Shopify 版本升级后，订单 webhook 里一个用了三年的字段被改名了。开发在沙箱里测了一遍"下单能进来"，就上线了。但他没测的是：改单和退单的 webhook 用的还是旧字段名。
凌晨两点，新版本切换。订单能进来，但所有带改单、退单的订单在 WMS 那边解析失败，直接进了死信队列。没人看死信队列——监控只配了"订单流入量"，没配"解析失败率"。
早上九点开工，客服先炸的：客户说改了地址，仓库说没收到。查日志才发现，积压了 6000 多单异常。修了整整三天，期间改单全靠人工在 WMS 里手工改，客服被骂爆。
复盘时开发很委屈："沙箱里测过下单是好的。" 我说：你测的是 happy path。API 升级要测的是全链路——下单、改单、退单、库存回写、单号回传，一条都不能少。
真实项目故事二：401 报错被当成"网络波动"忽略了两周
2023 年底，一家 3PL 客户，Amazon SP-API 迁移。
迁移时应用的授权 token 权限 scope 变了，库存同步接口开始报 401。运维同学看了一眼日志，觉得是"网络波动"，重启了一下同步任务，401 还在，但他没深究——因为监控只配了"任务有没有在跑"，没配"HTTP 状态码分布"。
两周后，亚马逊卖家账号绩效掉分，超卖了 300 多件。客户的老板打电话来，声音都在抖。
这个坑我见过三次，每次都是同一个根因：监控的是"程序活没活"，而不是"接口对不对"。 程序活着，但返回的全是 401，跟死了没区别。
升级前 30 天：先把这张表建起来
别一上来就动手改代码。先做台账，90% 的翻车都是因为"不知道自己在用什么版本"。
列一张表，每行一个平台连接器：
- 平台名称（Shopify / Amazon / Walmart…）
- 当前用的 API 版本
- 该版本的退役日期（从官网 changelog 抄下来，贴在项目看板上）
- 负责人（必须是一个具体的人，不是"技术部"）
这张表谁来维护？指定一个人，每季度对一次官网 changelog。别指望"大家"——"大家"负责的事，最后都没人负责。台账建好那天，把每个退役日期倒推 30 天设个日历提醒：公告邮件可能漏看，提醒不会。
然后做这件事：把平台开发者更新邮件订阅了——这封邮件就是你的倒计时发令枪。
升级公告来了，先做这 3 个判断
公告邮件躺在邮箱里，别只转发给开发。先做三个判断：
判断一：这次升级动了什么？ 打开 changelog，只看 breaking changes（破坏性变更）那一节。没动你用的字段和接口，风险就低；动了 webhook 的字段名、鉴权方式、分页逻辑，标红。
判断二：我们的连接器用到了几个？ 拿出台账，一个一个打勾。用到的打勾，没用到的划掉。很多仓的连接器是三年前外包公司写的，早就没人记得用了哪个版本——台账就是这时候用的。
判断三：影响的是哪条线？ 动到订单流入的，就是 P0，最高优先级；只动到单号回传的，可以排后。先把火力集中在会让仓库停摆的线上。
三个判断做完，范围和优先级就清楚了。
升级日的 7 步 checklist
公告来了，按这个清单走，一步都别跳：
第 1 步：沙箱先行。 新版本先在沙箱或测试环境跑完 4 条链路回归：下单流入 WMS、改单退单、库存回写、物流单号回传。记住故事一的教训：happy path 不算测完。
第 2 步：监控告警提前一周上线。 订单流入延迟超过 15 分钟告警；webhook 失败率突增告警；API 的 4xx、5xx 突增告警；token 有效期不足 30 天告警。记住故事二的教训：告警要看"接口对不对"，不只看"程序活没活"。
第 3 步：灰度发布。 10% 流量 → 50% → 100%，每一步留 24 小时观察窗。用 feature flag 或者双版本并跑，回滚按钮要在手边，不是在文档里。
第 4 步：升级日有人值守。 升级当天安排人盯日志，不是"有空看一眼"，是专门盯。把升级安排在工作日的上午，千万别放在周五下午——周末没人修，这个坑我见过三次。
第 5 步：仓库备好手工预案。 准备好手工导入单的 CSV 模板，接口挂了先手工导单。仓不能停。 技术可以慢慢修，货必须照常发。
第 6 步：大促前两周冻结。 大促前两周内不动任何接口。谁提升级，直接驳回。等大促结束再说。
第 7 步：上线后 72 小时对账。 每小时比对"平台订单数 vs WMS 入单数"，差一单都要查。对上了 72 小时，才算真正落地。
沙箱回归：4 条链路一个都不能少
每次 API 升级，沙箱里必须跑完这 4 条链路，一个都不能少：下单流入 WMS（地址、SKU、数量全对）；改单退单（改地址、改数量、整单取消）；库存回写（WMS 库存变了，平台要在几分钟内同步）；物流单号回传（平台订单状态变成已发货）。跑完截图留底，出了问题先排除"我没测"，再去查平台那边。
这 6 个翻车点，个个我都见过
高频翻车点，看看你中过几个：
- 只升级了生产环境，沙箱的字段映射没同步——下次回归测了个寂寞。
- 库存回写用了新字段，但 WMS 那边还是旧逻辑——库存数对不上，超卖就是这么来的。
- webhook 回调 URL 还是旧域名——平台往旧地址推，你这边永远收不到。
- token 权限 scope 升级后变了，忘了重新授权——401 见故事二。
- 大促前一周升级——神仙也救不了。
- 把"平台公告"只转发给了开发，没告诉仓库运营——升级当天仓库一脸懵，连手工预案都没准备。
技术上都不难，难的是没人当回事。checklist 打印出来贴运维墙上，比什么都管用。
作者：林晓｜WMS实施顾问，做过30+上线项目
