淘寶/天貓商品詳情API返回值詳解（含代碼示例）
一、API接口概述
淘寶開放平臺(tái)/萬邦開放平臺(tái)提供taobao.item.get接口，用于通過商品ID（num_iid）獲取商品的詳細(xì)信息，包括基礎(chǔ)屬性、價(jià)格、庫存、圖文描述、SKU規(guī)格、促銷活動(dòng)等。
二、核心返回值字段解析
字段名說明示例值
num_iid商品唯一ID，用于精準(zhǔn)定位商品"123456789"
title商品標(biāo)題，含關(guān)鍵詞，影響搜索和識(shí)別"2025新款智能手表旗艦版"
price當(dāng)前銷售價(jià)格"1299.00"
original_price原價(jià)（部分接口返回，用于價(jià)格對(duì)比）"1599.00"
pic_url商品主圖URL（高清圖片鏈接）"https://img.alicdn.com/xxx.jpg"
category商品所屬分類"智能設(shè)備"
brand品牌名稱"XX品牌"
description商品詳細(xì)描述（HTML格式，含特點(diǎn)、規(guī)格、材質(zhì)等）"<p>2025年最新款智能手表...</p>"
item_imgs商品圖片列表（含主圖、詳情圖等多角度展示）[{"url":"https://img.alicdn.com/xxx_1.jpg"}]
stock商品總庫存數(shù)量150
sales商品銷量（反映受歡迎程度）350
skusSKU列表（含不同規(guī)格的價(jià)格、庫存及屬性組合）[{"sku_id":"sku_001", "price":"1299.00", "stock":150, "properties":"顏色:黑色;尺寸:標(biāo)準(zhǔn)版"}]
seller_id賣家唯一ID"987654321"
seller_nick賣家昵稱"官方旗艦店"
location發(fā)貨地（影響物流時(shí)效和運(yùn)費(fèi)）"浙江杭州"
post_fee郵費(fèi)（"0.00"表示包郵）"0.00"
promotion當(dāng)前促銷活動(dòng)（如滿減、打折）"滿1000減100"
coupon_info優(yōu)惠券信息（面額及使用條件）{"amount":"100.00", "condition":"滿1000元可用"}
service_list服務(wù)保障（如七天無理由退換）["七天無理由退換"]
rate_info評(píng)價(jià)數(shù)據(jù)（好評(píng)率及總評(píng)價(jià)數(shù)）{"good_rate":"97.6%", "total_count":1250}
detail_url商品詳情頁鏈接（可直接跳轉(zhuǎn)至淘寶頁面）"https://item.taobao.com/item.htm?id=123456789"
json
{
"item_get_response":{
"item":{
"num_iid":"123456789",
"title":"2025新款智能手表旗艦版",
"price":"1299.00",
"original_price":"1599.00",
"pic_url":"https://img.alicdn.com/xxx.jpg",
"category":"智能設(shè)備",
"brand":"XX品牌",
"description":"<p>2025年最新款智能手表，支持心率監(jiān)測...</p>",
"item_imgs":[
{"url":"https://img.alicdn.com/xxx_1.jpg"},
{"url":"https://img.alicdn.com/xxx_2.jpg"}
],
"stock":150,
"sales":350,
"skus":[
{
"sku_id":"sku_001",
"price":"1299.00",
"stock":150,
"properties":"顏色:黑色;尺寸:標(biāo)準(zhǔn)版",
"image":"https://img.alicdn.com/xxx_black.jpg"
}
],
"seller_id":"987654321",
"seller_nick":"官方旗艦店",
"location":"浙江杭州",
"post_fee":"0.00",
"promotion":"滿1000減100",
"coupon_info":{"amount":"100.00","condition":"滿1000元可用"},
"service_list":["七天無理由退換"],
"rate_info":{"good_rate":"97.6%","total_count":1250},
"detail_url":"https://item.taobao.com/item.htm?id=123456789"
}
}
}
四、代碼調(diào)用示例（Python）
python
importrequests
importhashlib
importtime
defget_taobao_item_details(app_key, app_secret, num_iid):
url ="https://eco.taobao.com/router/rest"
timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
params = {
'method':'taobao.item.get',
'app_key': app_key,
'num_iid': num_iid,
'timestamp': timestamp,
'format':'json',
'v':'2.0',
'sign_method':'md5',
'fields':'num_iid,title,price,pic_url,desc,skus,stock,sales'
}
# 生成簽名
sorted_params =sorted(params.items())
query_string =''.join([f"{k}{v}"fork, vinsorted_params])
sign_str = app_secret + query_string + app_secret
params['sign'] = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
# 發(fā)送請(qǐng)求
response = requests.get(url, params=params)
returnresponse.json()
# 示例調(diào)用
app_key ="YOUR_APP_KEY"
app_secret ="YOUR_APP_SECRET"
num_iid ="123456789"
data = get_taobao_item_details(app_key, app_secret, num_iid)
ifdata.get('item_get_response', {}).get('item'):
item = data['item_get_response']['item']
print(f"商品標(biāo)題:{item['title']}")
print(f"當(dāng)前價(jià)格: ￥{item['price']}")
print(f"庫存:{item['stock']}件")
print(f"主圖鏈接:{item['pic_url']}")
else:
print(f"請(qǐng)求失敗:{data.get('error_response', {}).get('msg', '未知錯(cuò)誤')}")
五、調(diào)用注意事項(xiàng)
權(quán)限與認(rèn)證
需在淘寶開放平臺(tái)注冊(cè)賬號(hào)、創(chuàng)建應(yīng)用并獲取AppKey和AppSecret。
部分接口（如taobao.item.detail.get）需額外申請(qǐng)權(quán)限。
簽名生成規(guī)則
按參數(shù)名排序后拼接密鑰，使用MD5加密生成簽名。
頻率限制
免費(fèi)版每日調(diào)用限5000次，超出需付費(fèi)或優(yōu)化邏輯（如緩存數(shù)據(jù)）。
字段篩選
通過fields參數(shù)指定返回字段（如fields=num_iid,title,price），減少數(shù)據(jù)冗余。
錯(cuò)誤處理
檢查status字段（0為成功），非0時(shí)根據(jù)error_code和message排查問題。
六、擴(kuò)展功能場景
多SKU管理
通過skus字段獲取商品規(guī)格（如顏色、尺碼）的價(jià)格和庫存，支持電商系統(tǒng)動(dòng)態(tài)展示。
促銷活動(dòng)監(jiān)控
實(shí)時(shí)解析promotion和coupon_info字段，向用戶推送限時(shí)折扣或滿減優(yōu)惠。
服務(wù)保障透傳
展示service_list中的服務(wù)（如七天無理由退換），提升用戶信任度。
通過以上接口和返回值說明，可高效集成淘寶商品詳情數(shù)據(jù)至業(yè)務(wù)系統(tǒng)，支持商品展示、價(jià)格監(jiān)控、智能選品等場景。
