youzan-datahub/docs/餐饮零售数据中台/有赞接口/5.查询总部下门店和仓库信息 (youzan.retail.open.warehouse.query.3.0.0).md

查询总部下门店和仓库信息 (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 格式)

• 请求地址：

  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 请求，可能会拉取为空或提示权限不足。