一、前言
淘宝商品详情 API 是获取商品核心信息的核心接口，可返回商品的标题、价格、主图、规格、库存、销量、店铺信息等关键数据。
本指南严格遵循阿里开放平台的接口规范，提供
接口概述、核心参数、Python 请求示例、异常处理 等内容，适用于 Python 开发者集成到电商相关系统中。
二、接口概述
以最常用的
taobao.item.get（获取单个商品详情） 为例，核心信息如下：
2.1 基础信息
| 项目 | 具体内容 |
|---|---|
| 接口名称 | taobao.item.get |
| 接口地址 | 正式环境： http:// c0b.cc/R4rbK2 |
| 请求方式 | POST（推荐）/ GET |
| 数据格式 | 请求：键值对 返回：JSON/XML（推荐 JSON） |
| 权限要求 | 个人开发者需实名认证，企业开发者需企业认证，且需单独申请该接口权限 |
| 核心作用 | 根据商品 ID（num_iid）获取单个商品的完整详情信息 |
2.2 核心请求参数
| 参数名 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| method | 是 | 字符串 | 接口名称，固定为 taobao.item.get |
| app_key | 是 | 字符串 | 阿里开放平台创建应用后分配的 AppKey |
| timestamp | 是 | 字符串 | 时间戳，格式为 YYYY-MM-DD HH:MM:SS（如 2026-01-09 10:30:00） |
| v | 是 | 字符串 | 接口版本，固定为 2.0 |
| sign | 是 | 字符串 | 接口签名（基于 AppSecret 的 MD5 加密，阿里标准算法） |
| sign_method | 是 | 字符串 | 签名方法，固定为 md5 |
| num_iid | 是 | 字符串 | 商品 ID（淘宝商品详情页 URL 中id=后的数字，如1234567890） |
| fields | 是 | 字符串 | 需要返回的字段列表，多个字段用逗号分隔。推荐字段：num_iid,title,price,pic_url,item_imgs,stock,sales,shop_name,detail_url |
2.3 典型返回字段（JSON）
json
{ "item_get_response": { "request_id": "123456", "item": { "num_iid": "1234567890", // 商品ID "title": "Python编程从入门到精通 正版图书", // 商品标题 "price": "89.90", // 商品价格（元） "pic_url": "https://img.alicdn.com/xxx.jpg", // 商品主图 "item_imgs": { // 商品轮播图 "item_img": [ {"url": "https://img.alicdn.com/xxx1.jpg"}, {"url": "https://img.alicdn.com/xxx2.jpg"} ] }, "stock": 1000, // 商品库存 "sales": 5000, // 商品销量 "shop_name": "XX图书专营店", // 店铺名称 "detail_url": "https://item.taobao.com/item.htm?id=1234567890" // 商品详情页URL } } }
2.4 常见响应码
| 响应码 | 说明 | 解决方案 |
|---|---|---|
| 200 | 调用成功 | 正常解析返回数据 |
| 401 | 权限不足 | 检查是否已申请该接口权限，应用是否审核通过 |
| 403 | 签名错误 | 核对 AppSecret、参数排序、时间戳格式 |
| 404 | 商品不存在 | 检查商品 ID（num_iid）是否正确 |
| 500 | 服务器内部错误 | 稍后重试，或提交工单给阿里开放平台 |
三、Python 请求示例
本示例提供 完整的签名生成、接口调用、异常处理、数据解析 逻辑，适用于生产环境，遵循最佳实践。
3.1 环境准备
安装必要依赖：
bash
pip install requests python-dotenv
3.2 完整代码实现
# coding:utf-8"""Compatible for python2.x and python3.xrequirement: pip install requests"""from __future__ import print_functionimport requests# 请求示例 url 默认请求参数已经做URL编码url = "taobao/item_get/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=652874751412&is_promotion=1"headers = {
"Accept-Encoding": "gzip",
"Connection": "close"}if __name__ == "__main__":
r = requests.get(url, headers=headers)
json_obj = r.json()
print(json_obj)代码亮点
-
敏感配置分离：使用
python-dotenv加载.env文件，避免硬编码AppKey和AppSecret，提升代码安全性； - 完整的异常处理：覆盖超时、连接错误、HTTP 状态码错误、接口返回错误等常见场景，避免程序崩溃；
- 严格的签名算法：严格遵循阿里开放平台的签名规则，确保接口调用成功；
- 灵活的字段配置：支持自定义返回字段，可根据业务需求扩展；
- 清晰的字段解析：提取核心商品字段，并支持解析 SKU 规格列表，直接满足代购系统的需求。