youzan-datahub/docs/餐饮零售数据中台/有赞接口/5.分页查询库存模式 (youzan.retail.open.stock.mode.query.1.0.0).md

# 分页查询库存模式 (youzan.retail.open.stock.mode.query.1.0.0)

## 1. 接口基本信息

* **API 名称**：分页查询库存模式
* **API 接口名**：`youzan.retail.open.stock.mode.query`
* **版本号**：`1.0.0`
* **计费规则**：基础接口，调用计费
* **接口描述**：用于连锁总部或单店商家，分页查询旗下各个店铺/门店（kdt_id）对应的“库存管理模式”。帮助开发者判断门店是使用独立销售库存，还是共享总部/仓储的库存，以及是否开启了单据管理库存。

---

## 2. 请求说明

* **请求协议**：HTTPS
* **请求方式**：POST (请求体传参，推荐 `application/json` 格式)
* **请求地址**：

  ```http
  https://open.youzanyun.com/api/youzan.retail.open.stock.mode.query/1.0.0
  ```

---

## 3. 请求参数

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

| 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 |
| :--- | :--- | :---: | :--- | :--- |
| `access_token` | String | **是** | `9b510e23...` | 鉴权凭证，用于请求 API |
| `retail_source` | String | **是** | `YOUZAN` | 零售调用来源（调用方和有赞约定的值，通常为接入应用标识，必填字段） |
| `node_kdt_id` | Long | 否 | `18938611` | 连锁场景下查询指定分店的 `kdt_id`。查总部下全部店铺则不用传；单店场景不用传。 |
| `stock_mode` | Integer | 否 | `2` | 按特定库存模式筛选。不传则查全部模式。<br>`1`-独立销售库存；`2`-共享总部库存；`3`-共享门店仓库存库；`4`-进出存单据管理。 |
| `page_no` | Integer | 否 | `1` | 页码，默认从 1 开始 |
| `page_size` | Integer | 否 | `20` | 分页大小，默认每页 20 条数据 |

---

## 4. 响应参数

响应主体包裹在 `data` 中，返回门店库存模式列表与分页信息。

| 根级参数名称 | 类型 | 描述说明 |
| :--- | :--- | :--- |
| `success` | Boolean | 请求是否成功 (`true`/`false`) |
| `code` | Integer | 状态码，`200` 表示成功，`-100` 表示系统错误 |
| `message` | String | 成功或错误提示信息 |
| `request_id` | String | 请求 ID（官方标注：已作废） |
| `data` | Object | **查询结果总包** |

### 4.1 `data` 内部核心业务字段解构

| 内部模块结构 / 数组 | 类型 | 核心包含内容与说明 |
| :--- | :--- | :--- |
| **`open_stock_mode_search_d_t_o`** | List | **库存模式明细列表** |
| └─ `kdt_id` | Long | 店铺/门店底层 ID 标识 |
| └─ `team_name` | String | 店铺/门店名称（如：测试门店） |
| └─ `shop_role` | Integer | 店铺类型。`2`-门店；`3`-独立仓；`6`-分销供货商店铺；`7`-前置仓 |
| └─ `stock_mode` | Integer | **库存模式**。<br>`1`-独立销售库存<br>`2`-共享总部库存<br>`3`-共享门店仓库存库<br>`4`-进出存单据管理 |
| └─ `order_manager_stock` | Integer | 单据管理库存开关（门店专用）。`1`-开启，`0`-关闭 |
| **`paginator`** | Object | **分页信息对象** |
| └─ `page` | Integer | 当前页码 |
| └─ `page_size` | Integer | 当前页大小 |
| └─ `total_count` | Integer | 匹配到的总条数（用于前端计算总页数） |

---

## 5. 响应示例 (JSON)

### 5.1 成功响应示例

```json
{
    "trace_id": "yz7-0ae82d0e-1677750929750-364981",
    "code": 200,
    "success": true,
    "message": "successful",
    "data": {
        "open_stock_mode_search_d_t_o":[
            {
                "kdt_id": 18938611,
                "team_name": "YZ-零售单店（别改名字）鄧",
                "shop_role": 0,
                "stock_mode": 3,
                "order_manager_stock": 1
            }
        ],
        "paginator": {
            "total_count": 1,
            "page": 1,
            "page_size": 20
        }
    }
}
```

---

## 6. ⚠️ 开发者防坑指南与注意事项（核心排错）

1. **必传参数 `retail_source` 遗漏阻断**：
   有赞零售（Retail）体系的接口，有部分老业务逻辑强依赖 `retail_source`（零售调用来源）。此字段在文档中明确标注为**必填（是）**。如果不传，接口会直接报错拦截。如果您是常规自用型应用对接，通常约定传 `"YOUZAN"` 或咨询有赞服务小二获取专属标识。
2. **错误码 `-100` 的核心排查方向（Token 权限越界）**：
   如果接口返回 `{"code": -100, "message": "服务器错误"}`，除了检查必填参数外，**最常见的原因是 `access_token` 的授权主体不匹配**。
   * **排查建议**：请检查申请 Token 的授权 ID 是否是连锁“总部”、“单店”或“合伙人”级别的 ID。例如，用一个无下属门店的普通微商城 Token 试图去拉取总部结构，就会触发越界报错。
3. **`node_kdt_id` 与网点架构关系**：
   * **单店系统**：不要传 `node_kdt_id`。
   * **连锁总部系统**：如果需要一次性获取旗下所有门店的模式（常用于 ERP 系统初始化对账），不传此参数即可查全部；如果由于业务变动需要校验某一家具体分店是否切换了共享仓，传入该分店的 `kdt_id` 精确点查，效率最高。
4. **`stock_mode` 共享库存拦截提醒**：
   当 `stock_mode` 返回值为 `2`（共享总部库存）时，意味着该门店没有独立的实物库存管理权限。此时如果您通过代码强行调用门店库存扣减/入库的 API，有赞底层会报错拦截。业务逻辑上必须将库存扣减的指令路由指向其**共享总部**的店铺 ID 或总仓。