聚水潭商品库存查询接口字段手册教程(对接 MySQL 实战)

这个接口解决什么问题

聚水潭 /open/inventory/query 用于把聚水潭的商品库存拉取到本地 MySQL 表 jst_inventory_query,支撑多仓/分仓库存汇总、库存预警、可售库存计算,以及与 ERP、BI 系统的库存数据打通。我们在做供应链集成时,几乎每个客户都需要这条链路。

接口能力总览

• 认证方式:聚水潭开放平台标准的 partnerId + 签名机制,请求头携带 AppKey、时间戳与签名串。
• 请求结构:POST + form/query 形式,核心参数 wms_co_id、modified_begin、modified_end、page_index、page_size、sku_ids。
• 响应结构:JSON 包裹的 datas 数组,每条记录对应一行库存,顶层 has_next 标识分页是否结束。
• 分页模式:page_index 从 1 起,page_size 默认 30、上限 50,需循环拉取直到 has_next=false。
• 增量模式:按 modified 字段增量,modified_begin 与 modified_end 时间窗不得超过 7 天,否则接口会报错。
• 特殊查询:wms_co_id 不传或为 0 时返回全仓总库存;sku_ids 最多 20 个,与修改时间不能同时为空。

典型字段映射

字段名	类型	含义	实战注意事项
i_id	string	库存记录主键	集成时建议使用 {{sku_id}}-{{wms_co_id}}-{{ts}} 作为 MySQL 主键,避免跨仓冲突
sku_id	string	商品 SKU 编码	metadata 中 number 指向它,作为业务主键
name	string	商品名称	与 sku_id 关联,便于人工核对
qty	string	可用库存	实际可售数量,常与虚拟、锁定字段联用
virtual_qty	string	虚拟库存	预售、预占等虚拟增加量
purchase_qty	string	采购在途	采购订单未入库数量
allocate_qty	string	分配数量	已分配待出库
order_lock	string	订单锁定	订单占用,会减少可售
pick_lock	string	拣货锁定	拣货中锁定
in_qty	string	入库在途	入库未完成
return_qty	string	退货在途	退货未入库
defective_qty	string	残次品	不可售库存
min_qty / max_qty	string	库存预警阈值	用于低/超储预警
modified	string	修改时间	增量拉取的关键字段,需以「服务器时间」为准
ts	string	时间戳	同步时间,常做幂等去重的辅助键

可售库存的常用经验公式:qty + virtual_qty - order_lock - pick_lock - allocate_qty,具体以聚水潭业务规则为准。

在轻易云上如何配置

在轻易云数据集成平台里,该接口通常封装为「聚水潭-商品库存查询」适配器,挂在「聚水潭·开放平台」连接器下。配置思路:

1. 连接器:选择聚水潭适配器,填写 partnerId、AppKey、AppSecret,系统会自动生成签名。
2. 请求模板:把 modified_begin / modified_end 用平台变量 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}} 绑定,实现增量窗口。
3. 字段映射器:平台字段映射器会自动把 datas[*] 展开为明细行,主键字段使用表达式 {{sku_id}}-{{wms_co_id}}-{{ts}}。
4. 目标端:写入 MySQL 表 jst_inventory_query,轻易云会默认生成 REPLACE INTO 批量写入,避免重复。
5. 后置脚本:在「AfterTargetGenerate」阶段挂载「空值改 null、过滤 emoji 与四字节字符」脚本,避免 MySQL 写入异常。
6. 调度:建议 crontab 设置为 20 */2 * * *,每 2 小时一轮,既不会触碰到 7 天窗口上限,也能覆盖主流预警需求。

跨方案实战要点

1. 增量窗口别超过 7 天:多个客户都踩过这个坑,聚水潭服务端的硬限制。建议留 1–2 小时重叠区,避免漏单。
2. 分仓用 wms_co_id 区分:全仓汇总与单仓查询走同一接口,但必须用不同的 wms_co_id 参数,落地到 MySQL 时要保留该列。
3. page_size 不要贪多:实测 page_size=50 在数据量大时偶发超时,稳妥起见用 30。
4. 主键要用复合键:单用 i_id 容易冲突,用 sku_id+wms_co_id+ts 组合键最稳。
5. 数量字段全部是字符串:MySQL 端建议统一存为 VARCHAR 或显式 CAST 转 DECIMAL,不要直接当数字使用。
6. 空字符串要清掉:聚水潭常返回 "",在落库前统一转 null,否则 MySQL 索引会膨胀。

踩坑复盘

• 7 天窗口被截断:第一次跑时把窗口设成 30 天,接口直接报错。稳妥做法是:按 modified 滚动,每次 2 小时窗 + 1 小时重叠。
• page_size 过大导致 504:某零售企业单仓数据量极大,设 page_size=50 后请求频繁超时,改为 30 后稳定。
• Emoji 字符导致 MySQL 报错:商品名称里有表情符号,utf8 写入失败。需要在「AfterTargetGenerate」阶段过滤四字节字符。
• 全仓 vs 分仓数据混淆:有客户把全仓和分仓数据写到同一行,导致库存翻倍。务必按 wms_co_id 分行落库。
• 库存数量被当 INT 写:接口所有数量字段都是 string,直接入到 INT 列时 "" 会被解析为 0,造成可售库存漂移,建议落库前显式转 NULL 或 DECIMAL。

何时选用

当你需要把聚水潭库存本地化、做多仓汇总、驱动库存预警或对接 BI/ERP 时,这条接口是最稳妥的选择。但若你只想要某个 SKU 的实时可售数量,且没有批量分析需求,直接调用聚水潭前端接口更轻量。本接口不适合做"秒级实时"库存,2 小时级是性价比最高的节奏。