实战解析电商api：1688item_search-按关键字搜索商品数据

一、接口能力总览

item_search 是 1688 开放平台最高频的接口之一，支持按关键字、类目、价格区间、起批量等多条件组合筛选，返回字段覆盖：

商品基础：ID、标题、主图、详情页 URL
批发属性：阶梯价、起订量、是否混批、是否跨境专供
供应商信息：店铺名称、诚信通年限、30 天成交笔数
库存/销量：可售库存、30 天成交量、评价数

一次请求最多 50 条，官方 QPS=1，企业账号可上浮至 5 。

二、权限与凭证

企业开发者认证（营业执照+对公打款）
创建应用 → 申请 com.alibaba.product.search 权限 → 拿到 AppKey / AppSecret
通过 OAuth2.0 客户端模式获取 AccessToken，有效期 3600 s，需缓存提前刷新。

三、签名生成（Python 版）

1688 采用「参数 ASCII 升序 + key=value 拼接 + AppSecret」后 MD5 大写：

python 复制代码

import hashlib, urllib.parse, time, requests

def 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'])

返回单条记录示例：

javascript 复制代码

{
  "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
}

五、字段深坑指南

字段	注意点
priceRange	字符串，单位"元"，已包含阶梯价区间；如需精确到 SKU 级价格，需再调 `item.get` 。
quantity	为"展示库存"，真实可售看 `availableQuantity`（若存在）。
moq	最小起订量，部分类目支持混批，需结合 `mixWholeSale=true` 判断。
creditYears	诚信通年限，可作为供应商实力粗筛。
sale30	30 天成交件数，非 GMV；若=0 不代表无销量，可能新上架。

六、性能与合规

频率：官方默认 1 QPS，峰值超过直接 403；批量请加 time.sleep(1) 或申请企业配额。
翻页：最多 50 页×50 条=2500 条；深翻请缩小关键词+增量时间戳。
数据合规：禁止落地用户隐私（手机号、地址），商品价格不可直接在前台展示，必须跳转 1688 详情页。

七、小结

item_search 接口本身很轻，但「签名+令牌+翻页+字段解析」四个节点全是坑。把本文的 Client 类直接套进项目，再配一张「字段-含义-异常值」映射表，基本就能在 30 分钟内搭起一条可上线的 1688 关键词搜索通道，后续无论是选品、比价还是供应链可视化，都能即插即用。