一、接口概述与定位
1688 跨境寻源通 API 是 1688 开放平台专为跨境电商打造的供应链数据解决方案，其中商品详情接口是核心能力之一。该接口为跨境卖家、ERP 系统及铺货工具提供全维度商品数据支持，覆盖商品基础属性、批发价格、库存、SKU 规格、供应商资质等关键信息。
适用场景：选品分析、一键铺货、价格监控、跨境供应链管理。
二、接入前准备
2.1 开发者资质要求
寻源通 API 面向企业开发者，个人开发者权限受限。接入前需完成：
-
**注册企业开发者账号：**选择"企业开发者"类型，提交营业执照完成实名认证（审核约 1-2 个工作日）。
-
创建应用 ：在控制台"应用管理"中创建应用，选择"跨境寻源通"应用类型，获取
AppKey和AppSecret。 -
申请接口权限 ：在"接口权限"页面勾选详情相关接口（如
alibaba.product.get），提交使用场景说明（审核约 3 个工作日）。
2.2 认证与授权
接口采用 OAuth2.0 授权流程获取 access_token：
# 1. 引导用户授权
GET https://open.1688.com/auth/authorize.htm?
response_type=code&
client_id=YOUR_APP_KEY&
redirect_uri=YOUR_CALLBACK_URL
# 2. 用授权码换取 access_token
POST https://open.1688.com/openapi/http/1/system.oauth2/getToken/2.0
grant_type=authorization_code&
client_id=YOUR_APP_KEY&
client_secret=YOUR_APP_SECRET&
code=AUTHORIZATION_CODE三、核心详情接口详解
3.1 接口基础信息
| 项目 | 说明 |
|---|---|
| 接口名称 | 获取商品详情 |
| 请求地址 | https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get |
| 请求方式 | HTTP POST |
| 数据格式 | application/x-www-form-urlencoded |
| 响应格式 | JSON |
| 签名算法 | MD5 / HMAC-SHA256 |
3.2 请求参数
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|---|---|---|---|---|
app_key |
String | 是 | 应用唯一标识 | 12345678 |
method |
String | 是 | 接口方法名 | com.alibaba.product.alibaba.product.get |
timestamp |
String | 是 | 时间戳（yyyy-MM-dd HH:mm:ss） | 2026-04-27 16:30:00 |
v |
String | 是 | API 版本 | 2.0 |
format |
String | 是 | 响应格式 | json |
sign |
String | 是 | MD5 签名 | E4F2G3H4... |
access_token |
String | 是 | OAuth2.0 授权令牌 | - |
productId |
Long | 是 | 1688 商品 ID | 619899292404 |
fields |
String | 否 | 指定返回字段（逗号分隔） | shippingInfo,saleInfo,skuInfo |
fields 常用字段 ：
subject（标题）、priceRanges（价格区间）、imageUrl（主图）、skuInfo（SKU信息）、saleInfo（销售信息）、shippingInfo（物流信息）、productFeatureList（商品属性）。
3.3 签名生成规则
签名是接口安全调用的关键，算法如下：
python
import hashlib
def generate_sign(params, app_secret):
# 1. 移除 sign 参数，按参数名 ASCII 升序排序
sorted_params = sorted((k, v) for k, v in params.items() if k != 'sign')
# 2. 拼接字符串：app_secret + key1value1key2value2... + app_secret
sign_str = app_secret + ''.join(f"{k}{v}" for k, v in sorted_params) + app_secret
# 3. MD5 加密并转大写
return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()四、返回数据结构解析
接口返回标准 JSON 结构，核心字段如下：
javascript
{
"success": true,
"result": {
"productId": 619899292404,
"subject": "夏季新款纯棉T恤男款宽松短袖",
"imageUrl": "https://cbu01.alicdn.com/img/ibank/...jpg",
"priceRanges": [
{
"startQuantity": 1,
"price": "28.00",
"currency": "CNY"
},
{
"startQuantity": 100,
"price": "22.50",
"currency": "CNY"
}
],
"skuInfo": {
"skuItems": [
{
"skuId": "123456",
"attributes": [
{"attributeName": "颜色", "attributeValue": "白色"},
{"attributeName": "尺码", "attributeValue": "XL"}
],
"price": "28.00",
"amountOnSale": 500
}
]
},
"saleInfo": {
"unit": "件",
"minOrderQuantity": 1,
"batchNumber": 1
},
"shippingInfo": {
"deliveryFee": {
"originalCost": "0.00",
"type": "FREE"
},
"sendGoodsAddress": "浙江省杭州市"
},
"supplier": {
"loginId": "xxx.1688.com",
"companyName": "杭州xxx服饰有限公司",
"isGoldSupplier": true,
"yearsAsSupplier": 5
}
}
}4.1 关键字段说明
| 字段路径 | 类型 | 说明 |
|---|---|---|
result.subject |
String | 商品标题 |
result.priceRanges |
Array | 批发价格梯度（按起订量） |
result.skuInfo |
Object | SKU 规格与库存信息 |
result.saleInfo.minOrderQuantity |
Integer | 最小起订量（MOQ） |
result.supplier |
Object | 供应商资质信息 |
result.shippingInfo |
Object | 物流与运费模板 |
五、Python 调用实战示例
python
import requests
import time
import hashlib
import urllib.parse
class AlibabaAPI:
def __init__(self, app_key, app_secret, access_token):
self.app_key = app_key
self.app_secret = app_secret
self.access_token = access_token
self.gateway = "https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get"
def get_product_detail(self, product_id, fields=None):
params = {
'app_key': self.app_key,
'method': 'com.alibaba.product.alibaba.product.get',
'timestamp': time.strftime('%Y-%m-%d %H:%M:%S'),
'v': '2.0',
'format': 'json',
'access_token': self.access_token,
'productId': product_id
}
if fields:
params['fields'] = fields
# 生成签名
params['sign'] = self._generate_sign(params)
# 发送 POST 请求
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
response = requests.post(self.gateway, data=params, headers=headers)
if response.status_code == 200:
data = response.json()
if data.get('success'):
return data['result']
else:
raise Exception(f"API Error: {data.get('errorMessage')}")
else:
raise Exception(f"HTTP Error: {response.status_code}")
def _generate_sign(self, params):
sorted_params = sorted((k, v) for k, v in params.items() if k != 'sign')
sign_str = self.app_secret + ''.join(f"{k}{v}" for k, v in sorted_params) + self.app_secret
return hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
# 使用示例
api = AlibabaAPI(
app_key="your_app_key",
app_secret="your_app_secret",
access_token="your_access_token"
)
# 获取商品详情（指定字段）
product = api.get_product_detail(
product_id=610947572360,
fields="subject,priceRanges,skuInfo,saleInfo,shippingInfo"
)
print(f"商品标题: {product['subject']}")
print(f"价格梯度: {product['priceRanges']}")六、调用限制与最佳实践
6.1 平台限制
| 限制项 | 说明 |
|---|---|
| 调用频率 | 默认 QPS 限制，详情查询建议控制在每秒 1 次以内 |
| 日调用上限 | 不超过应用授权配额（基础版通常 1000 次/日） |
| 数据用途 | 仅用于合法商业采购和分析，不得用于恶意竞争 |
6.2 最佳实践建议
-
缓存机制：对频繁访问的商品信息实现本地缓存，减少重复调用。
-
字段裁剪 ：通过
fields参数只请求必要字段，降低响应体积和解析成本。 -
错误重试：实现指数退避重试机制，处理网络抖动或限流场景。
-
异步处理 ：批量查询时使用异步 IO（如
aiohttp）提升效率。 -
日志监控：记录 API 调用日志，便于排查问题和用量监控。
七、常见问题
Q1: 个人开发者能否接入寻源通接口？
不能。1688 寻源通 API 主要面向企业开发者，需提交营业执照完成企业实名认证。
Q2: 如何获取商品的跨境属性（如英文标题、跨境价格）？
需申请跨境专属接口权限，部分字段需通过
alibaba.cross.product.get等跨境接口获取 。
Q3: 接口返回 "Invalid signature" 错误如何处理？
检查签名算法是否正确：参数需按 ASCII 升序排序，值为空字符串的参数也需参与签名，MD5 结果需转大写。
八、总结
1688 跨境寻源通详情接口是连接跨境电商与 1688 供应链的核心数据通道。通过标准化 OAuth2.0 认证、MD5 签名机制和结构化数据返回，开发者可高效获取商品的批发价格、SKU 库存、供应商资质等关键信息。在实际接入中，建议严格遵循平台的调用频率限制，结合缓存与异步策略，确保系统稳定高效运行。