77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
|
||
# 查询总部下门店和仓库信息 (youzan.retail.open.warehouse.query.3.0.0)
|
||
|
||
## 1. 接口基本信息
|
||
|
||
* **API 名称**：查询总部下门店和仓库信息
|
||
* **API 接口名**：`youzan.retail.open.warehouse.query`
|
||
* **版本号**：`3.0.0`
|
||
* **接口描述**：用于连锁总部或多网点商家，批量查询其底下的所有真实仓库以及具有仓库属性的“线下门店”信息。获取到的 `warehouse_code` 是后续调用库存调整、盘点、调拨等单据接口的**必传核心参数**。
|
||
|
||
---
|
||
|
||
## 2. 请求说明
|
||
|
||
* **请求协议**：HTTPS
|
||
* **请求方式**：POST (推荐 `application/json` 格式)
|
||
* **请求地址**：
|
||
|
||
```http
|
||
https://open.youzanyun.com/api/youzan.retail.open.warehouse.query/3.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 请求参数
|
||
|
||
在请求的 Body 中传入以下 JSON 参数：
|
||
|
||
| 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 |
|
||
| :--- | :--- | :---: | :--- | :--- |
|
||
| `access_token` | String | **是** | `9b510e232...` | 有赞云 API 鉴权凭证（请使用连锁总店的 Token 授权） |
|
||
| `page_no` | Integer | 否 | `1` | 页码，默认从 1 开始 |
|
||
| `page_size` | Integer | 否 | `20` | 每页返回的数量，建议默认 20，最大通常不超过 100 |
|
||
| `warehouse_name` | String | 否 | `北京一号仓` | 仓库或门店名称（支持模糊搜索筛选） |
|
||
| `retail_source` | String | 否 | `YOUZAN` | 零售调用来源。*（注：该字段官方已于 2021-04-26 废弃取消强校验，新接入开发者无需传值，不影响调用）* |
|
||
|
||
---
|
||
|
||
## 4. 响应参数
|
||
|
||
响应主体包裹在 `data` 中，主要返回门店与仓库的映射列表信息。
|
||
|
||
| 根级参数名称 | 类型 | 描述说明 |
|
||
| :--- | :--- | :--- |
|
||
| `success` | Boolean | 请求是否成功 (`true`/`false`) |
|
||
| `code` | Integer | 状态码，`200` 表示成功 |
|
||
| `message` | String | 成功或错误提示信息 |
|
||
| `data` | Object | **查询结果总包** |
|
||
| └─ `count` | Integer | 匹配到的总条数（用于计算分页） |
|
||
| └─ `items` | Array | **仓库/门店信息列表集合** |
|
||
|
||
### 4.1 `items` 数组内核心业务字段解构
|
||
|
||
| 内部参数名称 | 类型 | 核心说明 |
|
||
| :--- | :--- | :--- |
|
||
| `warehouse_code` | String | **仓库/门店编码（核心参数）**。有赞系统内部生成的唯一编码（如 `MD00021` 或 `TEST001`）。 |
|
||
| `warehouse_name` | String | 仓库或门店的名称。 |
|
||
| `warehouse_type` | Integer | 仓库属性类型。区分该主体是“普通大仓”还是“线下实体门店”。 |
|
||
| `kdt_id` | Long | 绑定的对应店铺/网点的底层 ID。（如果该仓是独立门店，则返回对应门店的 kdt_id） |
|
||
| `status` | Integer | 仓库状态。例如正常营业、停用等。 |
|
||
| `address` | String | 仓库或门店的详细物理地址。 |
|
||
|
||
---
|
||
|
||
## 5. ⚠️ 开发者防坑指南与注意事项（核心高频报错提醒）
|
||
|
||
1. **极其容易混淆的 `warehouse_code` 与 `kdt_id`（错误码 `234000003`）**：
|
||
在有赞新零售/连锁系统中，“线下门店”本身也被视作一个“仓库”。很多开发者在调用“查询/调整门店商品库存”接口（如 `youzan.retail.open.query.warehousestock` 或 `youzan.retail.open.stock.adjust`）时，**错误地将门店的底层店铺ID（`kdt_id`）当作仓库编码传了进去**，这会导致接口直接报错：`{"code": 234000003, "message": "仓库信息不存在"}`。
|
||
**正确做法**：必须先调用本接口（`youzan.retail.open.warehouse.query`），拿到门店对应的真实 `warehouse_code`（类似 `MD00021`），再用这个编码去调用库存接口。
|
||
|
||
2. **ERP 映射关系的建立（库存对接必读）**：
|
||
如果您正在对接第三方 ERP 系统的网店/门店库存同步，正确的初始化流必须是：
|
||
在第三方系统中建立映射表 → 调用本接口全量拉取有赞的 `warehouse_code` → 与 ERP 系统里的仓库编码（或者门店编号）进行 `1:1` 的绑定映射。
|
||
|
||
3. **连锁授权架构提示**：
|
||
本接口属于“零售连锁/多网点”场景下的专属 API。调用时使用的 `access_token` 必须是由**总部（总店）**授权产生的。如果使用单店或无多网点权限的微商城 Token 请求，可能会拉取为空或提示权限不足。
|