1688商品详情抓取API接口接入指南

在电商数据驱动业务的场景中，1688 作为国内核心的 B2B 电商平台，其商品详情数据（如价格、库存、规格、供应商信息等）对竞品分析、供应链优化、定价策略制定具有重要价值。本文将基于 1688 开放平台规范，详细讲解商品详情抓取 API 接口的接入全流程，帮助开发人员高效实现数据获取功能。

一、接入前准备工作

在调用 1688 API 前，需完成账号注册、应用创建及环境配置，确保满足接口调用的基础条件。

1.1 注册 1688 开发者账号

1. 访问1688 开放平台官网，点击右上角 “注册”，选择 “企业开发者” 或 “个人开发者” 身份（企业身份权限更全，建议优先选择）；

1. 按提示完成实名认证（需提供企业营业执照 / 个人身份证、银行账户信息等），审核通过后即可获得开发者权限。

1.2 创建应用并获取凭证

1. 登录 1688 开放平台后，进入 “控制台 - 应用管理”，点击 “创建应用”；

1. 填写应用名称（如 “商品详情抓取工具”）、应用描述、应用类型（选择 “服务端应用”），并提交平台审核（审核通常 1-3 个工作日）；

1. 审核通过后，在应用详情页获取核心凭证：

• App Key：应用唯一标识，用于接口调用时的身份识别；
• App Secret：应用密钥，用于接口签名验证，需妥善保管，避免泄露。

1.3 环境与工具准备

1. 开发语言：支持 Java、Python、PHP、Node.js 等主流语言，本文以 Python（3.8+）为例演示；

1. 依赖库：

• 接口请求：requests（处理 HTTP 请求）；
• 数据解析：json（解析接口返回的 JSON 数据）、lxml（可选，处理商品详情页 HTML 片段）；
• 签名计算：hashlib（实现 MD5 加密，用于接口签名）；

1. 调试工具：Postman（用于接口调试，验证请求参数与响应格式）、1688 开放平台 “API 测试工具”（在接口文档页直接调试）。

二、核心接口选择与参数说明

1688 开放平台提供多个与商品详情相关的 API，其中 **“item_get” 接口 **（获取单个商品详情）是最常用的接口，支持获取商品基础信息、价格、库存、规格、供应商等核心数据。

2.1 接口基础信息

• 接口地址：https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get

• 请求方式：GET/POST（推荐 POST，避免参数暴露在 URL 中）

• 接口权限：需在 “开放平台 - 权限管理” 中申请 “商品详情查询权限”（个人开发者需额外提交用途说明）

2.2 核心请求参数

参数名	类型	是否必填	说明
app_key	String	是	应用唯一标识（从应用详情页获取）
method	String	是	接口名称，固定为 “com.alibaba.product.alibaba.product.get”
timestamp	String	是	时间戳，格式为 “yyyy-MM-dd HH:mm:ss”（如 2024-05-20 14:30:00），与服务器时间误差不超过 10 分钟
format	String	是	响应格式，固定为 “json”
v	String	是	接口版本，当前最新版本为 “2.0”
sign	String	是	签名值，用于验证请求合法性（生成规则见下文）
productId	String	是	1688 商品 ID（可从商品详情页 URL 中提取，如 URL“https://detail.1688.com/offer/123456789.html” 中，productId 为 “123456789”）
fields	String	否	需返回的字段列表，多个字段用逗号分隔（如 “productId,productTitle,price,stock”），不填则返回全部字段

三、接口签名生成（关键步骤）

1688 API 采用 “参数排序 + MD5 加密” 的签名机制，确保请求未被篡改。签名生成步骤如下：

3.1 签名生成规则

1. 收集所有请求参数（含 app_key、method、timestamp 等必选参数，不含 sign 本身）；

1. 将参数按 “参数名 ASCII 码升序” 排序（如 “app_key” 在 “method” 之前，因为 “a” 的 ASCII 码小于 “m”）；

1. 按 “参数名 = 参数值” 的格式拼接所有排序后的参数，形成字符串（如 “app_key=123456&format=json&method=com.alibaba.product.alibaba.product.get&productId=123456789&timestamp=2024-05-20 14:30:00&v=2.0”）；

1. 在拼接字符串末尾添加 “&secret=App Secret”（App Secret 为应用详情页获取的密钥）；

1. 对最终字符串进行 MD5 加密（32 位小写），结果即为 sign 值。

3.2 Python 签名生成示例代码

import hashlib

import time

def generate_sign(params, app_secret):

"""

生成1688 API签名

:param params: 请求参数字典（不含sign）

:param app_secret: 应用密钥

:return: 32位小写MD5签名

"""

# 1. 按参数名ASCII升序排序

sorted_params = sorted(params.items(), key=lambda x: x[0])

# 2. 拼接参数字符串

param_str = "&".join([f"{k}={v}" for k, v in sorted_params])

# 3. 拼接secret

sign_str = f"{param_str}&secret={app_secret}"

# 4. MD5加密

sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest()

return sign

# 示例：构造参数并生成签名

app_key = "your_app_key"

app_secret = "your_app_secret"

product_id = "123456789"

# 构造请求参数（不含sign）

