youzan-datahub/docs/餐饮零售数据中台/有赞接口/3.分页查询销售中和已售罄商品列表 (youzan.item.search.3.0.0).md

# 分页查询微商城销售中和已售罄商品列表 (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` 后，再针对该单品去调用接口更新本地数据库。