## 一、接口基础认知
item_get（官方标识：taobao.item.get）是淘宝开放平台提供用于获取单个商品详情数据的核心接口，支持获取淘宝、天猫商品的标题、价格、库存、SKU、图片、销量、卖家信息等20多个维度的结构化数据。
**接口核心属性：**
| 项目 | 详情 |
|------|------|
| 接口名称 | taobao.item_get |
| 请求方式 | HTTPS GET/POST |
| 响应格式 | JSON/XML（默认JSON） |
| 接口版本 | 2.0 |
| 核心能力 | 根据商品ID获取商品标题、价格、SKU、库存、图文、类目、销量、规格属性等全量详情 |
**支持的返回数据类别：**
- **基础信息**：商品ID（num_iid）、标题、主图URL、卖家昵称、店铺ID、商品类目
- **价格信息**：基础售价、优惠价、价格单位、是否支持优惠券
- **库存与规格**：总库存、SKU列表（含SKU ID、规格名称、SKU价格、SKU库存）、规格属性组
- **物流与服务**：发货地、运费模板、是否包邮、售后服务类型
- **详情内容**：商品详情页HTML、卖点描述、包装清单
该接口广泛适用于ERP系统同步、竞品分析、货源选品、跨平台铺货等场景。
## 二、前置准备（必做步骤）
调用接口前，需在淘宝开放平台完成以下配置：
**1. 注册开发者账号**
登录淘宝开放平台，完成企业或个人开发者认证。个人认证可调用基础接口，企业认证支持更多权限。
**2. 创建应用**
进入“开发者中心 - 应用管理”，创建第三方应用，选择应用类型（如“工具型应用”），填写真实的应用名称与用途，避免审核不通过。
**3. 申请接口权限**
在应用详情页的“接口权限”中，搜索并申请 taobao.item_get 接口权限。个人应用通常即时通过，企业应用需1-3个工作日审核。个人开发者基础字段权限审核周期约1-3个工作日。个人账号权限较低，taobao.item.get每天仅100次调用。
**4. 获取密钥**
权限通过后，在“应用设置 - 密钥管理”中获取 **AppKey** 与 **AppSecret**（核心凭证，需妥善保管，避免泄露）。
> 注意：仅调用商品详情接口无需获取SessionKey，只有调用用户相关接口才需通过OAuth2.0授权。
## 三、请求参数说明
调用接口需要传入公共参数和业务参数，参数需严格按类型配置，sign与num_iid为核心必填项。
### 3.1 公共参数（所有调用必传）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| method | String | 固定值：`taobao.item.get` |
| app_key | String | 应用唯一标识，从开放平台控制台获取 |
| timestamp | String | 时间戳，格式 `yyyy-MM-dd HH:mm:ss`（与平台时间偏差≤5分钟） |
| format | String | 响应格式，可选 `json`/`xml`（默认json） |
| v | String | 接口版本，固定为 `2.0` |
| sign_method | String | 签名方法，固定为 `md5` |
| sign | String | MD5签名串，用于验证请求合法性 |
### 3.2 业务参数
| 参数名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| num_iid | String | **是** | 商品数字ID，可从商品详情页URL中提取 |
| fields | String | 否 | 指定返回字段（逗号分隔），如 `title,price,stock`，可减少数据传输量 |
| is_promotion | String | 否 | 是否获取促销信息（0=不获取，1=获取，默认0） |
| session | String | 否 | 用户会话标识（获取隐私数据时需传） |
指定fields参数可有效减少数据传输量，节省调用额度。
## 四、签名生成规则（核心难点）
淘宝开放平台采用MD5签名算法，所有请求需携带签名参数sign，任一环节错误都会返回签名失败错误。签名生成需严格遵循以下步骤：
**步骤一：参数收集** — 将所有请求参数（含公共参数与业务参数）整理为键值对，排除sign参数本身。
**步骤二：参数排序** — 按参数名ASCII码升序排序（如“app_key”在“format”之前，“timestamp”在“v”之前）。
**步骤三：字符串拼接** — 按 `key=value` 格式拼接所有排序后的参数，然后在字符串首尾拼接AppSecret。
**步骤四：MD5加密** — 将拼接后的字符串进行MD5加密（32位大写），结果即为sign参数值。
> **避坑提示**：时间戳格式错误、参数排序颠倒、app_secret泄露是签名失败的三大主因。
## 五、Python 调用示例
以下是一个可直接使用的Python调用示例：
```python
import requests
import hashlib
import time
import json
class TaobaoItemApi:
def __init__(self, app_key, app_secret):
self.app_key = app_key
self.app_secret = app_secret
self.url = "https://eco.taobao.com/router/rest"
def generate_sign(self, params):
"""生成签名"""
# 按参数名ASCII升序排序
sorted_params = sorted(params.items(), key=lambda x: x[0])
# 拼接参数：首尾加app_secret
sign_str = self.app_secret
for key, value in sorted_params:
sign_str += f"{key}{value}"
sign_str += self.app_secret
# MD5加密并转为大写
sign = hashlib.md5(sign_str.encode()).hexdigest().upper()
return sign
def item_get(self, num_iid, fields="title,price,pics,detail_url"):
"""获取商品详情"""
params = {
"app_key": self.app_key,
"method": "taobao.item.get",
"format": "json",
"v": "2.0",
"sign_method": "md5",
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"num_iid": num_iid,
"fields": fields
}
params["sign"] = self.generate_sign(params)
try:
response = requests.get(self.url, params=params, timeout=10)
result = json.loads(response.text)
if "error_response" in result:
error = result["error_response"]
return {"success": False, "error_code": error["code"], "error_msg": error["msg"]}
return {"success": True, "data": result["item_get_response"]["item"]}
except Exception as e:
return {"success": False, "error_msg": str(e)}
# 使用示例
if __name__ == "__main__":
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"
api = TaobaoItemApi(APP_KEY, APP_SECRET)
result = api.item_get("123456")
if result["success"]:
print("商品标题：", result["data"]["title"])
print("商品价格：", result["data"]["price"])
else:
print("获取失败：", result["error_msg"])
```
代码中需要注意：时间戳格式必须为 `yyyy-MM-dd HH:mm:ss`，sign_method 固定为 md5，签名结果需转为大写。
## 六、返回数据核心字段
接口返回的商品详情数据覆盖基础信息、交易信息、规格信息、详情信息四大类：
| 类别 | 核心字段 | 说明 |
|------|----------|------|
| 基础信息 | num_iid | 商品ID |
| | title | 商品标题 |
| | pic_url | 主图链接 |
| | cid | 商品类目 |
| | nick / seller_id | 店铺名称 / 店铺ID |
| 交易信息 | price | 商品标价 |
| | promotion_price | 促销价 |
| | stock / num | 库存数 |
| | sales | 月销量 |
| 规格信息 | props_name | 规格参数 |
| | sku_price / sku_stock | 规格价格 / 规格库存 |
| 详情信息 | desc | 商品详情页富文本 |
| | video_url | 主图视频链接 |
## 七、常见错误码与排查
调用失败时会返回 error_response，包含错误code与message：
| 错误码 | 含义 | 排查方向 |
|--------|------|----------|
| 10001 | API权限不足 | 检查是否已申请item_get接口权限，应用是否审核通过 |
| 10013 / 403 | 签名错误 | 核对AppSecret、参数排序、时间戳格式 |
| 216100 / 404 | 商品ID不存在 | 检查num_iid是否正确 |
| 216110 | 商品已下架 | 该商品已不再销售 |
| 429 | 频率限制 | 降低调用频率，增加缓存策略 |
**常见问题排查要点：**
- **签名失败**：优先检查时间戳格式是否为 `yyyy-MM-dd HH:mm:ss`，参数是否按ASCII升序排列，AppSecret是否配置正确
- **权限不足**：确认在开放平台已提交对应接口的权限申请并通过审核
- **商品ID无效**：从商品详情页URL中提取数字ID，确保num_iid正确
- **时间同步**：确保服务器时间与淘宝API服务器时间同步，偏差不超过5分钟
调试技巧：建议先在沙箱环境进行测试，确认签名生成正确、参数完整后再切换至正式环境。同时可通过开放平台控制台查看接口调用日志进行排查。
## 八、调用频率限制
淘宝商品详情API按账号类型、接口版本分级执行频率限制：
| 账号类型 | 日调用上限 | 分钟级限制 | QPS限制 |
|----------|-----------|-----------|---------|
| 个人开发者（免费） | 100-1000次/天 | 10-30次/分钟 | ≤2次/秒 |
| 企业开发者 | 可提升至10000次/天 | ≤100次/分钟 | — |
高频场景需做好限流和缓存处理，建议对商品详情设置合理缓存（如1小时），减少接口调用次数。
## 九、最佳实践建议
1. **字段优化**：通过fields参数只获取业务需要的字段，减少数据传输量，提升响应速度
2. **缓存策略**：对商品详情设置合理缓存（如1小时），减少重复调用
3. **并发控制**：遵守QPS限制，避免触发限流机制（通常QPS限制为10-100）
4. **错误重试**：网络超时等临时性错误可有限次数重试；权限不足、参数错误等不应重试
5. **批量查询**：如需批量获取商品信息，可使用item_get_batch接口，或对item_get进行合理并发控制
6. **密钥安全**：AppSecret务必妥善保管，避免硬编码在客户端代码中，建议通过服务端调用
