Ecang（易仓 OMS）代理仓使用说明
更新时间：2026-08-06
1. 先看这页解决什么问题
这篇文档只讲 Ecang（易仓 OMS）这个代理仓系统的特殊规则，不重复介绍通用的代理仓配置和任务页操作。
如果你要处理的是下面这些问题，优先看这篇：
- 易仓当前支持哪些代理仓能力；
- 易仓库存数量应该怎么理解；
- 易仓场景下哪些出库链路会走代理仓，哪些不会；
- 易仓场景下入库、出库序列号具体支持到什么程度；
- 易仓任务长时间等待、取消失败或库存不同步时，应该先查哪里。
如果你还没完成系统、仓库、渠道配置，请先看《代理仓系统》。 如果你已经有任务异常，需要看状态和重试，请看《同步任务》。
2. 配置要点
2.1 新增易仓系统
菜单路径：GWMS-代理仓-代理仓系统
- 点击【新增】
- 填写【系统名称】
- 【系统类型】选择「易仓 OMS」
- 填写易仓提供的接入配置：
- 【接口地址】：必填
- 【App Key】：必填
- 【App Token】：必填
- 【语言】：选填，默认
zh_CN，一般不需要修改 - 【默认平台】：选填，默认
OTHER
- 点击【确定】
推送到易仓的入库单和出库单，审核要求当前都固定按"需要审核"处理，不支持在这里配置成"不审核"。
2.2 配置仓库映射（重要）
菜单路径：GWMS-代理仓-代理仓系统-仓库
必须配置 4 项：
- 代理仓代码
- GWMS 仓库代码
- 虚拟上架库位（存放易仓合格品）
- 残品库位（存放易仓不合格品）
❗ 如果缺少专用库位配置：
- 入库只能收货，无法上架
- 无法触发库存同步
2.3 易仓库存数量说明
易仓返回的库存包含两部分：
- 可用库存：可以分配出库的数量
- 锁定库存：已分配但未出库的数量
重要：总库存 = 可用库存 + 锁定库存
❌ 错误理解：只看可用库存 ✅ 正确理解：可用 + 锁定 = 总库存
除了可用/锁定，易仓的每批库存还带一个"合格/不合格/暂存"标记：
- 合格：计入虚拟上架库位
- 不合格：计入残品库位
- 暂存：当前版本不参与同步，既不计入虚拟上架库位，也不计入残品库位，也不计入总库存
也就是说，如果易仓那边有一批库存正处于"暂存"状态，GWMS 本地暂时看不到这部分数量，需要等它转成合格或不合格后才会体现在库存同步结果里。
3. 当前链路范围
3.1 入库业务
- GWMS 创建入库单
- 系统自动推送到易仓
- 到《同步任务》查看任务状态
- 易仓处理完成后，GWMS 自动收货和上架
取消入库单：
- 只有入库单在易仓那边还处于"已接单"或"处理中"阶段时，才允许发起取消。
- 如果易仓那边已经流转到收货、上架等更靠后的阶段，取消可能不会被易仓接受，需要先到《日志》确认易仓返回的具体原因。
3.2 序列号相关链路
当前易仓只支持"易仓 -> GWMS"这一个方向的序列号回写，不支持"GWMS 主动推送序列号给易仓"。
当前支持范围：
- 当易仓返回入库终态结果时，系统会从返回报文里解析序列号并回写到 GWMS 本地入库序列号记录。
- 当易仓返回出库完成结果时，系统会从返回报文里解析序列号并回写到 GWMS 本地出库序列号记录。
当前不支持：
- 入库单创建成功后，系统不会像 HPK 那样把本地已绑定的序列号主动补推给易仓。
- 本地序列号后续新增、变更或删除时，也不会同步推送给易仓。
如果你要确认某张单据的序列号有没有从易仓回写回来，直接到《日志》看这张单据对应的状态查询回包里有没有带序列号；不需要再检查"推送"方向，因为这个方向当前不存在。
3.3 出库业务
当前代码里，易仓出库只支持一件代发模式：
- GWMS 创建出库单。
- 系统自动推送到易仓。
- 系统创建任务并按自动节奏查询易仓处理状态。
- 易仓已完成后，GWMS 再推进本地出库状态。
- 如果易仓这次出库结果回包里带了序列号，系统会同时尝试把序列号回写到 GWMS 本地出库序列号记录。
❗ 备货中转出库当前不支持接入易仓：如果一张备货中转出库单被路由到易仓，推送会直接失败并进入人工处理，不会静默跳过。如果你的仓库同时存在一件代发和备货中转两种出库业务，请确认路由配置只把一件代发出库单指向易仓。
3.4 出库单"已下架"状态
易仓场景下，出库单的"已下架"状态目前只会在系统即将执行本地正式出库的那一刻才会一起标记，不会像 HPK 那样在易仓仍在处理中、尚未真正出库时提前标记。
也就是说：如果你在出库单列表或同步任务里看到某张易仓出库单还没有标记"已下架"，不能据此判断易仓那边还没开始处理，只能说明本地还没走到正式出库这一步。这一点当前跟 HPK 的表现不一致，暂时按此现状处理。
3.5 库存同步
触发方式：
- 在仓库映射页面点击【同步库存】
- 系统每 12 小时自动执行一次（与 HPK 共用同一个定时任务）
执行内容：
- 先尽量处理同仓待处理业务任务
- 从易仓拉取库存快照
- 按"合格/不合格/暂存"分类，暂存部分跳过
- 自动修正虚拟上架库位和残品库位的库存差异
- 保存库存快照
查看结果： 到《同步任务》查看库存同步任务详情。
注意：
- 只修正虚拟上架库位和残品库位
- 如果这次同步中有任意一页库存查询失败，本次同步会整体判失败，不会用不完整的数据覆盖已保存的库存快照
- 库存同步任务本身不靠轮询推进，但执行前的业务预处理有数量和时长预算，不是必须等所有业务任务都跑完才开始
4. 常见问题
4.1 "请先配置代理仓代码" / "请先配置虚拟上架库位" / "请先配置残品库位"
**原因：**仓库映射配置不完整
处理：
- 到《代理仓系统》查看仓库映射
- 检查是否配置了代理仓代码、GWMS 仓库代码、虚拟上架库位和残品库位
- 补齐缺失配置后重新触发库存同步
4.2 备货中转出库单推送失败
**原因：**当前易仓只支持一件代发出库，不支持备货中转
处理：
- 到《同步任务》确认这张出库单的失败原因
- 确认这张单据的业务类型是否本来就应该走易仓
- 如果不该走易仓，检查渠道或路由配置
4.3 入库单取消失败
**原因：**入库单在易仓那边可能已经流转到收货、上架等更靠后的阶段，不再允许取消
处理：
- 到《日志》查看易仓返回的取消结果和具体原因
- 如果易仓已经进入更靠后的阶段，需要先跟易仓侧确认实际处理进度，再决定是否需要人工介入
4.4 序列号没有出现在 GWMS
常见原因：
- 这条链路当前只支持"易仓回写"，不支持"GWMS 推送"；如果你要确认的是"本地序列号有没有推给易仓"，当前版本不支持这个方向
- 易仓的入库或出库状态回包里本身没有带序列号
- 回包里带了序列号，但 SKU 映射后没有匹配到 GWMS 商品
处理：
- 先确认你要排查的方向：只有"易仓 -> GWMS"这一个方向存在
- 到《日志》确认易仓入库或出库状态回包里是否真的带了序列号
- 确认回包里的 SKU 和 GWMS 商品映射是否一致
4.5 库存里少了一部分数量
**原因：**这部分库存在易仓那边处于"暂存"状态，当前版本不参与同步
处理：
- 先跟易仓侧确认这批库存当前的状态
- 如果它已经从暂存转成合格或不合格，重新触发一次库存同步
4.6 任务一直在等待中
常见原因：
- 易仓仍未处理到终态；
- 任务已经进入下一次自动查询等待；
- 当前摘要里已经有错误，但还没被人工处理；
- 映射、系统配置或资料问题还没修正。
处理：
- 先看《同步任务》里的【执行摘要】和【下次执行时间】。
- 如果摘要明确提示配置或资料问题，先修正问题，不要只反复点【立即同步】。
- 如果没有明显错误，再到《日志》确认易仓的返回内容。
- 必要时联系易仓确认单据在对方系统中的实际处理状态。