分页查询库存模式 (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 Permalink 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 Permalink Blame History

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