# 查询门店商品信息 (youzan.retail.open.offline.spu.query.3.0.0) ## 1. 接口基本信息 * **API 名称**：查询门店商品信息 * **API 接口名**：`youzan.retail.open.offline.spu.query` * **版本号**：`3.0.0` * **计费规则**：基础接口，调用计费 * **接口描述**：查询门店商品信息。**注意：系统有严格的查询深度限制，`page_no * page_size` 的乘积不能大于 3300。** --- ## 2. 请求说明 * **请求协议**：HTTPS * **请求方式**：POST (请求体传参，`application/json` 格式) * **请求地址**： ```http https://open.youzanyun.com/api/youzan.retail.open.offline.spu.query/3.0.0 ``` --- ## 3. 请求参数 | 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 | | :--- | :--- | :---: | :--- | :--- | | `access_token` | String | **是** | `9b510e232...` | 鉴权凭证，用于请求 API | | `retail_source` | String | **是** | `YOUZAN` | 零售调用来源。*(注：该字段已于2021-04-26号废弃取消校验，新接入开发者无需传值，已对接开发者不受影响)* | | `warehouse_code` | String | 否 | `TEST001` | **仓库编码**。可通过 `youzan.retail.open.warehouse.query` 接口获取；**如果不填，默认查总部商品库商品** | | `show_display` | Integer | 否 | `0` | 销售状态。`0`：已售罄；`1`：销售中；`2`：在库中。**不传值默认查询“销售中”状态** | | `page_no` | Integer | 否 | `1` | 页码，从 1~300 开始的正整数。(`page_no * page_size` 总数不超过3300) | | `page_size` | Integer | 否 | `20` | 每页条数，默认 20 条。(`page_no * page_size` 总数不超过3300) | | `name_or_sku_no` | String | 否 | `商品1` | 搜索条件：商品名称 / 商品条码 | | `item_ids` | List | 否 | `[12312321]` | 商品 Id 列表（适用于首次通过该接口批量获取存入数据库，后续查询时取出导入的场景） | --- ## 4. 响应参数 响应主体包裹在 `data` 中，主要分为 `paginator` (分页信息) 和 `offline_spus` (门店商品明细)。 | 根级参数名称 | 类型 | 描述说明 | | :--- | :--- | :--- | | `success` | Boolean | 表示本次请求是否成功 (`true`/`false`) | | `code` | Integer | 网关返回码，`200` 表示成功 | | `message` | String | 网关返回码描述 | | `data` | Object | **响应参数总包** | | └─ `paginator` | Object | **分页数据对象** | |     ├─ `page` | Integer | 页码，从 1 开始正整数 | |     ├─ `page_size` | Integer | 每页条数。默认 20 条 | |     └─ `total_count` | Integer | 匹配到的总条数 | | └─ `offline_spus`| List | **门店商品 (SPU) 信息列表** | ### 4.1 `offline_spus` (门店商品明细) 与 `sku_models` (规格明细) 结构解构 | 内部参数名称 | 类型 | 核心说明 | | :--- | :--- | :--- | | `item_id` | Long | 门店商品 Id，有赞生成的店铺下商品唯一 Id | | `title` | String | 商品名称 | | `spu_no` | String | 商品条码 | | `price` | String | 零售价 | | `max_guide_price`| String | 最大建议零售价（单位：元） | | `min_guide_price`| String | 最小建议零售价（单位：元） | | `unit` | String | 单位（如：件） | | `sell_stock_count`| String | 销售库存 | | `sold_num` | String | 总销量 | | `created_at` | String | 创建时间 | | `is_display` | Integer | 是否上架：`1` (上架)；`0` (未上架) | | `measurement` | Integer | 称重非称重商品标识：`0` (非称重)；`10` (称重) | | `has_multi_sku` | Boolean | 是否多规格：`true` (是)；`false` (否) | | `is_non_spec` | Boolean | 是否无规格：`true` (是)；`false` (否) | | `category_name` | String | 商品分组名称 | | `specifications` | String | 规格信息（如：`"XL"`） | | `tax_code` | String | 税收分类编码（商家配置开具电子发票时自定义填写） | | `plu_code` | String | PLU 码 | | `biz_mark_code` | String | 商品标编码（如 `"010000000002"`） | | `biz_mark_name` | String | 商品标名称。枚举对应：
`"010000000002"`：预售商品
`"020000000001"`：零售连锁
`"000000000041"`：餐饮商品
`"010000000042"`：生鲜果蔬商品
`"010000000043"`：海淘跨境商品 | | **`sku_models`** | List | **门店商品 SKU (规格) 信息列表** | |   ├─ `sku_id` | Long | 规格 Id，有赞生成的店铺下商品规格唯一 Id | |   ├─ `sku_no` | String | 规格条码（支持商家自定义，英文数字组合，店铺下唯一） | |   ├─ `specs` | String | 规格信息（如：`"红色，XL"`） | |   ├─ `price` | String | 价格 | |   ├─ `max_guide_price`| String | 最大建议零售价 | |   ├─ `min_guide_price`| String | 最小建议零售价 | |   ├─ `plu_code` | String | PLU 码 | |   └─ `unit` | String | 单位 | --- ## 5. ⚠️ 开发者防坑指南与注意事项（基于官方文档） 1. **严格的深度查询限制 (`3300` 限制)**： 文档特别强调了 Elasticsearch 的搜索深度约束：`page_no * page_size` 的**乘积绝对不能超过 3300**。例如当 `page_size` 为默认的 20 时，最多只能翻到第 165 页。如果要查询的数据量庞大，切忌无脑通过递增页码扫库，以免触发限制报错。 2. **`warehouse_code`（仓库编码）的归属逻辑**： * 如果您**不传**此参数：接口默认只去查询“总部商品库”的商品信息。 * 如果您想要查询某家特定门店的下发商品与价格信息，必须传入正确的、通过 `youzan.retail.open.warehouse.query` 获取到的特定门店仓库编码（如 `TEST001`）。 * **报错预警：**如果传入了错误或不存在的编码，系统将返回错误码 `234007003` (不合法的仓库编码)。 3. **`show_display` 默认行为过滤**： 请注意，如果请求时不传 `show_display` 参数，接口底层会自动帮您**过滤掉**下架在库和已售罄的商品，**只返回状态为“1：销售中”的商品**。如果有盘库需求，需要找回仓库里的下架商品，请务必显式传入对应的状态值。 4. **废弃的 `retail_source` 字段**： 官方已明确声明该字段自 2021-04-26 起已取消校验。新接入的开发者无需关心或给该参数传值，不会影响接口的正常调用。 5. **查询结果为空处理 (`234002001` 错误码)**： 如果在传入 `name_or_sku_no` 后没有匹配到任何结果，接口会返回错误码 `234002001`（无商品信息）。在代码侧编写逻辑时，需对此错误码做特殊的“无数据”放行处理，而不是作为异常直接抛出。