分页查询微商城销售中和已售罄商品列表 (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)

请求地址：

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`	排序方式，格式为 `字段名:升降序`。支持：`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	否	`[123, 234]`	店内组织末级节点 ID 列表，最大不能超过 200
`node_kdt_id`	Long	否	`54731007`	有赞连锁网店店铺 ID，仅供连锁场景使用，判断信息归属网店
`search_code_type`	Integer	否	`3`	编码查询类型：`1` 编码，`2` 条码，`3` 规格编码，`4` 规格条码
`search_code_list`	List	否	`["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	商品分组(标签) ID 列表（包含1、2级分组）
`group_names`	List	分组名称列表，如 `["全部分组", "T恤"]`
(其他链接类)	String	`image` (主图链接), `page_url` (小程序路径), `detail_url` (H5链接)

4.2 `items` 内嵌复杂对象 (图片、运费、属性等)

在每个商品对象中，还包含以下级联对象，用于描述商品更立体的属性：

对象/数组名称	内部核心字段说明
`delivery_template` (运费模板)	`delivery_template_id`(模板ID), `delivery_template_name`(名称), `delivery_template_fee`(运费范围，单位：元), `delivery_template_valuation_type`(计费类型 `1`按件 `2`按重量 `3`体积)
`item_imgs` (图片列表)	包含商品轮播图等：`id`(图片ID), `url`(原图链接), `thumbnail`(缩略图), `medium`(中图), `created`(创建时间)
`sku_extension_attributes` (SKU扩展属性)	`sku_id`(规格ID), `cost_price`(成本价)
`meas_prop` (重量与计量)	内部包裹 `meas` 数组。包含：`sku_id`(商品规格ID), `weight`(规格维度重量，单位：克)
`properties` (类目相关属性)	分为 `publics` (公域属性，如品牌、材质) 和 `privates` (私域属性，如商家自定义的颜色、尺码)。内含 `pro_name`(属性名) 和 `val_names`(属性值名称列表)

(注：如果需要对多规格商品进行深度的库存或价格修改，建议结合 youzan.item.detail.get 获取完整的 SKU 明细节点。)

5. 请求与响应示例

5.1 Java SDK 调用示例

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 - 全量结构截取)

{
    "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. ⚠️ 常见使用问题与避坑指南

接口查询状态限制（无法查全库） 注意：此接口只能查到状态为 “销售中” 以及 “已售罄” 的商品。它不支持查询“仓库中”的商品。若需对全店商品库对账，需搭配 youzan.items.inventory.get 使用；如果是连锁总部的商品库，需使用 youzan.item.common.search。
库存数量的陷阱 (quantity vs actual_quantity) 当您的店铺属于“门店渠道”(channel = 1) 时，旧版的 quantity 字段因为单位换算问题，会被强制放大 1000倍（如实际库存 66 个会返回 66000）。强烈建议开发者在业务逻辑中直接取用 actual_quantity 字段，该字段官方已自动处理好了单位转换，始终代表真实的物理库存数量。
分页与查询深度的限制 接口严格限制 page_size * page_no <= 4000 条。如果店铺内商品总数超过 4000 个，无法仅通过增加页码拉取全量数据。解决方案：利用 update_time_start 和 update_time_end 进行时间切片（例如每次查询1个月内的更新记录），循环遍历全量数据。
时间戳单位是“毫秒” 请仔细核对您的入参。update_time_start 和 update_time_end 必须传递 13 位毫秒级时间戳，如果后端语言默认生成的是 10 位秒级时间戳，会导致无法匹配数据返回空。
增量更新推荐：WebHook 推送 如果您需要对店铺内的商品信息进行双向准实时同步，官方不推荐使用本接口进行“定时高频死循环轮询”。正确的姿势是：订阅有赞云商品变更消息推送（如 ITEM_UPDATE、ITEM_CREATE），在接收到商品变更的 item_id 后，再针对该单品去调用接口更新本地数据库。

12 KiB Raw Permalink Blame History Unescape Escape

分页查询微商城销售中和已售罄商品列表 (youzan.item.search.3.0.0)

1. 接口基本信息

2. 请求说明

3. 请求参数 (全量)

4. 响应参数

4.1 items 数组内商品基础字段

4.2 items 内嵌复杂对象 (图片、运费、属性等)

5. 请求与响应示例

5.1 Java SDK 调用示例

5.2 响应示例 (JSON - 全量结构截取)

6. ⚠️ 常见使用问题与避坑指南

12 KiB

Raw Permalink Blame History

4.1 `items` 数组内商品基础字段

4.2 `items` 内嵌复杂对象 (图片、运费、属性等)