一、1688商品采集API核心概述

1.1 核心作用

1.2 核心API接口介绍

• 商品详情查询API：核心接口，支持通过商品ID查询单个商品的完整信息，包括商品标题、价格、规格参数、图文详情、库存、卖家信息等。

• 商品列表查询API：支持通过关键词、类目、价格区间等条件筛选商品，获取商品列表数据（含商品ID、标题、价格、销量等基础信息），适合批量筛选目标商品。

• 商品属性查询API：专门用于获取指定商品的属性参数（如材质、尺寸、产地等），补充商品详情数据的完整性。

• 卖家商品列表API：通过卖家ID查询其店铺内的所有商品，适合对特定卖家的商品进行批量采集。

1.3 接口限制与资费

二、API接入前准备工作

2.1 注册并认证1688开放平台账号

1. 访问1688开放平台官网（https://open.1688.com/），注册开发者账号（个人或企业均可，企业认证后权限更高）。

2. 完成账号实名认证，提交相关资质材料（个人身份证、企业营业执照等），等待平台审核通过。

2.2 创建应用并获取接入凭证

1. 登录开放平台后，进入“开发者中心-应用管理”，点击“创建应用”，填写应用名称、应用类型、应用描述等信息，提交审核。

2. 应用审核通过后，进入应用详情页，获取核心接入凭证：appKey（应用唯一标识）和appSecret（应用密钥，用于签名验证，需妥善保管）。

2.3 了解接口授权机制

1. 引导用户跳转至1688授权页面，用户确认授权后，返回授权码（code）。

2. 使用appKey、appSecret和授权码，调用令牌接口获取访问令牌（accessToken）和刷新令牌（refreshToken）。

3. 调用API时，需在请求头或参数中携带accessToken（有效期一般为2小时，过期后可用refreshToken刷新）。

2.4 环境准备

# 安装请求库和JSON解析库
pip install requests
pip install json5

三、1688商品采集API调用核心流程

3.1 通用调用流程

1. 拼接请求参数：根据接口文档，整理必要的请求参数（如appKey、商品ID、accessToken等）。

2. 生成签名：1688 API要求对请求参数进行签名验证，签名规则为：将参数按字母顺序排序，拼接appSecret后进行MD5加密，得到签名（sign）。

3. 发送HTTP请求：通过GET或POST方式向接口地址发送请求（多数1688 API支持GET请求）。

4. 解析响应数据：接口返回JSON格式数据，解析数据并提取所需字段（如商品标题、价格等）。

5. 异常处理：针对限流、授权过期、参数错误等异常情况，处理返回的错误码（如400参数错误、401未授权、429限流）。

3.2 签名生成核心逻辑（Python示例）

import hashlib

def generate_sign(params, app_secret):
    # 1. 按参数名ASCII升序排序
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    # 2. 拼接参数键值对（key1value1key2value2...）
    sign_str = ''.join([f"{k}{v}" for k, v in sorted_params])
    # 3. 拼接appSecret
    sign_str += app_secret
    # 4. MD5加密，转大写
    sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
    return sign

四、实战：商品详情API调用示例

4.1 接口信息（以商品详情查询API为例）

• 接口地址：https://gw.open.1688.com/openapi/param2/2/2015-05-20/offer.get.json

• 请求方式：GET

• 核心参数：appKey、accessToken、offerId（商品ID）、sign（签名）

4.2 完整调用代码

import requests
import hashlib

# 配置信息（替换为自己的appKey、appSecret、accessToken）
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
ACCESS_TOKEN = "your_access_token"
OFFER_ID = "1234567890123"  # 目标商品ID

def generate_sign(params, app_secret):
    """生成签名"""
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    sign_str = ''.join([f"{k}{v}" for k, v in sorted_params])
    sign_str += app_secret
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()

def get_offer_detail(offer_id):
    """调用商品详情API，获取商品信息"""
    # 1. 构造请求参数
    params = {
        "appKey": APP_KEY,
        "accessToken": ACCESS_TOKEN,
        "offerId": offer_id,
        "format": "json"  # 指定返回格式为JSON
    }
    # 2. 生成签名
    params["sign"] = generate_sign(params, APP_SECRET)
    # 3. 发送请求
    url = "https://gw.open.1688.com/openapi/param2/2/2015-05-20/offer.get.json"
    try:
        response = requests.get(url, params=params, timeout=10)
        # 4. 解析响应
        if response.status_code == 200:
            result = response.json()
            # 处理成功响应
            if result.get("errorCode") == 0:
                return result["result"]
            else:
                print(f"接口调用失败：{result.get('errorMessage')}")
                return None
        else:
            print(f"HTTP请求失败，状态码：{response.status_code}")
            return None
    except Exception as e:
        print(f"请求异常：{str(e)}")
        return None

if __name__ == "__main__":
    # 调用接口获取商品详情
    offer_detail = get_offer_detail(OFFER_ID)
    if offer_detail:
        # 提取核心字段
        product_info = {
            "商品ID": offer_detail.get("offerId"),
            "商品标题": offer_detail.get("title"),
            "原价": offer_detail.get("originalPrice"),
            "现价": offer_detail.get("price"),
            "销量": offer_detail.get("saleCount"),
            "卖家ID": offer_detail.get("memberId"),
            "卖家名称": offer_detail.get("memberName"),
            "商品详情链接": offer_detail.get("detailUrl")
        }
        # 打印结果
        for key, value in product_info.items():
            print(f"{key}: {value}")

4.3 响应数据解析说明

• offerId：商品唯一ID，用于后续数据关联。

• title：商品标题，包含核心卖点和关键词。

• price/originalPrice：现价和原价，注意单位（一般为元）。

• saleCount：商品销量（部分商品可能不返回）。

• detail：商品图文详情，包含图片URL和文本描述。

• specInfo：商品规格信息（如颜色、尺寸等）。

五、关键注意事项

5.1 严格遵守平台规范，避免违规

• 不得超出API授权范围采集数据，禁止采集平台禁止获取的隐私数据（如买家信息）。

• 数据仅用于自身合法业务，不得转售、泄露或用于恶意竞争。

• 严格控制调用频率，避免触发限流（可通过添加延时、合理分批采集优化）。

5.2 处理授权过期问题

def refresh_access_token(refresh_token):
    """使用refreshToken刷新accessToken"""
    params = {
        "appKey": APP_KEY,
        "appSecret": APP_SECRET,
        "refreshToken": refresh_token,
        "grantType": "refresh_token"
    }
    url = "https://gw.open.1688.com/openapi/oauth2/refresh_token.json"
    response = requests.get(url, params=params)
    result = response.json()
    if result.get("errorCode") == 0:
        return result["accessToken"], result["refreshToken"]
    else:
        print(f"刷新token失败：{result.get('errorMessage')}")
        return None, None

5.3 异常处理与容错设计

• 针对网络波动，添加请求重试机制（使用requests.adapters.HTTPAdapter配置重试次数）。

• 对返回的错误码进行分类处理：401（重新授权）、429（降低频率、延时重试）、500（服务端错误，稍后重试）。

• 采集数据时实时备份，避免因程序崩溃导致数据丢失。

5.4 注意数据格式差异

六、总结与延伸