这个接口解决什么问题

聚水潭 /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,具体以聚水潭业务规则为准。

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

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

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 小时级是性价比最高的节奏。