当前位置：首页 > news >正文

速卖通 item_get 接口对接全攻略：从入门到精通

news 2025/10/8 11:36:30

速卖通（AliExpress）开放平台的item_get接口是获取商品详情的核心工具，适用于跨境电商分析、多平台比价、选品系统等场景。本文将全面讲解该接口的对接流程、认证机制、代码实现及最佳实践，帮助开发者系统掌握从入门到精通的全流程。

一、接口基础认知

核心功能item_get接口通过商品 ID 获取速卖通平台的商品详细信息，涵盖：
- 基本信息：商品 ID、标题、描述、主图及图片列表
- 价格信息：原价、售价、折扣、货币单位（支持多币种）
- 库存信息：总库存、规格库存、预售状态
- 交易信息：30 天销量、评分、评论数
- 规格信息：颜色、尺寸等多规格组合及对应价格 / 库存
- 物流信息：运费模板、发货地、配送范围
接口端点速卖通接口地址为统一入口，通过参数指定区域：
请求方式：HTTP POST
数据格式：请求与响应均为 JSON 格式
认证方式：采用app_key+access_token+ 签名认证

二、对接前置准备

开发者账号注册访问速卖通开放平台注册账号，完成企业认证（个人账号权限有限）。
创建应用与获取密钥
- 在开放平台控制台创建应用，选择应用类型（如 "平台型" 或 "工具型"）
- 应用创建后，获取app_key和app_secret（密钥需严格保密）
- 完成授权流程，获取access_token（有效期通常为 3600 秒）
权限申请
- item_get接口属于基础商品接口，需在开放平台申请开通
- 不同权限等级获取的字段范围不同，商业应用需申请高级权限
环境准备
- 开发语言：支持 Python/Java/PHP 等任意可发起 HTTP 请求的语言
- 测试工具：Postman 或速卖通开放平台调试工具
- 依赖库：Python 需安装requests库（pip install requests）

三、接口调用流程

参数组装接口参数分为「公共参数」和「业务参数」：
- 公共参数：app_key、access_token、timestamp（毫秒级时间戳）、sign（签名）、format（返回格式）、v（版本）
- 业务参数：productId（商品 ID，必填）、fields（需要返回的字段列表）
示例参数结构：
json
```
{"app_key": "your_app_key","access_token": "your_access_token","timestamp": 1620000000000,"sign": "签名值","format": "json","v": "1.0","productId": "1234567890","fields": "productId,title,price,stock,imageUrl"
}
```
签名生成速卖通签名生成步骤：
1. 收集所有参数（除sign外），按参数名 ASCII 码升序排序
2. 拼接为key=value&key=value格式的字符串
3. 尾部追加&app_secret=your_app_secret
4. 对拼接字符串进行 MD5 加密（32 位大写），结果即为sign
发送请求将参数以 JSON 格式放入请求体，发送 POST 请求到接口地址，设置Content-Type: application/json。
响应处理成功响应包含item_get_response字段（商品详情），错误响应包含error_response字段（错误码和描述）。

四、代码实现示例（Python）

以下是调用速卖通item_get接口的完整代码，包含签名生成、令牌管理和错误处理：

