o0b.cn/JeO6y3
做跨境铺货、竞品监控、自研ERP、选品工具的开发者，90%都踩过速卖通API的坑：选不对接口查不了竞品、签名反复报错、403权限封禁、调用频繁限流、多语言币种适配异常。
本文结合多年实战踩坑经验，彻底区分两套官方商品详情接口，整理从零接入流程、参数规范、签名算法、生产级代码、高频报错解决方案，完全适配竞品数据分析、多语言铺货、跨平台商品迁移、店铺数据同步全业务场景。
一、核心避坑：速卖通两套官方详情接口（90%新手选错）
速卖通开放平台有两套完全独立的商品详情接口，权限、能力、适用场景天差地别，选错直接无法获取竞品数据、接口审核驳回。
- aliexpress.item.get（商家自用接口 ❌ 不推荐铺货/选品）
- 适用主体：速卖通自有店铺卖家
- 核心能力：仅可查询自己店铺的商品详情、库存、价格
- 致命限制：无法查询任何外部竞品、全网公开商品
- 网关地址：https://gw-api.aliexpress.com/router/rest
- 适用场景：自有店铺ERP数据同步、库存价格自研管理
- aliexpress.solution.product.detail.get（联盟分销通用接口 ✅ 首选）
- 适用主体：服务商、开发者、选品工具、铺货团队、跨境ERP
- 核心能力：查询全网所有公开速卖通商品（竞品、第三方爆款均可查）
- 核心优势：原生支持多语言（英/俄/西/法等）、多币种换算，完美适配跨境铺货
- 网关地址：https://api-sg.aliexpress.com/rest（新加坡海外网关，访问更稳定）
- 适用场景：竞品监控、爆款选品、多平台铺货、跨站点商品迁移、价格行情分析
终极结论：只要是做选品、查竞品、对外铺货，一律用 solution 分销接口，不要用商家自用接口！
二、接入前置必备条件（缺一必报错）
速卖通官方API无免费个人权限，个人账号权限极低，无法获取完整商品数据，必须完成以下配置：
- 注册速卖通开放平台账号，完成企业实名认证
- 创建服务商/自用型应用，获取核心凭证：app_key、app_secret
- 通过OAuth2.0授权，获取长期有效 access_token
- 后台手动申请solution.product.detail.get 接口权限，等待1-3个工作日审核
- 配置服务器出口IP白名单，未配置直接返回403禁止访问
- 同步服务器时间至阿里云NTP服务器，时间误差超5分钟会签名失败
三、接口核心入参规范（精准适配铺货/选品）
分为业务私有参数（商品查询核心）和公共必填参数（所有接口通用），缺一不可。 业务私有参数
公共必填参数（高频出错重点）
app_key、timestamp（13位毫秒级时间戳）、sign（MD5签名）、format=json、v=2.0、access_token- 官方签名算法（90%报错根源）
严格遵循以下步骤，错一步直接 Invalid Sign： - 剔除 sign 本身、空值参数，保留所有有效参数
- 将参数名按 ASCII 升序 排序（重点易错点）
- 按 key+value 顺序无缝拼接所有参数
- 首尾包裹 app_secret，生成完整加密字符串
- MD5加密后转为32位大写字符串
签名踩坑总结：必须携带access_token参与签名、时间戳必须13位毫秒、禁止保留空参数、服务器时间必须同步官方时区
四、接口返回核心字段（铺货/选品刚需）
覆盖商品基础信息、价格、SKU、物流、评价、销量等全维度数据，满足所有跨境业务需求：
{
"product_id": "商品唯一ID",
"subject": "多语言商品标题",
"description": "完整详情图文描述",
"main_image_url": "商品主图链接",
"image_urls": "轮播图数组",
"video_url": "商品视频地址",
"price_info": {
"original_price": "原价",
"sale_price": "实时售价",
"currency": "对应币种"
},
"sku_info_list": [
{
"sku_id": "规格ID",
"sku_price": "单规格售价",
"stock": "实时库存",
"attribute": "颜色/尺寸/型号属性"
}
],
"shipping_info": {
"shipping_cost": "基础运费",
"delivery_time": "发货时效",
"ship_from_country": "发货地",
"is_overseas_warehouse": "是否海外仓（选品核心字段）"
},
"evaluation_info": {
"evaluation_count": "评价总数",
"avg_rating": "综合评分",
"positive_rate": "好评率"
},
"sale_count": "累计销量",
"category_id": "类目ID",
"discount_info": "折扣活动信息"
}
五、Python 生产级可直接运行代码（带容错+避坑）
代码已优化签名算法、异常捕获、空参数过滤、时间同步适配，可直接部署使用：
import time
import hashlib
import requests
核心配置（替换为自己的凭证）
APP_KEY = "你的app_key"
APP_SECRET = "你的app_secret"
ACCESS_TOKEN = "你的access_token"
GATEWAY = "https://api-sg.aliexpress.com/rest"
def get_ali_sign(params, secret):
# 过滤空参数、ASCII升序排序
params = {k: v for k, v in params.items() if v is not None and v != ""}
sorted_params = sorted(params.items(), key=lambda x: x[0])
raw_str = secret
for k, v in sorted_params:
raw_str += f"{k}{v}"
raw_str += secret
# MD5大写加密
return hashlib.md5(raw_str.encode("utf-8")).hexdigest().upper()
def get_aliexpress_product(product_id, lang="en", currency="USD"):
# 13位毫秒时间戳（必填避坑）
timestamp = str(int(time.time() * 1000))
params = {
"method": "aliexpress.solution.product.detail.get",
"app_key": APP_KEY,
"timestamp": timestamp,
"format": "json",
"v": "2.0",
"access_token": ACCESS_TOKEN,
"product_id": product_id,
"language": lang,
"currency": currency
}
# 生成签名
params["sign"] = get_ali_sign(params, APP_SECRET)
# 请求接口+异常捕获
try:
resp = requests.post(GATEWAY, data=params, timeout=10)
return resp.json()
except Exception as e:
return {"code": -1, "msg": f"请求异常：{str(e)}"}
调用测试
if name == "main":
res = get_aliexpress_product("目标商品ID", "en", "USD")
print(res)
六、高频报错 & 终极避坑指南（实战汇总）
- Invalid Sign 签名失败（最高频）
- 问题原因：时间戳非13位、参数未排序、空参数未过滤、access_token未参与签名、服务器时间偏差过大
- 解决方案：统一毫秒时间戳、过滤所有空值、排序后再签名、同步阿里云NTP时间
- 403 Forbidden 权限拒绝
- 问题原因：未配置IP白名单、接口权限未审核通过、应用资质过期
- 解决方案：后台添加服务器出口IP、重新提交接口权限审核、核验企业资质
- 1002 Too Many Request 限流
- 问题原因：免费应用QPS限制≤2次/秒，高频并发请求触发封禁
- 解决方案：开启Redis缓存（缓存15-30分钟）、令牌桶限流、指数退避重试
- 商品无数据/返回空内容
- 问题原因：商品下架、私密商品、违规封禁、部分特殊类目不支持查询
- 解决方案：增加商品状态判断，跳过无效商品ID
- 多语言/币种返回异常
- 问题原因：参数大小写错误、网关使用国内地址
- 解决方案：固定使用新加坡海外网关、语言币种参数小写规范传入
七、生产环境优化方案（适配ERP/工具长期运行）
- 缓存优化：商品基础信息缓存15-30分钟，价格库存高频字段短时缓存，大幅降低调用量
- 限流策略：全局QPS限制2次/秒，禁止并发轰炸请求
- 容错重试：限流、网络异常采用指数退避重试，签名错误直接拦截不重试
- 数据清洗：结构化解析SKU属性、自动转存图片至自有图床、统一汇率换算
- 合规保障：拒绝爬虫抓取、禁止批量轮询监控竞品、不二次售卖接口数据
八、接口方案对比（快速选型）
速卖通商品详情API接入的核心关键：选对solution分销接口、严格遵循签名规则、做好限流缓存、合规调用。
摒弃老旧的商家自用接口，本文方案可完美适配竞品选品、多语言铺货、跨平台商品迁移、ERP数据同步所有主流跨境业务，规避99%的接入坑点，直接落地生产环境。
