106 lines
6.6 KiB
Markdown
106 lines
6.6 KiB
Markdown
# 查询门店商品信息 (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<Long> | 否 | `[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 | 商品标名称。枚举对应：<br>`"010000000002"`：预售商品<br>`"020000000001"`：零售连锁<br>`"000000000041"`：餐饮商品<br>`"010000000042"`：生鲜果蔬商品<br>`"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`（无商品信息）。在代码侧编写逻辑时，需对此错误码做特殊的“无数据”放行处理，而不是作为异常直接抛出。
|