摘要：本文将详细介绍如何调用1688开放平台提供的API接口，通过商品ID精确获取商品的详细信息。内容包括接口概述、请求方式、参数说明、返回数据结构解析以及调用示例。
1. 接口概述
1688开放平台提供了 获取商品详情 接口，允许开发者通过传入商品ID来查询该商品的详细信息。该接口返回的数据结构包含了商品的基础属性、价格、库存、图片、规格等关键信息。
2. 请求方式
接口名称：获取商品详情
请求方法：HTTP POST
请求地址：https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get
数据格式：application/x-www-form-urlencoded
3. 请求参数
调用该接口需要传递以下关键参数：
access_token：String 类型。调用API的身份授权令牌，需通过1688开放平台的OAuth2.0授权流程获取。必须。
productId：Long 类型。目标商品的唯一ID。必须。
fields (可选)：String 类型。用于指定需要返回的字段列表，多个字段用英文逗号分隔。若不指定，默认返回所有字段。
示例：fields=subject,priceRanges,imageUrl,skuInfo
4. 返回数据结构解析
接口成功调用后，会返回一个结构化的JSON数据。核心字段包括：
{
"result": {
"productId": 123456789012345, // 商品ID
"subject": "商品标题", // 商品标题
"priceRanges": [ // 价格区间
{
"startQuantity": 1, // 起批量
"price": 99.99 // 价格
},
// ... 其他价格区间
],
"imageUrl": "https://example.com/image.jpg", // 主图URL
"detailPage": "https://detail.1688.com/offer/123456789012345.html", // 详情页URL
"skuInfo": { // SKU信息
"skuMap": { // SKU属性映射
"颜色;尺寸": {
"skuId": "sku123", // SKU ID
"specId": "spec123", // 规格ID
"price": 99.99, // SKU价格
"stock": 100 // SKU库存
}
// ... 其他SKU组合
},
"specs": [ // 规格定义
{
"specId": "spec123", // 规格ID
"name": "颜色", // 规格名称
"values": [ // 规格值
{
"valueId": "value1",
"name": "红色"
},
{
"valueId": "value2",
"name": "蓝色"
}
]
},
// ... 其他规格
]
},
"status": "published", // 商品状态 (published, deleted等)
// ... 其他字段 (如物流信息、服务承诺、描述信息等)
},
"success": true, // 请求是否成功
"errorCode": "0", // 错误码 (0表示成功)
"errorMsg": null // 错误信息
}
5. 调用示例 (Python)
import requests
# 你的AppKey、AppSecret、AccessToken (实际应用中需安全存储)
app_key = 'YOUR_APP_KEY'
app_secret = 'YOUR_APP_SECRET'
access_token = 'YOUR_ACCESS_TOKEN'
# 目标商品ID
product_id = 123456789012345 # 替换为实际商品ID
# API请求地址
url = 'https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.get'
# 构建请求参数
params = {
'access_token': access_token,
'productId': product_id,
# 'fields': 'subject,priceRanges,imageUrl,skuInfo' # 可选，按需指定字段
}
# 发送POST请求
response = requests.post(url, data=params)
# 处理响应
if response.status_code == 200:
data = response.json()
if data.get('success'):
product_info = data['result']
print("商品标题:", product_info['subject'])
print("主图URL:", product_info['imageUrl'])
# 解析价格区间、SKU等信息...
else:
print("API调用失败:", data.get('errorMsg', '未知错误'))
else:
print("HTTP请求失败，状态码:", response.status_code)
注意事项：
确保 access_token 有效且具有足够的权限。
productId 必须是有效的1688商品ID (长整型)。
根据业务需求合理使用 fields 参数，避免请求过多不必要的数据。
注意接口调用频率限制，避免触发流控。
处理可能的错误码 (如 isv.invalid-parameter, isp.permission-denied 等)。
6. 常见问题
Q：如何获取 access_token？ A：需要通过1688开放平台的OAuth2.0授权流程获取。开发者需在开放平台创建应用，引导用户授权后获取授权码(code)，再换取访问令牌(access_token)。
Q：返回的图片URL是完整的吗？ A：通常返回的是图片的相对路径或包含域名的主路径。建议拼接1688的图片域名前缀 (如 https://cbu01.alicdn.com/) 或直接使用返回的完整URL。
Q：如何获取实时库存？ A：此接口返回的库存信息 (stock) 可能不是实时更新的。对于需要实时库存的场景，建议使用 获取单个商品库存 等更专业的库存API。
Q：接口返回为空或错误怎么办？ A：首先检查 errorCode 和 errorMsg。常见原因包括：商品ID无效、商品已删除、access_token 失效或权限不足、调用频率超限等。对照错误码排查问题。
7. 总结
通过 获取商品详情 API，开发者可以高效地根据商品ID获取1688平台上商品的丰富信息。合理利用此接口，可以构建商品展示、比价、库存监控等多种应用场景。调用时需严格遵守接口规范，关注授权、参数有效性及错误处理。
建议：在正式集成前，务必仔细阅读1688开放平台官方文档中关于该接口的最新说明，并利用API测试工具进行调试。
审核编辑 黄宇
