1688 商品详情 API 是 B2B 供应链系统对接的核心接口，主要用于获取商品的基础信息、SKU 规格、批发价格及库存。针对你关心的实战调用与字段解析，我为你整理了一份可直接运行的 Python 代码，并附上高频字段解析与避坑指南。
一、 接口选择与前置准备
- 接口对比（选型建议）
1688 开放平台有多个商品接口，建议根据业务场景选择：
接口名 适用场景 特点
alibaba.item.get 推荐。通用商品详情，支持非授权访问 无需 access_token，可获取公开商品信息（如标题、价格、主图）
alibaba.product.get 自有商品管理 需 OAuth2 授权，只能查询自己店铺的商品
实战建议：如果你只是做选品、比价或同步第三方商品，直接使用 alibaba.item.get 即可。
- 必备参数
• AppKey / AppSecret：在 1688 开放平台创建应用后获取。
• Item ID：商品 ID，通常为长整型（如 699788888888）。
二、 Python 实战：封装 API 客户端
以下代码封装了完整的签名生成与请求逻辑，支持字段过滤以提升性能。
import hashlib
import time
import requests
from typing import Dict, Any, Optional
封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
class Ali1688ItemAPI:
"""1688 商品详情 API 客户端 (基于 alibaba.item.get)"""
def __init__(self, app_key: str, app_secret: str):
self.app_key = app_key
self.app_secret = app_secret
self.base_url = "https://gw.open.1688.com/openapi/param2/2/alibaba.item.get/2.0"
def _generate_sign(self, params: Dict[str, Any]) -> str:
"""
生成 1688 API 签名 (MD5)
规则：1. 按 Key 升序排序 2. 拼接 key+value 3. 首尾加上 AppSecret 4. MD5 转大写
"""
# 过滤空值并排序
sorted_params = sorted([(k, v) for k, v in params.items() if v is not None])
# 拼接 key+value
sign_str = ''.join([f"{k}{v}" for k, v in sorted_params])
# 首尾拼接 AppSecret 并计算 MD5
sign_str = f"{self.app_secret}{sign_str}{self.app_secret}"
return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
def get_item_detail(self, item_id: str, fields: Optional[str] = None) -> Dict[str, Any]:
"""
获取商品详情
Args:
item_id: 1688 商品 ID
fields: 指定返回字段，多个用逗号分隔（推荐使用，减少响应体积）
"""
# 1. 组装公共参数
params = {
'app_key': self.app_key,
'method': 'alibaba.item.get',
'timestamp': str(int(time.time() * 1000)), # 13位毫秒时间戳
'format': 'json',
'v': '2.0',
'item_id': item_id,
}
# 2. 可选：字段过滤（极大提升性能）
if fields:
params['fields'] = fields
# 3. 生成签名
params['sign'] = self._generate_sign(params)
# 4. 发送请求
try:
resp = requests.get(self.base_url, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()
# 5. 错误处理
if 'error_response' in data:
error = data['error_response']
raise Exception(f"API Error [{error.get('code')}]: {error.get('msg')}")
# 提取商品数据
return data.get('alibaba_item_get_response', {}).get('item', {})
except requests.exceptions.RequestException as e:
raise Exception(f"Request failed: {e}")
==================== 使用示例 ====================
if name == "main":
# 初始化（密钥建议放在环境变量中）
client = Ali1688ItemAPI(
app_key="你的AppKey",
app_secret="你的AppSecret"
)
try:
# 指定需要的字段（减少网络传输，提升性能）
fields = "item_id,title,price,sku_list,pics,spec_info,shop_name"
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 调用接口（替换为真实的商品ID）
result = client.get_item_detail("商品ID", fields=fields)
# 解析关键字段
print("商品标题:", result.get('title'))
print("参考价格:", result.get('price'))
print("店铺名称:", result.get('shop_name'))
# 解析SKU列表
sku_list = result.get('sku_list', [])
for sku in sku_list:
print(f"SKU ID: {sku.get('sku_id')}, 价格: {sku.get('price')}")
except Exception as e:
print(f"调用失败: {e}")
三、 核心返回字段解析（B2B 重点）
1688 的返回数据结构与淘宝 API 差异较大，重点关注以下 B2B 特色字段：
- 基础信息
字段名 类型 说明 示例
item_id Long 商品唯一 ID 699788888888
title String 商品标题（含营销词） "2025新款 纯棉T恤 批发"
status String 商品状态 published（已上架）
shop_name String 店铺名称 "某某服装厂"
- 价格与库存（B2B 特色）
字段名 说明 业务含义
price 参考价格（字符串） 通常是起批价，如 "19.90"
sku_list SKU 数组 核心：每个 SKU 包含 spec_attributes（规格）、price、amount_on_sale（可售库存）
spec_info 规格文本 如 "颜色:红色;尺码:M" 的纯文本描述
注意：1688 的价格通常是阶梯价（区间价），price 字段可能只显示最低价，详细阶梯价需解析 sku_list 或调用专门的价格接口 。
- 图片与详情
字段名 说明
pics 主图 URL 列表（含详情图）
desc 商品详情 HTML（需申请额外权限或调用详情接口）
四、 高频避坑点（面试/实战）
签名错误（401）
◦ 原因：参数排序错误（必须按 ASCII 升序）、时间戳格式错误（必须 13 位毫秒）、AppSecret 拼接错误。◦ 解决：严格使用上述代码中的 _generate_sign 方法。
字段权限不足
◦ 现象：返回数据中缺少 shop_name 或 sku_list。◦ 解决：在 1688 开放平台后台，申请接口权限时务必勾选“非授权商品访问”，否则只能获取极少的公开字段 。
数据延迟
◦ 注意：1688 接口数据存在 10-30 分钟缓存，并非实时更新。对于库存、价格敏感的业务，需在业务层做容错 。限流（429）
◦ 策略：默认 QPS 限制较严格（通常 5-10 次/秒），生产环境务必加入重试机制（如指数退避）或队列控制。
五、 面试加分项
如果面试中问到 1688 API 对接，除了代码实现，可以补充以下架构思考：
• 字段过滤：使用 fields 参数只获取必要字段，减少 70% 的响应体积，提升性能 。
• 密钥安全：AppSecret 必须通过环境变量或配置中心管理，严禁硬编码在代码中。
• 降级策略：当 1688 API 不稳定时，如何利用本地缓存（Redis）的旧数据保证业务不中断。
