分页查询库存模式 (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 格式)

请求地址：

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`	按特定库存模式筛选。不传则查全部模式。 `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	库存模式。 `1`-独立销售库存 `2`-共享总部库存 `3`-共享门店仓库存库 `4`-进出存单据管理
└─ `order_manager_stock`	Integer	单据管理库存开关（门店专用）。`1`-开启，`0`-关闭
`paginator`	Object	分页信息对象
└─ `page`	Integer	当前页码
└─ `page_size`	Integer	当前页大小
└─ `total_count`	Integer	匹配到的总条数（用于前端计算总页数）

5. 响应示例 (JSON)

5.1 成功响应示例

{
    "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. ⚠️ 开发者防坑指南与注意事项（核心排错）

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

5.5 KiB Raw Blame History Unescape Escape

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

1. 接口基本信息

2. 请求说明

3. 请求参数

4. 响应参数

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

5. 响应示例 (JSON)

5.1 成功响应示例

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

5.5 KiB

Raw Blame History

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