207 lines
12 KiB
Markdown
207 lines
12 KiB
Markdown
# 分页查询微商城销售中和已售罄商品列表 (youzan.item.search.3.0.0)
|
||
|
||
## 1. 接口基本信息
|
||
|
||
* **API 名称**：分页查询微商城销售中和已售罄商品列表
|
||
* **API 接口名**：`youzan.item.search`
|
||
* **版本号**：`3.0.0`
|
||
* **计费规则**：基础接口，调用计费（具体以控制台能力包购买为准）。
|
||
* **接口描述**：用于分页综合查询处于“**销售中**”和“**已售罄**”状态的商品列表。支持按关键字、分组、品牌、类目、更新时间等多种维度组合筛选。
|
||
* **⚠️ 注意**：此接口**无法查询到“仓库中”的商品**（如下架商品），若需查询下架或仓库中商品需调用 `youzan.items.inventory.get`。
|
||
|
||
---
|
||
|
||
## 2. 请求说明
|
||
|
||
* **请求协议**：HTTPS
|
||
* **请求方式**：GET/POST (推荐 POST `application/json`)
|
||
* **请求地址**：
|
||
|
||
```http
|
||
https://open.youzanyun.com/api/youzan.item.search/3.0.0
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 请求参数 (全量)
|
||
|
||
| 参数名称 | 类型 | 是否必须 | 示例值 | 参数说明 |
|
||
| :--- | :--- | :---: | :--- | :--- |
|
||
| `access_token` | String | **是** | `9b510e232c9...` | 有赞云 API 鉴权凭证 |
|
||
| `q` | String | 否 | `薯片` | 搜索字段，支持搜索：商品名（模糊匹配） |
|
||
| `item_ids` | String | 否 | `457692126,45745...` | 作为查询条件的商品 ID 列表，以逗号分隔，用于精确筛选 |
|
||
| `page_no` | Integer | 否 | `1` | 页码，从 1~100 开始，分页数不能超过 100 页。`page_size` 和 `page_no` 相乘总条数不能大于 4000 条 |
|
||
| `page_size` | Integer | 否 | `20` | 每页数量，要求小于 50，默认 20 |
|
||
| `order_by` | String | 否 | `update_time:desc` | 排序方式，格式为 `字段名:升降序`。<br>支持：`created_time`(创建时间)、`update_time`(更新时间)、`price`(价格)、`sold_num`(销量) |
|
||
| `update_time_start`| Long | 否 | `1563379200000` | 更新时间**起始**，Unix时间戳，**时间单位：ms（毫秒）** |
|
||
| `update_time_end` | Long | 否 | `1563465600000` | 更新时间**截止**，Unix时间戳，**时间单位：ms（毫秒）** |
|
||
| `show_sold_out` | Integer | 否 | `0` | 是否在售：`0`—在售，`1`—售罄或部分售罄，`2`—全部 |
|
||
| `tag_ids` | String | 否 | `106590,106593` | 作为查询的分组(标签) ID 列表，以逗号分隔 |
|
||
| `brand_ids` | String | 否 | `1254378,86662` | 作为查询的品牌 ID 列表，以逗号分隔 |
|
||
| `category_ids` | String | 否 | `67263,71822` | 作为查询的分类 ID 列表，以逗号分隔 |
|
||
| `leaf_category_id` | Long | 否 | `9723123` | 新版商品类目（V4版本）叶子类目 ID |
|
||
| `shop_org_ids` | List<Long>| 否 | `[123, 234]` | 店内组织末级节点 ID 列表，最大不能超过 200 |
|
||
| `node_kdt_id` | Long | 否 | `54731007` | 有赞连锁网店店铺 ID，仅供连锁场景使用，判断信息归属网店 |
|
||
| `search_code_type` | Integer | 否 | `3` | 编码查询类型：`1` 编码，`2` 条码，`3` 规格编码，`4` 规格条码 |
|
||
| `search_code_list` | List<String>| 否 | `["BM111","BM222"]` | 对应上述类型的编码数组，限制 100 个 |
|
||
| `item_source` | Integer | 否 | `0` | 商品创建类型：`0` 普通；`1` 网店自建 (仅支持连锁分店) |
|
||
| `offline_id` | Long | 否 | `58853441` | 多网点 ID |
|
||
| `channel` | Integer | 否 | `0` | 店铺渠道类型：`-1`：全部渠道；`0`：网店； `1`：门店。默认网店。 |
|
||
|
||
---
|
||
|
||
## 4. 响应参数
|
||
|
||
响应结果主体以 `data` 包裹，主要包含商品总数 `count` 和商品对象列表 `items`。
|
||
|
||
| 根级参数名称 | 类型 | 描述说明 |
|
||
| :--- | :--- | :--- |
|
||
| `success` | Boolean | 业务请求是否成功 (`true`/`false`) |
|
||
| `code` | Integer | 状态码，`200` 为成功 |
|
||
| `message` | String | 成功或错误的提示消息 |
|
||
| `data.count` | Integer | 搜索到的符合条件的商品总数量（用于前端计算总页数） |
|
||
| `data.items` | Array | 商品详细信息集合 |
|
||
|
||
### 4.1 `items` 数组内商品基础字段
|
||
|
||
| 字段名 | 类型 | 字段说明 |
|
||
| :--- | :--- | :--- |
|
||
| `item_id` | Long | 商品唯一标识（有赞内部商品 ID） |
|
||
| `alias` | String | 商品别名，可用于拼接商品前端 H5/小程序详情页链接 |
|
||
| `title` | String | 商品名称/标题 |
|
||
| `sub_title` | String | 商品分享描述 / 副标题 |
|
||
| `price` | Long | 商品当前售卖价（单位：**分**，如 100 代表 1元） |
|
||
| `origin` | String | 划线价（单位：**元**） |
|
||
| `item_no` | String | 商家自行填写的商品编码（支持英文和数字组合） |
|
||
| `quantity` | Long | 库存数量（注：门店渠道下会被放大 1000 倍展示） |
|
||
| `actual_quantity` | String | 实际总库存（自动处理门店渠道放大 1000 倍的转换问题，建议以该字段为准） |
|
||
| `item_type` | Integer | 商品类型：`0`普通 `3`降价拍 `5`外卖 `10`分销 `20`会员卡 `60`虚拟 `61`电子卡券等 |
|
||
| `channel` | Integer | 归属渠道类型：`0`网店 `1`门店 |
|
||
| `post_type` | Integer | 运费类型：`1`—统一运费，`2`—运费模板 |
|
||
| `post_fee` | Long | 统一运费的费用（单位：分） |
|
||
| `created_time` | String | 创建时间，格式 `"yyyy-MM-dd HH:mm:ss"` |
|
||
| `update_time` | String | 最后更新时间，格式 `"yyyy-MM-dd HH:mm:ss"` |
|
||
| `has_multi_sku` | Boolean | 是否包含多规格（多 SKU）商品 |
|
||
| `tag_ids` | List<Long> | 商品分组(标签) ID 列表（包含1、2级分组） |
|
||
| `group_names` | List<String>| 分组名称列表，如 `["全部分组", "T恤"]` |
|
||
| *(其他链接类)* | String | `image` (主图链接), `page_url` (小程序路径), `detail_url` (H5链接) |
|
||
|
||
### 4.2 `items` 内嵌复杂对象 (图片、运费、属性等)
|
||
|
||
在每个商品对象中，还包含以下级联对象，用于描述商品更立体的属性：
|
||
|
||
| 对象/数组名称 | 内部核心字段说明 |
|
||
| :--- | :--- |
|
||
| **`delivery_template`**<br>*(运费模板)* | `delivery_template_id`(模板ID), `delivery_template_name`(名称), `delivery_template_fee`(运费范围，单位：**元**), `delivery_template_valuation_type`(计费类型 `1`按件 `2`按重量 `3`体积) |
|
||
| **`item_imgs`**<br>*(图片列表)* | 包含商品轮播图等：`id`(图片ID), `url`(原图链接), `thumbnail`(缩略图), `medium`(中图), `created`(创建时间) |
|
||
| **`sku_extension_attributes`**<br>*(SKU扩展属性)* | `sku_id`(规格ID), `cost_price`(成本价) |
|
||
| **`meas_prop`**<br>*(重量与计量)* | 内部包裹 `meas` 数组。包含：`sku_id`(商品规格ID), `weight`(规格维度重量，单位：**克**) |
|
||
| **`properties`**<br>*(类目相关属性)* | 分为 `publics` (公域属性，如品牌、材质) 和 `privates` (私域属性，如商家自定义的颜色、尺码)。内含 `pro_name`(属性名) 和 `val_names`(属性值名称列表) |
|
||
|
||
*(注：如果需要对多规格商品进行深度的库存或价格修改，建议结合 `youzan.item.detail.get` 获取完整的 SKU 明细节点。)*
|
||
|
||
---
|
||
|
||
## 5. 请求与响应示例
|
||
|
||
### 5.1 Java SDK 调用示例
|
||
|
||
```java
|
||
YZClient client = new DefaultYZClient(new Token("YOUR_ACCESS_TOKEN"));
|
||
|
||
YouzanItemSearchParams youzanItemSearchParams = new YouzanItemSearchParams();
|
||
// 搜索关键字
|
||
youzanItemSearchParams.setQ("薯片");
|
||
// 设置按更新时间降序排列
|
||
youzanItemSearchParams.setOrderBy("update_time:desc");
|
||
// 仅查询在售商品
|
||
youzanItemSearchParams.setShowSoldOut(0);
|
||
// 设置页码和每页数量
|
||
youzanItemSearchParams.setPageNo(1);
|
||
youzanItemSearchParams.setPageSize(20);
|
||
|
||
YouzanItemSearch youzanItemSearch = new YouzanItemSearch();
|
||
youzanItemSearch.setAPIParams(youzanItemSearchParams);
|
||
|
||
YouzanItemSearchResult result = client.invoke(youzanItemSearch);
|
||
```
|
||
|
||
### 5.2 响应示例 (JSON - 全量结构截取)
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "successful",
|
||
"data": {
|
||
"count": 18,
|
||
"items":[
|
||
{
|
||
"item_id": 365112687,
|
||
"alias": "2x9272j7pmw9q",
|
||
"title": "一袋薯片",
|
||
"price": 1000,
|
||
"origin": "15.00",
|
||
"item_no": "spbm001",
|
||
"quantity": 66,
|
||
"actual_quantity": "66",
|
||
"item_type": 0,
|
||
"channel": 0,
|
||
"post_type": 2,
|
||
"post_fee": 0,
|
||
"created_time": "2019-03-24 11:04:24",
|
||
"update_time": "2019-03-25 11:04:24",
|
||
"has_multi_sku": false,
|
||
"group_names":["零食", "全部分组"],
|
||
"image": "https://img.yzcdn.cn/upload_files/2019/03/08/Foya.jpg",
|
||
"page_url": "packages/goods/detail/index",
|
||
"delivery_template": {
|
||
"delivery_template_id": 658289,
|
||
"delivery_template_name": "杭州市按件计费",
|
||
"delivery_template_fee": "16.00",
|
||
"delivery_template_valuation_type": 1
|
||
},
|
||
"item_imgs":[
|
||
{
|
||
"id": 365112687,
|
||
"url": "https://img.yzcdn.cn/upload_files/2019/03/08/Foya.jpg",
|
||
"thumbnail": "https://img.yzcdn.cn/upload_files/2019/03/08/Foya.jpg?imageView2/2/w/290/h/290"
|
||
}
|
||
],
|
||
"properties": {
|
||
"publics":[
|
||
{
|
||
"pro_id": 123,
|
||
"pro_name": "品牌",
|
||
"val_names": ["乐事"]
|
||
}
|
||
],
|
||
"privates":[
|
||
{
|
||
"pro_id": 124,
|
||
"pro_name": "口味",
|
||
"val_names": ["番茄味"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. ⚠️ 常见使用问题与避坑指南
|
||
|
||
1. **接口查询状态限制（无法查全库）**
|
||
注意：此接口只能查到状态为 **“销售中”** 以及 **“已售罄”** 的商品。它**不支持**查询“仓库中”的商品。若需对全店商品库对账，需搭配 `youzan.items.inventory.get` 使用；如果是连锁总部的商品库，需使用 `youzan.item.common.search`。
|
||
2. **库存数量的陷阱 (`quantity` vs `actual_quantity`)**
|
||
当您的店铺属于“门店渠道”(`channel = 1`) 时，旧版的 `quantity` 字段因为单位换算问题，会被强制放大 **1000倍**（如实际库存 66 个会返回 66000）。**强烈建议开发者在业务逻辑中直接取用 `actual_quantity` 字段**，该字段官方已自动处理好了单位转换，始终代表真实的物理库存数量。
|
||
3. **分页与查询深度的限制**
|
||
接口严格限制 `page_size * page_no <= 4000` 条。如果店铺内商品总数超过 4000 个，无法仅通过增加页码拉取全量数据。**解决方案**：利用 `update_time_start` 和 `update_time_end` 进行时间切片（例如每次查询1个月内的更新记录），循环遍历全量数据。
|
||
4. **时间戳单位是“毫秒”**
|
||
请仔细核对您的入参。`update_time_start` 和 `update_time_end` 必须传递 **13 位毫秒级时间戳**，如果后端语言默认生成的是 10 位秒级时间戳，会导致无法匹配数据返回空。
|
||
5. **增量更新推荐：WebHook 推送**
|
||
如果您需要对店铺内的商品信息进行双向准实时同步，官方不推荐使用本接口进行“定时高频死循环轮询”。正确的姿势是：订阅有赞云商品变更消息推送（如 `ITEM_UPDATE`、`ITEM_CREATE`），在接收到商品变更的 `item_id` 后，再针对该单品去调用接口更新本地数据库。
|