params = {

"app_key": app_key,

"method": "com.alibaba.product.alibaba.product.get",

"timestamp": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()),

"format": "json",

"v": "2.0",

"productId": product_id,

"fields": "productId,productTitle,price,stock,sellerName" # 需返回的字段

}

# 生成签名

sign = generate_sign(params, app_secret)

params["sign"] = sign # 将sign加入请求参数

四、接口调用与响应解析

完成签名生成后，即可发起接口请求，并对返回的 JSON 数据进行解析，提取所需的商品详情信息。

4.1 Python 接口调用示例

import requests

def call_1688_product_api(params):

"""

调用1688商品详情API

:param params: 含sign的完整请求参数

:return: 解析后的商品详情字典

"""

api_url = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get"

try:

# 发起POST请求（推荐）

response = requests.post(api_url, data=params, timeout=10)

# 检查响应状态码

if response.status_code != 200:

raise Exception(f"请求失败，状态码：{response.status_code}")

# 解析JSON响应

result = response.json()

# 检查接口返回状态（1688 API用"success"字段标识成功）

if not result.get("success"):

error_msg = result.get("errorMessage", "未知错误")

error_code = result.get("errorCode", "未知错误码")

raise Exception(f"接口调用失败，错误码：{error_code}，错误信息：{error_msg}")

# 返回商品详情数据（核心数据在"result.product"中）

return result.get("result", {}).get("product", {})

except Exception as e:

print(f"接口调用异常：{str(e)}")

return {}

# 调用接口并获取商品详情

product_detail = call_1688_product_api(params)

print("商品详情：", product_detail)

4.2 响应数据解析示例

接口返回的product_detail为 JSON 格式字典，核心字段解析如下：

# 提取关键商品信息

if product_detail:

# 商品基础信息

product_id = product_detail.get("productId") # 商品ID

product_title = product_detail.get("productTitle") # 商品标题

product_url = product_detail.get("detailUrl") # 商品详情页URL

# 价格信息（单位：元，多规格商品需遍历"skuList"）

base_price = product_detail.get("price", {}).get("price") # 基础价格

sku_list = product_detail.get("skuList", []) # 规格列表（如颜色、尺寸）

for sku in sku_list:

sku_spec = sku.get("specInfo") # 规格描述（如"红色-XL"）

sku_price = sku.get("price", {}).get("price") # 规格对应价格

sku_stock = sku.get("stock") # 规格对应库存

print(f"规格：{sku_spec}，价格：{sku_price}元，库存：{sku_stock}件")

# 供应商信息

seller_name = product_detail.get("seller", {}).get("sellerName") # 供应商名称

seller_level = product_detail.get("seller", {}).get("level") # 供应商等级（如"实力商家"）

print(f"商品ID：{product_id}\n标题：{product_title}\n基础价格：{base_price}元\n供应商：{seller_name}（{seller_level}）")

五、接入注意事项

5.1 接口调用限制

1. 频率限制：1688 对 API 调用频率有严格控制（如个人开发者单应用单日调用上限 1000 次，企业开发者上限 5000 次），需在 “开放平台 - 应用监控” 中查看实时调用量，避免超限（超限后接口会返回errorCode: 429，需等待次日重置）；

1. IP 限制：同一 IP 地址调用频率不得超过 10 次 / 秒，建议通过 “IP 池” 或 “请求延时”（如time.sleep(0.1)）控制频率。

5.2 权限与合规性

1. 仅可抓取已获得权限的商品数据，禁止抓取未授权的隐私信息（如买家联系方式、供应商营业执照敏感信息）；

1. 需遵守《1688 开放平台服务协议》，数据仅用于合法商业用途，不得用于恶意爬取、竞品攻击等违规行为。

5.3 错误处理与重试机制

1. 常见错误码及处理方案：

• 400：参数错误（检查 productId 是否正确、timestamp 格式是否符合要求）；
• 401：签名错误（重新核对 App Secret、参数排序是否正确）；
• 403：权限不足（申请 “商品详情查询权限”）；
• 500：服务器异常（添加重试机制，建议重试 3 次，每次间隔 2 秒）；

1. 实现重试逻辑示例：

def call_api_with_retry(params, max_retry=3, retry_interval=2):

retry_count = 0

while retry_count < max_retry:

product_detail = call_1688_product_api(params)

if product_detail:

return product_detail

retry_count += 1

print(f"第{retry_count}次重试，间隔{retry_interval}秒...")

time.sleep(retry_interval)

print("重试次数耗尽，接口调用失败")

return {}

六、总结与扩展

本文通过 “准备工作 - 签名生成 - 接口调用 - 数据解析 - 注意事项” 的流程，完成了 1688 商品详情抓取 API 的核心接入讲解。开发人员可基于本文示例，结合实际业务需求优化功能：

1. 批量抓取：通过循环传入多个productId，实现多商品详情批量获取（需注意控制调用频率）；

1. 数据存储：将解析后的商品数据存入 MySQL、MongoDB 等数据库，方便后续分析；

1. 监控告警：对接日志系统（如 ELK）或告警工具（如钉钉机器人），实时监控接口调用状态，避免故障遗漏。