youzan-datahub/docs/餐饮零售数据中台/有赞接口/5.查询仓库商品库存 (youzan.retail.open.query.warehousestock.1.0.0).md

查询仓库商品库存 (youzan.retail.open.query.warehousestock.1.0.0)

1. 接口基本信息

• API 名称：查询仓库商品库存
• API 接口名：youzan.retail.open.query.warehousestock
• 版本号：1.0.0
• 接口描述：用于精确查询指定仓库或线下门店下，特定商品规格（SKU）的各项详细库存数据。支持实时拉取实物库存、在途库存、计划库存及各维度的占用库存。

---

2. 请求说明

• 请求协议：HTTPS

• 请求方式：POST (严格要求，推荐 application/json 格式)

• 请求地址：

  https://open.youzanyun.com/api/youzan.retail.open.query.warehousestock/1.0.0
  

---

3. 请求参数

在请求的 Body 中传入以下 JSON 参数：

参数名称	类型	是否必填	示例值	参数说明
access_token	String	是	9b510e232...	有赞云 API 鉴权凭证
warehouse_code	String	是	MD00021	仓库/门店编码。必须传递有赞底层生成的仓编码（由 youzan.retail.open.warehouse.query 接口获取）。
sku_codes	Array (String)	是	["SKU001", "SKU002"]	商品规格编码（SKU）数组。注意：每次请求最多传入 20 个 SKU 编码。

---

4. 响应参数

响应主体包裹在 data 中，以数组列表形式返回请求中对应 SKU 的多维度库存详情。

根级参数名称	类型	描述说明
success	Boolean	请求是否成功 (true/false)
code	Integer	状态码，200 表示成功
message	String	成功或错误提示信息
data	Array	库存结果列表集合

4.1 data 数组内核心业务字段解构

内部参数名称	类型	核心说明
sku_code	String	商品规格编码（对应入参检索的 SKU）。
warehouse_code	String	当前查询返回的仓库编码。
stock_num	String/Decimal	实物库存数量。当前仓库中真实存在的物理库存总数。（注：该接口返回的库存数值精确到小数点后两位，如 100.00）
freeze_num	String/Decimal	实物库存占用。已被订单锁定、但尚未真实扣减出库的物理库存数量。
plan_num	String/Decimal	计划库存数量。多用于门店预售或外部系统的虚拟分配库存。
plan_freeze_num	String/Decimal	计划库存占用。计划库存中已被锁定的数量。
road_num	String/Decimal	在途库存。处于采购在途、调拨在途的预计入库商品数量。

---

5. ⚠️ 开发者防坑指南与注意事项（核心高频报错提醒）

1. 极其高频的报错：234000003 - 仓库信息不存在： 如果您在调用该接口时收到此错误，99% 的原因是您在 warehouse_code 字段里错误地传入了门店的店铺 ID（kdt_id）。

   • 避坑必看：此接口不认网点 ID。请务必先调用 youzan.retail.open.warehouse.query（查询总部下门店和仓库信息），拿到类似 MD00021 或 TEST001 的真正仓库编码，再传入本接口使用。

2. 如何计算“当前可用库存”？ 本接口不会直接吐出一个叫“可用库存”的字段。如果您正在对接前端商城的剩余可售数量计算，请按照公式自行相减： 可用库存 = 实物库存 (stock_num) - 实物库存占用 (freeze_num)

3. 参数数量超限限制： 入参的 sku_codes 数组严格限制最大长度为 20。如果您需要进行全店全量商品的库存对账或初始化同步，请不要用该接口循环遍历（极易触发限流告警），建议使用对应的“分页查询库存”专用接口。此接口更适合购物车结算前或单品详情页的点对点实时余量校验。

4. 精度格式说明： 有赞新零售体系内的库存不仅支持整数，也支持散装/称重商品（如按斤、米售卖）。因此返回的 stock_num 等数量字段可能为带有两位小数的数值型字符串（如 "5.50"），在强类型语言（如 Java、Go）解析时需注意浮点数/高精度类的映射处理。