一、前言
在跨境电商领域，速卖通（AliExpress）作为阿里巴巴旗下的全球交易平台，积累了海量商品数据。通过商品详情 API，可以实时获取商品标题、价格、库存、评价等核心信息，为价格监控、竞品分析、库存管理等场景提供数据支撑。本文将结合 2026 年最新 API 规范，详细讲解接入流程并提供完整代码示例。
二、准备工作：获取 API 权限
2.1 注册开发者账号
- 访问 速卖通开放平台，完成企业或个人开发者认证
- 企业账号权限更全，建议优先注册企业账号
2.2 创建应用并获取密钥
在开发者后台创建应用，选择「商品详情」API 权限。审核通过后，将获得以下核心凭证：
| 凭证 | 说明 |
|---|---|
App Key | 应用标识 |
App Secret | 应用密钥，用于签名 |
Access Token | 访问令牌，有效期 1 年 |
2.3 配置服务器 IP 白名单
务必配置服务器 IP 白名单，未配置将返回 403 错误。
2.4 接口文档准备
关注最新版《速卖通 API 文档》，重点关注 aliexpress.item.get 接口的参数定义和返回字段说明。
三、核心接口参数说明
| 接口方法名 | 功能 | 核心参数 | 备注 |
|---|---|---|---|
aliexpress.solution.product.detail.get | 商品详情 | product_id、language、currency | 返回标题、价格、库存、图片、描述等 |
aliexpress.item.get | 商品详情（新版） | item_id、language | 支持多语言、SKU、物流等 |
aliexpress.item.search | 商品搜索 | keywords、page_no、page_size | 支持 SALE_DESC/PRICE_ASC/PRICE_DESC 排序 |
aliexpress.solution.product.inventory.get | 库存查询 | product_id、sku_id | 支持单个/批量商品库存 |
aliexpress.solution.product.price.get | 价格查询 | product_id、sku_id | 返回原价、折扣价、币种等 |
四、Python 代码实战
4.1 方式一：使用第三方封装库（推荐）
from aliexpress_api import AliexpressApi
# 初始化 API 客户端
api = AliexpressApi(
app_key="你的App Key",
app_secret="你的App Secret",
access_token="你的Access Token",
language="en_US"
)
def get_product_detail(product_id: str) -> dict:
"""
查询速卖通商品详情
:param product_id: 速卖通商品ID（数字串，如1005005808863025）
:return: 商品详情字典
"""
try:
response = api.execute(
method="aliexpress.solution.product.detail.get",
params={
"product_id": product_id,
"language": "en",
"currency": "USD"
}
)
return response
except Exception as e:
print(f"查询商品详情失败：{e}")
return {}
# 测试调用
if __name__ == "__main__":
test_product_id = "1005005808863025"
detail = get_product_detail(test_product_id)
if detail and detail.get("code") == 200:
product_info = detail.get("data", {})
print("商品标题：", product_info.get("product_title"))
print("商品价格：", product_info.get("sale_price"))
print("商品主图：", product_info.get("main_image_url"))
print("库存数量：", product_info.get("stock_quantity"))
print("商品描述：", product_info.get("product_description"))
else:
print("获取商品详情失败，响应：", detail)
4.2 方式二：原生 HTTP 请求实现（无第三方库）
import time
import hashlib
import requests
from urllib.parse import urlencode, quote_plus
def generate_sign(params: dict, app_secret: str) -> str:
"""
生成速卖通API签名（MD5）
:param params: 请求参数（不含sign）
:param app_secret: 应用Secret
:return: 签名字符串
"""
# 1. 参数按ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 2. 拼接为key=value格式，无分隔符
sign_str = app_secret
for k, v in sorted_params:
if v is not None and v != "":
sign_str += f"{k}{v}"
sign_str += app_secret
# 3. MD5加密并转大写
sign = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
return sign
def ali_api_request(method: str, params: dict, app_key: str, app_secret: str, access_token: str, gateway: str) -> dict:
"""
原生发送速卖通API请求
:param method: 接口方法名
:param params: 业务参数
:param app_key: App Key
:param app_secret: App Secret
:param access_token: access_token
:param gateway: API网关地址
:return: 接口响应
"""
# 1. 构造公共参数
common_params = {
"app_key": app_key,
"method": method,
"format": "json",
"v": "2.0",
"timestamp": str(int(time.time() * 1000)), # 毫秒级时间戳
"sign_method": "md5",
"access_token": access_token
}
# 2. 合并公共参数和业务参数
all_params = {**common_params, **params}
# 3. 生成签名
all_params["sign"] = generate_sign(all_params, app_secret)
# 4. 发送GET请求
try:
response = requests.get(
url=gateway,
params=all_params,
timeout=15
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"请求失败：{e}")
return {}
# 测试原生调用（商品详情）
if __name__ == "__main__":
APP_KEY = "你的App Key"
APP_SECRET = "你的App Secret"
ACCESS_TOKEN = "你的access_token"
GATEWAY = "https://api-sg.aliexpress.com/sync" # 新加坡节点，国内可用
result = ali_api_request(
method="aliexpress.solution.product.detail.get",
params={
"product_id": "1005005808863025",
"language": "en",
"currency": "USD"
},
app_key=APP_KEY,
app_secret=APP_SECRET,
access_token=ACCESS_TOKEN,
gateway=GATEWAY
)
print("原生请求响应：", result)
五、进阶实战：跨境商品全维度解析
以下代码支持 完整结构化数据，完美适配跨境电商选品、多站点数据采集、价格监控等真实业务场景。
import requests
import time
import hashlib
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
# 自行替换开放平台密钥
APP_KEY = "你的APP_KEY"
APP_SECRET = "你的APP_SECRET"
ACCESS_TOKEN = "你的ACCESS_TOKEN"
API_URL = "https://api-sg.aliexpress.com/sync" # 新加坡节点，国内可用
class AliExpressItemDetailApi:
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.session = self._build_session()
self.last_request_time = 0 # 频率控制
def _build_session(self):
# 自动重试机制，提升接口稳定性
retry = Retry(total=3, backoff_factor=0.5, status_forcelist=[429, 500, 503])
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
return session
def _make_sign(self, params):
# 速卖通官方签名规则（网上90%写错）
sorted_items = sorted(params.items(), key=lambda x: x[0])
plain = self.app_secret
for k, v in sorted_items:
if v:
plain += f"{k}{v}"
plain += self.app_secret
return hashlib.md5(plain.encode('utf-8')).hexdigest().upper()
def get_item_detail(self, item_id, language="en"):
# 频率控制：免费版QPS=2，间隔至少0.5秒
current_time = time.time()
if current_time - self.last_request_time < 0.5:
time.sleep(0.5)
self.last_request_time = current_time
timestamp = str(int(time.time()))
# 组装请求参数
params = {
"method": "aliexpress.item.get",
"app_key": self.app_key,
"access_token": self.access_token,
"timestamp": timestamp,
"format": "json",
"v": "2.0",
"item_id": item_id,
"language": language,
# 全字段获取，覆盖跨境电商核心需求
"fields": "title,price,original_price,image_url,sku_property_list,logistics_info,seller_info,evaluation_info,promotion_info"
}
# 生成签名
params["sign"] = self._make_sign(params)
try:
resp = self.session.get(API_URL, params=params, timeout=15)
result = resp.json()
# 错误判断
if result.get("code") != 0:
return {"success": False, "msg": result.get("msg", "接口异常")}
# 核心数据解析与清洗
data = result.get("result", {})
cleaned_data = {
"商品ID": data.get("item_id"),
"多语言标题": data.get("title"),
"售价": data.get("price"),
"原价": data.get("original_price"),
"主图链接": data.get("image_url"),
"SKU规格": data.get("sku_property_list", []),
"物流信息": data.get("logistics_info", {}),
"卖家信息": data.get("seller_info", {}),
"评价统计": data.get("evaluation_info", {}),
"促销信息": data.get("promotion_info", {}),
"商品链接": f"https://www.aliexpress.com/item/{item_id}.html"
}
return {"success": True, "data": cleaned_data}
except Exception as e:
return {"success": False, "msg": f"请求异常：{str(e)}"}
# 调用示例
if __name__ == "__main__":
api = AliExpressItemDetailApi(APP_KEY, APP_SECRET, ACCESS_TOKEN)
# 替换为真实商品ID
res = api.get_item_detail("1005005586923234", language="en")
if res["success"]:
print("✅ 商品详情获取成功")
print(f"商品标题：{res['data']['多语言标题']}")
print(f"售价：{res['data']['售价']}")
print(f"物流信息：{res['data']['物流信息']}")
else:
print(f"❌ {res['msg']}")
六、关键字段解析
API 返回的 JSON 数据包含以下核心字段：
| 字段 | 说明 |
|---|---|
item.title | 商品标题 |
item.price | 当前售价（支持多货币，如 USD） |
item.sale_count | 销量（格式如 1000+） |
item.rating_count | 评价数量 |
item.pic_url | 主图 URL |
item.detail_url | 商品详情页链接 |
sku_infos | SKU 规格组合、库存、价格映射 |
logistics_info | 物流方式、运费、发货时间 |
seller_info | 卖家信息、店铺评分 |
promotion_info | 促销标签、优惠券信息 |
七、注意事项
7.1 频率限制
免费版 API 默认 QPS 限制为 2 次/秒，建议添加 time.sleep() 进行流控。
7.2 签名错误排查
若返回 Invalid sign 错误，需检查：
- 参数是否按字典序排序
- App Secret 是否正确
- 时间戳是否与服务器时间同步
7.3 常见错误码
| 错误码 | 含义 | 解决方案 |
|---|---|---|
403 Forbidden | API 权限不足 | 检查 IP 白名单和接口权限 |
429 Too Many Requests | 触发频率限制 | 降低请求频率，添加流控 |
500 Internal Server Error | 平台临时故障 | 稍后重试 |
7.4 数据缓存
对高频访问的商品 ID，可本地缓存结果（如 Redis），减少 API 调用次数。
八、进阶优化
8.1 请求重试
使用 tenacity 库实现失败重试：
from tenacity import retry, stop_after_attempt, wait_fixed
@retry(stop=stop_after_attempt(3), wait=wait_fixed(2))
def get_product_detail_with_retry(product_id: str):
return get_product_detail(product_id)
8.2 Token 自动刷新
对接 OAuth2.0 刷新 Token 接口，实现 Token 过期自动续期：
def refresh_access_token(refresh_token: str, app_key: str, app_secret: str) -> dict:
url = "https://api.aliexpress.com/system/oauth2/token"
params = {
"grant_type": "refresh_token",
"client_id": app_key,
"client_secret": app_secret,
"refresh_token": refresh_token
}
response = requests.post(url, params=params)
return response.json()
九、无 API 权限的替代方案
若无法申请速卖通开放平台权限，可考虑：
- 速卖通联盟 API：面向联盟推广者的 API，可获取商品基础信息（需注册联盟账号）
- 合规第三方服务商：如店小秘、芒果店长等，提供封装好的速卖通数据接口
- 网页爬虫（谨慎）：仅用于个人学习，需遵守 robots.txt 和速卖通用户协议
十、总结
速卖通 API 接入的核心是 凭证管理 + 签名生成 + 参数合规。优先使用第三方封装库可大幅降低开发成本；生产环境需重点关注签名正确性、调用限流、Token 续期等问题。建议先在开放平台沙箱环境完成接口测试，再上线生产环境。
如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。
