1688.item_search工程实战：1688商品列表API分页采集与B2B货源数据分析落地

摘要 ：在跨境选品、供应链调研、ERP 货源池搭建、供应商数据分析等开发场景，需要批量结构化获取 1688 批发商品数据。本文以 1688 商品列表 API（1688.item_search）为核心，从接口参数、分页实现逻辑、数据解析、限流处理到 B2B 批发场景特有的开发问题做完整梳理，包含可直接复用的 Python 伪代码与踩坑总结，适合电商后端、数据采集、供应链系统开发者参考。

---

一、为什么要用接口而不是爬页面

做跨境供应链系统这几年，1688 货源数据采集是绕不开的模块。最早团队试过直接爬搜索结果页，问题很明显：

1. 页面结构频繁改版，选择器一改，解析逻辑全挂；
2. 反爬策略升级，IP 封禁、滑块验证层出不穷；
3. 1688 是 B2B 平台，批发阶梯价、起订量、实力商家标识散落在页面各处，HTML 解析维护成本极高。

后来切换到1688.item_search商品列表 API，直接拿结构化 JSON，不用处理 HTML，稳定性和开发效率都上了一个台阶。这篇文章把我们落地过程中踩过的坑整理出来，供同行参考。

二、接口能力与核心入参

1688.item_search的定位是搜索型接口，通过关键词或类目 ID 返回 1688 批发商品列表摘要。它和商品详情接口是互补关系：列表接口负责 "找商品"，详情接口负责 "拿完整数据"。

接口名称：1688.product.search （Taobaoapi2014前往体验）

请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）

接口版本：2.0

核心能力：关键词检索，支持价格区间、起订量、地区、实力商家、发货能力等多维度过滤，返回商品标题、阶梯批发价、MOQ、供应商信息、30 天成交、诚信通资质等 B2B 批发字段。

核心入参

参数	类型	必填	说明
q	string	是	搜索关键词
cat	int	否	类目 ID，指定类目下搜索
page	int	是	页码，从 1 开始
page_size	int	否	每页条数，受接口最大限制
sort	string	否	排序规则：综合、销量、价格等
start_price / end_price	float	否	价格区间筛选

接口能拿到什么

列表接口返回的是摘要级数据：商品 ID、标题、展示批发价、主图、销量、最小起订量、店铺信息、发货地、是否广告、是否实力商家。

它拿不到的 ：多档阶梯批发价、SKU 规格、详情 HTML、多图数组、产品参数、真实库存。这些必须拿着返回的num_iid再调用 1688 商品详情接口二次补齐。

这个边界一定要在项目设计阶段就想清楚，否则做到一半发现字段不够，返工成本很高。

三、返回数据结构解析

顶层响应

字段	类型	说明
code	int	0= 成功，非 0 = 异常
message	string	成功返回ok，失败返回错误描述
data	object	搜索业务主体

data 对象

字段	类型	说明
total	int	搜索预估总商品数，仅参考，不可作为分页依据
page	int	当前页码
page_size	int	每页条数
page_count	int	预估总页数，存在翻页上限，不可信
item_list	arrayobject	商品摘要数组，核心数据

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	店铺 ID
seller_nick	string	店铺名称
cat_id / cat_name	int / string	类目 ID 与名称
province / city	string	发货地
item_url	string	商品 H5 链接
is_ad	boolean	是否广告推广商品
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
            }
        ]
    }
}

四、分页逻辑：最容易踩的坑

分页是这个接口开发中翻车率最高的地方。

很多人看到total=42600、page_count=2130，就写个 for 循环从 1 翻到 2130 页。实际跑起来会发现，翻到一定深度之后，item_list直接返回空数组，但接口不报错 ------1688 搜索接口存在最大翻页上限，深层数据根本拿不到。

正确做法 ：不依赖total和page_count，每次请求后判断item_list是否为空，为空立即终止分页。

import time

def fetch_1688_search(keyword, start_page=1):
    page = start_page
    all_items = []
    while True:
        resp = call_1688_item_search_api(q=keyword, page=page, page_size=20)
        if resp.get("code") != 0:
            print(f"第{page}页调用失败: {resp.get('message')}")
            break
        item_list = resp.get("data", {}).get("item_list", [])
        if not item_list:
            # 到达翻页上限，终止
            break
        all_items.extend(item_list)
        save_items_to_db(item_list)
        page += 1
        time.sleep(0.8)  # 控制请求间隔
    return all_items

