淘宝商品详情API接口指南

一、前言

淘宝商品详情 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.x
requirement: pip install requests
"""
from __future__ import print_function
import 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 规格列表，直接满足代购系统的需求。

审核编辑 黄宇