77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
|
||
# 查询仓库商品库存 (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` 格式)
|
||
* **请求地址**：
|
||
|
||
```http
|
||
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）解析时需注意浮点数/高精度类的映射处理。
|