# 执行采集
result = fetch_1688_search("夏季纯棉T恤")

五、B2B 场景特有的处理逻辑

1688 和淘宝、京东最大的区别在于它是B2B 批发平台，有几个字段必须重点处理：

1. 最小起订量 min_order

这是 1688 独有的核心字段。很多商品要求 2 件起批、5 件起批，甚至有些是混批规则。做自动采购系统时，如果不校验min_order，订单数量达不到起批要求，采购接口直接报错。

建议 ：在商品入库时就把min_order存好，采购下单前做前置校验，不满足的走人工审核或合并订单。

2. 批发阶梯价

列表接口返回的price只是展示价，实际 1688 大量商品是多档阶梯价 ------ 买 2 件一个价，买 50 件一个价，买 500 件又一个价。

列表接口拿不到完整阶梯价，必须调用商品详情接口补齐。在做价格分析、采购成本核算时，要结合实际采购数量匹配对应档位，不能直接拿列表展示价计算。

3. 实力商家标识 is_kaiguan

做供应链选品时，is_kaiguan=true的实力商家 / 工厂店铺通常更可靠，发货稳定性、售后保障更好。可以在选品筛选逻辑中加入这个维度，优先推荐实力商家货源。

4. 广告商品过滤

is_ad=true是付费推广商品，做市场统计、价格分布分析时如果不过滤，数据会被广告商品带偏。建议在数据分析场景统一过滤广告商品，在选品场景可以保留但做标记。

六、其他高频踩坑点

图片防盗链

1688 的 CDN 图片带有防盗链，直接把pic_url放到自己系统里展示，过一段时间就 403 裂图。必须下载转存到自有对象存储，替换资源地址后再使用。

接口限流

多关键词批量遍历搜索，很容易触发限流。我们的方案是：

• 接入任务队列，所有搜索请求走队列；
• 控制 QPS，单关键词请求间隔不低于 0.8 秒；
• 失败重试采用指数退避，最多重试 3 次；
• 对不常变动的类目搜索结果做短期缓存，减少重复调用。

下架商品

搜索结果中会混入已下架商品，列表接口不一定能准确反映状态。建议在商品入库后，结合详情接口做一次商品状态二次校验，标记失效商品。

价格字段类型

返回的price可能是字符串也可能是浮点，做价格排序、区间筛选、统计分析时，务必统一转为数值类型，避免字符串比对造成逻辑 bug。

七、完整业务流程总结

关键词/类目配置
    ↓
调用1688.item_search获取商品列表
    ↓
判断item_list是否为空 → 为空则终止分页
    ↓
解析商品摘要，过滤广告商品
    ↓
存入候选货源池（含num_iid、min_order、price、is_kaiguan）
    ↓
按需调用1688商品详情接口补齐：阶梯价、SKU、详情图文、参数
    ↓
图片下载转存、HTML详情清洗
    ↓
供给选品、采购、价格监控、供应链分析模块

八、适用业务场景

1. 跨境选品系统：按关键词批量构建 1688 货源候选池，筛选实力商家、高销量商品
2. ERP 货源采集：自动采购系统前期商品检索，配合详情接口完成完整货源入库
3. 产业带数据分析：统计类目批发价格分布、起订量分布、地域供应商分布
4. 货源溯源：配合图搜接口，批量检索同款货源，做比价和供应商替代
5. 价格监控：定时抓取目标关键词商品快照，跟踪批发价格波动

九、总结

1688.item_search是 1688B2B 货源数据采集的入口级接口，开发难点不在于接口调用本身，而在于：

• 分页边界处理 ：以item_list为空作为终止条件，不要信total和page_count；
• B2B 字段理解 ：min_order、阶梯价、实力商家标识是 1688 独有的，必须重点处理；
• 接口边界认知：列表只返回摘要，完整数据必须配合详情接口；
• 工程稳定性：限流、缓存、重试、图片转存、下架校验，这些工程细节决定系统能不能长期稳定运行。