一、接口能力总览
item_search 是 1688 开放平台最高频的接口之一，支持按关键字、类目、价格区间、起批量等多条件组合筛选，返回字段覆盖：- 商品基础：ID、标题、主图、详情页 URL
- 批发属性：阶梯价、起订量、是否混批、是否跨境专供
- 供应商信息：店铺名称、诚信通年限、30 天成交笔数
- 库存/销量：可售库存、30 天成交量、评价数
二、权限与凭证
- 企业开发者认证（营业执照+对公打款）
- 创建应用 → 申请
com.alibaba.product.search权限 → 拿到 AppKey / AppSecret - 通过 OAuth2.0 客户端模式获取 AccessToken，有效期 3600 s，需缓存提前刷新。
三、签名生成（Python 版）
1688 采用「参数 ASCII 升序 + key=value 拼接 + AppSecret」后 MD5 大写：
Python
import hashlib, urllib.parse, time, requestsdef generate_sign(params: dict, secret: str) -> str:
params = {k: v for k, v in params.items() if v is not None}
sorted_str = ''.join([f'{k}{v}' for k, v in sorted(params.items())]) + secret return hashlib.md5(sorted_str.encode()).hexdigest().upper()四、最小可运行示例
下面示例一次性封装「获取令牌 → 生成签名 → 搜索 → 解析」全流程，可直接复制跑通：
Python
class Client:
def __init__(self, app_key: str, app_secret: str):
self.app_key = app_key
self.app_secret = app_secret
self.token = None
self.expire = 0
self.token_url = 'https://gw.open.1688.com/openapi/http/1/system.oauth2/getToken'
self.search_url = 'https://gw.open.1688.com/openapi/param2/2/portals.open.api.item.search'
# ----------- 令牌管理 -----------
def _refresh_token(self):
if self.expire > time.time() + 60:
return
body = {
'grant_type': 'client_credentials',
'client_id': self.app_key,
'client_secret': self.app_secret }
r = requests.post(self.token_url, data=body, timeout=10).json()
self.token = r['access_token']
self.expire = time.time() + int(r['expires_in'])
# ----------- 搜索核心 -----------
def item_search(self, keyword, page=1, page_size=20, **opt):
self._refresh_token()
params = {
'method': 'portals.open.api.item.search',
'app_key': self.app_key,
'access_token': self.token,
'format': 'json', 'v': '1.0',
'timestamp': str(int(time.time() * 1000)),
'keywords': keyword,
'page': page,
'pageSize': page_size,
**opt }
params['sign'] = generate_sign(params, self.app_secret)
r = requests.post(self.search_url, data=params, timeout=15).json()
if 'error_response' in r:
raise RuntimeError(r['error_response']['msg'])
result = r['item_search_response']
return {
'total': result['totalCount'],
'items': result['items']['item']
}# ----------- 调用 -----------cli = Client('你的AppKey', '你的AppSecret')ret = cli.item_search('蓝牙耳机', page=1, page_size=10)for i in ret['items']:
print(i['title'], i['priceRange'], i['moq'])返回单条记录示例：
JSON
{
"offerId": 64321098756,
"title": "TWS 蓝牙耳机 5.3 无线降噪 批发代发",
"imageUrl": "https://cbu01.alicdn.com/img/ibank/1180/288/123/1238828811.jpg",
"detailUrl": "https://detail.1688.com/offer/64321098756.html",
"priceRange": "38.0~45.0",
"moq": 2,
"quantity": 9999,
"sellerName": "深圳某某电子厂",
"creditYears": 6,
"sale30": 1374}五、字段深坑指南
六、性能与合规
- 频率：官方默认 1 QPS，峰值超过直接 403；批量请加
time.sleep(1)或申请企业配额。 - 翻页：最多 50 页×50 条=2500 条；深翻请缩小关键词+增量时间戳。
- 数据合规：禁止落地用户隐私（手机号、地址），商品价格不可直接在前台展示，必须跳转 1688 详情页。
七、小结
item_search 接口本身很轻，但「签名+令牌+翻页+字段解析」四个节点全是坑。把本文的 Client 类直接套进项目，再配一张「字段-含义-异常值」映射表，基本就能在 30 分钟内搭起一条可上线的 1688 关键词搜索通道，后续无论是选品、比价还是供应链可视化，都能即插即用。
如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。