import requests
import hashlib
import time
import json
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
class AliexpressItemApi:def __init__(self, app_key, app_secret, access_token=None):self.app_key = app_keyself.app_secret = app_secretself.access_token = access_tokenself.url = "https://gw.api.alibaba.com/openapi/param2/2/portals.open/api.item.get"self.token_expire_time = 0  # 令牌过期时间（时间戳，秒）def generate_sign(self, params):"""生成签名"""# 1. 按参数名ASCII升序排序sorted_params = sorted(params.items(), key=lambda x: x[0])# 2. 拼接为key=value&key=value格式sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])# 3. 追加app_secretsign_str += f"&app_secret={self.app_secret}"# 4. MD5加密（32位大写）sign = hashlib.md5(sign_str.encode()).hexdigest().upper()return signdef refresh_access_token(self):"""刷新access_token（需根据实际授权方式实现）"""# 实际应用中需根据速卖通授权流程实现令牌刷新# 此处为示例，实际需替换为真实刷新逻辑token_url = "https://gw.api.alibaba.com/openapi/http/1/system.oauth2/getToken"params = {"grant_type": "refresh_token","client_id": self.app_key,"client_secret": self.app_secret,"refresh_token": "your_refresh_token"}response = requests.post(token_url, data=params)result = response.json()if "error" in result:raise Exception(f"令牌刷新失败: {result['error_description']}")self.access_token = result["access_token"]self.token_expire_time = time.time() + int(result["expires_in"])return self.access_tokendef item_get(self, product_id, fields="productId,title,price,stock,imageUrl"):"""获取商品详情:param product_id: 商品ID:param fields: 需要返回的字段，多个用逗号分隔:return: 商品详情数据"""# 检查并刷新令牌if not self.access_token or time.time() > self.token_expire_time - 60:self.refresh_access_token()# 1. 组装参数params = {"app_key": self.app_key,"access_token": self.access_token,"timestamp": int(time.time() * 1000),  # 毫秒级时间戳"format": "json","v": "1.0","productId": product_id,"fields": fields}# 2. 生成签名params["sign"] = self.generate_sign(params)try:# 3. 发送POST请求response = requests.post(url=self.url,json=params,headers={"Content-Type": "application/json"},timeout=15)response.raise_for_status()result = response.json()# 4. 处理响应if "error_response" in result:error = result["error_response"]return {"success": False,"error_code": error.get("code"),"error_msg": error.get("msg")}return {"success": True,"data": result.get("item_get_response", {}).get("item", {})}except Exception as e:return {"success": False,"error_msg": f"请求异常: {str(e)}"}
# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
# 使用示例
if __name__ == "__main__":# 替换为实际参数APP_KEY = "your_app_key"APP_SECRET = "your_app_secret"ACCESS_TOKEN = "your_access_token"# 初始化API客户端api = AliexpressItemApi(APP_KEY, APP_SECRET, ACCESS_TOKEN)# 调用接口，获取商品详情result = api.item_get(product_id="1234567890",fields="productId,title,price,originalPrice,stock,imageUrl,saleCount,storeName")if result["success"]:item = result["data"]print(f"商品ID: {item.get('productId')}")print(f"商品标题: {item.get('title')}")print(f"售价: {item.get('price')} {item.get('currency')}")print(f"原价: {item.get('originalPrice')} {item.get('currency')}")print(f"库存: {item.get('stock')}")print(f"30天销量: {item.get('saleCount')}")print(f"店铺名称: {item.get('storeName')}")print(f"主图地址: {item.get('imageUrl')}")else:print(f"获取失败: {result['error_msg']} (错误码: {result.get('error_code')})")

五、参数与返回字段详解

核心参数说明
- productId：商品唯一标识，可从速卖通商品详情页 URL 提取（如https://www.aliexpress.com/item/1234567890.html中，productId=1234567890）
- fields：指定返回字段，常用字段包括：
  - 基础信息：productId、title（标题）、imageUrl（主图）、description（描述）
  - 价格信息：price（售价）、originalPrice（原价）、currency（货币单位）
  - 库存信息：stock（总库存）、skuStock（规格库存）
  - 交易信息：saleCount（30 天销量）、evaluationScore（评分）
  - 店铺信息：storeId、storeName（店铺名称）

多规格商品处理多规格商品的详细信息在skus字段中：

json

"skus": [{"skuId": "123","attributes": "颜色:红色;尺寸:M","price": "19.99","stock": 100}
]

货币单位说明速卖通支持多币种，currency字段返回货币代码（如USD、EUR、GBP等），可根据需求转换为目标货币。

六、错误处理与调试

常见错误码解析
- 1001：签名错误 → 检查签名生成逻辑、参数排序
- 1002：app_key无效 → 确认应用是否已激活
- 110：access_token无效 → 重新获取或刷新令牌
- 2001：商品不存在 → 检查productId是否正确
- 403：权限不足 → 申请对应接口权限
调试技巧
- 使用速卖通开放平台的API测试工具验证请求
- 检查timestamp是否为当前时间（误差需≤5 分钟）
- 确保fields参数中不包含未申请权限的字段

七、最佳实践与注意事项

跨境适配策略
- 处理多语言标题（速卖通商品通常包含多语言描述）
- 实现货币转换（结合实时汇率接口转换为本地货币）
- 考虑国际物流因素（提取运费、配送时间等信息）
性能优化
- 按需指定fields参数，减少数据传输量
- 实现本地缓存（建议缓存时间 10-30 分钟）
- 批量获取商品详情时，采用并发控制并遵守 QPS 限制（通常为 10）
合规使用
- 遵守《速卖通开放平台服务协议》，不得用于爬虫或数据倒卖
- 展示商品数据时需明确标注来源为速卖通
- 尊重知识产权，未经授权不得使用商品图片和描述
稳定性保障
- 实现令牌自动刷新机制，避免令牌过期
- 设计超时重试策略（最多 3 次，间隔 1-3 秒）
- 监控接口调用成功率，异常时触发告警