淘宝/天猫获得淘宝app商品详情原数据 API 返回值说明

蓝倾
2 阅读4分钟

淘宝/天猫商品详情API返回值详解（含代码示例）

一、API接口概述

淘宝开放平台提供taobao.item.get接口，用于通过商品ID（num_iid）获取商品的详细信息，包括基础属性、价格、库存、图文描述、SKU规格、促销活动等。

二、核心返回值字段解析

字段名说明示例值
num_iid商品唯一ID，用于精准定位商品"123456789"
title商品标题，含关键词，影响搜索和识别"2025新款智能手表旗舰版"
price当前销售价格"1299.00"
original_price原价（部分接口返回，用于价格对比）"1599.00"
pic_url商品主图URL（高清图片链接）"https://img.alicdn.com/xxx.jpg"
category商品所属分类"智能设备"
brand品牌名称"XX品牌"
description商品详细描述（HTML格式，含特点、规格、材质等）"<p>2025年最新款智能手表...</p>"
item_imgs商品图片列表（含主图、详情图等多角度展示）[{"url":"https://img.alicdn.com/xxx_1.jpg"}]
stock商品总库存数量150
sales商品销量（反映受欢迎程度）350
skusSKU列表（含不同规格的价格、库存及属性组合）[{"sku_id":"sku_001", "price":"1299.00", "stock":150, "properties":"颜色:黑色;尺寸:标准版"}]
seller_id卖家唯一ID"987654321"
seller_nick卖家昵称"官方旗舰店"
location发货地（影响物流时效和运费）"浙江杭州"
post_fee邮费（"0.00"表示包邮）"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"

三、返回值结构示例

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": "智能设备",
      "brand": "XX品牌",
      "description": "<p>2025年最新款智能手表，支持心率监测...</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": "颜色:黑色;尺寸:标准版",
          "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"
    }
  }
}

四、代码调用示例（Python）

python
import requests
import hashlib
import time
 
def get_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}" for k, v in sorted_params])
    sign_str = app_secret + query_string + app_secret
    params['sign'] = hashlib.md5(sign_str.encode('utf-8')).hexdigest().upper()
    
    # 发送请求
    response = requests.get(url, params=params)
    return response.json()
 
# 示例调用
app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
num_iid = "123456789"
data = get_taobao_item_details(app_key, app_secret, num_iid)
 
if data.get('item_get_response', {}).get('item'):
    item = data['item_get_response']['item']
    print(f"商品标题: {item['title']}")
    print(f"当前价格: ¥{item['price']}")
    print(f"库存: {item['stock']}件")
    print(f"主图链接: {item['pic_url']}")
else:
    print(f"请求失败: {data.get('error_response', {}).get('msg', '未知错误')}")

五、调用注意事项

  1. 权限与认证

    • 需在淘宝开放平台注册账号、创建应用并获取AppKey和AppSecret。
    • 部分接口（如taobao.item.detail.get）需额外申请权限。

  2. 签名生成规则

    • 按参数名排序后拼接密钥，使用MD5加密生成签名。

  3. 频率限制

    • 免费版每日调用限5000次，超出需付费或优化逻辑（如缓存数据）。

  4. 字段筛选

    • 通过fields参数指定返回字段（如fields=num_iid,title,price），减少数据冗余。

  5. 错误处理

    • 检查status字段（0为成功），非0时根据error_code和message排查问题。

六、扩展功能场景

  • 多SKU管理
    通过skus字段获取商品规格（如颜色、尺码）的价格和库存，支持电商系统动态展示。
  • 促销活动监控
    实时解析promotion和coupon_info字段，向用户推送限时折扣或满减优惠。
  • 服务保障透传
    展示service_list中的服务（如七天无理由退换），提升用户信任度。

通过以上接口和返回值说明，可高效集成淘宝商品详情数据至业务系统，支持商品展示、价格监控、智能选品等场景。

avatar
文章
阅读
粉丝