摘要：在跨境选品、供应链调研、ERP 货源池搭建、供应商数据分析业务中，经常需要批量获取 1688B2B 批发商品结构化摘要数据。1688.item_search商品列表 API，支持关键词、类目检索、价格筛选、分页查询，返回商品标题、批发展示价、最小起订量、店铺、发货地等摘要信息。本文从接口概述、请求入参、返回字段解析、标准 JSON 样例、业务流程、开发踩坑、业务场景完整讲解，适合电商后端、数据采集、供应链系统开发者参考。
一、接口概述
1688.item_search为 1688 商品列表搜索接口，作为 B2B 货源采集的入口接口，可以根据关键词或者类目 ID 批量获取商品摘要。
接口名称：1688.product.search （Taobaoapi2014 前往体验）
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
接口版本：2.0
核心能力：关键词检索，支持价格区间、起订量、地区、实力商家、发货能力等多维度过滤，返回商品标题、阶梯批发价、MOQ、供应商信息、30 天成交、诚信通资质等 B2B 批发字段。
接口能力覆盖
- 商品基础摘要：标题、展示批发价、划线价、近 30 天销量
- B2B 批发特有字段：最小起订量、实力商家工厂标识
- 多媒体基础资源：商品主图地址
- 店铺与地域信息：店铺 ID、店铺名称、发货省市
- 辅助标记：广告商品标记、类目信息
二、核心请求入参
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| q | string | 是 | 搜索关键词 |
| cat | int | 否 | 类目 ID，限定类目范围检索 |
| page | int | 是 | 请求页码，起始值为 1 |
| page_size | int | 否 | 单页返回条数，受接口限制 |
| sort | string | 否 | 排序类型：综合、销量、价格升 / 降序 |
| start_price | float | 否 | 价格区间‑最低价格 |
| end_price | float | 否 | 价格区间‑最高价格 |
三、返回数据结构解析
顶层响应结构
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 0调用成功；非 0 代表异常错误码 |
| message | string | 提示信息，成功返回 ok，失败返回错误描述 |
| data | object | 搜索业务主体对象 |
data 对象字段
| 字段 | 类型 | 说明 |
|---|---|---|
| total | int | 搜索预估总商品数量，仅做参考，不可作为分页循环依据 |
| page | int | 当前请求页码 |
| page_size | int | 每页返回商品条数 |
| page_count | int | 预估总页数，接口存在翻页上限，该字段不可信 |
| item_list | array[object] | 商品摘要数组，核心业务数据集 |
item_list 单条商品对象字段
| 字段 | 类型 | 说明 |
|---|---|---|
| num_iid | bigint | 1688 商品 ID，调用商品详情接口核心入参 |
| title | string | 商品完整标题 |
| price | float | 列表展示批发单价，多阶梯批发仅展示第一档价格 |
| original_price | float | 划线原价，无划线价返回 0 |
| pic_url | string | 商品主图 CDN 地址 |
| sales | int | 近 30 天成交销量 |
| min_order | int | 最小起订件数，B2B 批发核心字段 |
| shop_id | bigint | 1688 店铺 ID |
| seller_nick | string | 店铺名称 |
| cat_id | int | 商品类目 ID |
| cat_name | string | 商品类目完整名称 |
| province | string | 发货省份 |
| city | string | 发货城市 |
| item_url | string | 商品 H5 访问链接 |
| is_ad | boolean | 是否广告推广商品；true 为付费广告，统计分析建议过滤 |
| is_kaiguan | boolean | 实力商家 / 工厂店铺标识 |
四、标准 JSON 返回示例
{ "code": 0, "message": "ok", "data": {"total": 42600,"page": 1,"page_size": 20,"page_count": 2130,"item_list": [{"num_iid": 678923451123,"title": "夏季纯棉短袖T恤 男士宽松大码 工厂现货批发","price": 19.80,"original_price": 39.00,"pic_url": "https://gw.alicdn.com/demo.jpg","sales": 23600,"min_order": 2,"shop_id": 56789123,"seller_nick": "XX服饰工厂店","cat_id": 10166,"cat_name": "男装>男士T恤","province": "浙江","city": "杭州","item_url": "https://detail.1688.com/offer/678923451123.html","is_ad": false,"is_kaiguan": true}]}}
五、完整业务处理流程
- 传入关键词 / 类目 ID、页码、价格区间参数调用1688.item_search；
- 判断顶层code状态码，捕获接口调用异常；
- 获取data.item_list商品摘要数组；判断数组为空，直接终止分页，不要依赖 total、page_count；
- 业务按需过滤广告商品is_ad=true；
- 将商品摘要存入货源候选池，保存num_iid用于后续详情接口调用；
- 异步任务拿着商品 ID 调用 1688 商品详情接口补齐阶梯价、SKU、参数、详情图文；
- 图片资源下载转存自有对象存储，处理防盗链 403 问题；
- 全量数据清洗完成入库，供给选品、采购、数据分析模块。
六、开发高频踩坑总结
- 分页逻辑陷阱接口存在最大翻页深度，total、page_count仅为预估值。禁止循环总页数分页，业务上以 item_list 为空作为分页终止条件。
- 批发阶梯价格缺陷列表接口price只是展示价格，1688 大量商品有多档拿货阶梯价，完整阶梯价格必须调用详情接口获取；采购成本计算不能直接使用列表价格。
- 最小起订量 min_orderB2B 批发核心字段，自动采购业务必须读取校验；如果下单数量达不到最小起订，会直接造成采购接口报错。
- 广告商品干扰统计is_ad=true为付费推广商品，做类目价格、销量统计时建议过滤，避免统计数据失真。
- 图片防盗链 1688CDN 图片开启防盗链，直接引用会出现 403 裂图；业务系统需要下载图片并转存自有存储。
- 限流与任务队列多关键词批量搜索极易触发接口限流；大批量业务必须接入任务队列，控制 QPS，增加休眠、指数退避重试逻辑。
- 下架商品兼容搜索结果依旧会返回已下架商品，列表接口无法识别商品真实状态；入库后建议搭配详情接口做二次状态校验。
- 字段类型兼容部分场景价格字段可能返回字符串类型，代码需要统一转为数值，防止排序、统计出现逻辑错误。
七、Python 简易调用伪代码
def fetch_1688_item_search(keyword, page=1):resp = call_1688_item_search_api(q=keyword, page=page, page_size=20)if resp.get("code") != 0:print("接口调用失败", resp.get("message"))return []item_list = resp.get("data", {}).get("item_list", [])# 保存候选商品到数据库save_candidate_goods(item_list)return item_list# 调用示例goods = fetch_1688_item_search("夏季纯棉T恤", page=1)
八、落地业务场景
- 跨境 ERP 系统：批量构建 1688 批发货源候选池，用于选品分析
- 自动采购系统：前期商品检索，配合详情接口完成完整货源入库
- 产业带数据分析：类目批发价格、起订量、供应商地域分布统计
- 货源溯源业务：结合图片搜索接口，批量检索同款替代货源
- 竞品货源监控：定时抓取关键词商品快照，跟踪批发价格波动
九、总结
1688.item_search是 1688B2B 货源采集的入口接口，主要负责商品检索拿到摘要数据集。开发重点不在于简单接口调用，而在于分页边界处理、B2B 批发业务字段理解、限流重试、图片防盗链处理，同时要明确接口能力边界，搭配商品详情接口拿到完整货源数据。处理好上述工程细节，接口可以稳定支撑跨境选品、供应链分析、自动采购等业务系统。
