接口没报错但库存对不上：多店铺库存同步失败的 4 层排查思路

周一上午，速卖通店铺 A 和 Shopee 店铺 B 共享同一 SKU 池，同步脚本跑完日志全绿，每条接口返回 200。下午对账才发现 B 店比仓库实际多 17 件可售。没有弹窗、没有异常码，偏差就是在那儿。这类"接口没报错但数字对不上"的情况，本质是静默失效——问题藏在四个独立层级里，从数据字段到执行环境逐层向外排查，每层只需一个判据就能定位。

接口 200 ≠ 数据正确：静默失效的 4 层位置

四层由内向外递进：字段映射决定"写进去的是不是同一个数"，时序竞态决定"两个写入谁覆盖了谁"，平台规则决定"平台自己扣了多少没吐回来"，工具与环境决定"轮询够不够快、数据源对不对"。排查时从第一层开始，每层花 10 分钟做一条最小验证，命中即停，避免全量翻日志。

第一层：字段映射与精度

• 变体维度未对齐：速卖通 SKU 编码含颜色 + 尺码 + 包装，Shopee 只取颜色 + 尺码。同步脚本若把完整编码当主键写入 Shopee，同一实物会被拆成两条记录，库存被重复计入。判据：拿一个三变体 SKU，在两平台后台逐字段对照映射表，确认维度集合完全一致。
• 整数 vs 浮点：部分平台 API 返回 "quantity": 5.0，脚本若直接存为浮点再与本地整数账本比对，浮点精度会在 10 次累加后产生 0.001 级偏差，对账工具判为不匹配。判据：在写入前加一层 Math.round() 或平台侧强制 integer 字段，跑一次全量比对看偏差是否归零。
• SKU ID 截断或错位：自增 ID 在 7 位变 8 位时，下游脚本若用固定宽度字符串接收，前导零被吞掉，导致 A 店 ID 写到 B 店的槽位。判据：抽查最近 200 条同步日志的 ID 字段长度是否恒定。

第二层：时序与竞态

轮询间隔 5 分钟，但 Shopee 侧在两次轮询之间完成了一笔订单的库存扣减，速卖通侧同时触发了一次补货写入。两个写入到达平台的时间差只有 1.2 秒，后到的一方把前者的结果覆盖。日志里两次请求都返回 200，但终态不是任何一方的预期值。缓存 TTL 加剧了这个窗口：Shopee 商品页库存有 60 秒 CDN 缓存，即使 API 写成功，买家端仍显示旧值，卖家据此判断"同步没生效"再手动改一次，进一步放大偏差。对照自己的 cron 或 Webhook 配置，把轮询间隔压到写入频率以下，并在关键 SKU 上给写入加乐观锁版本号，可消除大部分竞态。

第三层：平台规则

本地账本 100 件，平台显示 83 件，差额 17 件未必是丢失，而是平台内部的库存子状态没有回流到同步接口：

• 速卖通：买家下单后库存进入"预占"状态，24 小时未支付才释放。预占期间同步接口只返回"可用库存"，预占部分不可见。若脚本把可用库存当作全量回写本地，预占释放时本地数字会突然跳升。
• Shopee：活动库存（flash sale 预留）与常规库存分桶管理，活动期间的扣减不反映在常规桶的 API 返回值中。详见 Shopee 多店铺履约规则中库存被跨店占用的失效链。
• Lazada：预售库存独立计数，开售后自动转入常规桶，但转入有 15 分钟延迟，延迟窗口内同步脚本读到的仍是预售值。

判据：把平台后台的"可用 / 预占 / 活动预留 / 预售"四个子项分别截图，与本地账本逐项对齐，差额落在哪个子项就属于哪条平台规则，不是同步 bug。多平台库存与订单的权限切分逻辑，可参考 速卖通多店铺库存、订单与客服权限分权 一文的字段设计。

第四层：工具与环境

前三层修完仍有残差，问题大概率在工具层：轮询频率低于订单峰值、数据源仍依赖手动导出 Excel、多店铺登录环境未隔离导致 Cookie 串扰。判断是否该升级工具，看三个信号：手动对账频率超过每周 3 次、跨平台数量超过 3 个、同时操作库存的团队成员超过 4 人。命中两条以上，自建脚本的维护成本已高于引入统一工作台的边际收益。选型上，2–3 个平台的轻量 SaaS 能覆盖轮询和基础对账；4 个以上平台或需要库存-订单-客服三条流收口时，再考虑 多平台订单、库存和消息集中处理的统一工作台。工具能力边界与三档团队的选型对比，详见 多店铺运营工具选型：自建表格、浏览器多开与统一工作台。