淘宝/天猫商品描述API（taobao.item_get_desc）返回值全面解析

一、接口概述

taobao.item_get_desc 是淘宝/天猫开放平台提供的核心商品详情接口之一，主要用于获取商品的详细描述信息。与 taobao.item.get 接口相比，该接口更专注于返回商品详情页的图文描述内容，适用于需要展示商品完整介绍、规格参数、使用说明等场景。

接口特点：

• 专注描述信息：核心返回商品详情页的HTML描述内容

• 图文分离：通常返回HTML文本，图片资源需要额外处理

• 多语言支持：支持通过参数指定返回语言（中文/英文/俄文等）

• 数据缓存：支持缓存机制，提升调用效率

---

二、请求参数详解

公共参数（Public Parameters）

参数名	类型	是否必填	说明
key	String	是	API调用密钥（App Key）
secret	String	是	API调用密钥（App Secret）
api_name	String	是	接口名称，固定为 item_get_desc
cache	String	否	是否使用缓存：yes（默认）/ no
result_type	String	否	返回格式：json（默认）/ jsonu / xml / serialize
lang	String	否	翻译语言：cn（默认中文）/ en / ru
version	String	否	API版本号

请求参数（Request Parameters）

参数名	类型	是否必填	说明
num_iid	String	是	淘宝/天猫商品数字ID

请求示例：

curl -i "https://api-gw.onebound.cn/taobao/item_get_desc/?key=<your_api_key>&secret=<your_api_secret>&num_iid=520813250866"

---

三、返回值结构全景

成功调用后，API返回标准的JSON数据结构，整体分为响应头信息、商品主体数据和错误信息三大部分。

3.1 顶层响应结构

{
    "request_id": "4f8c9d2e1a3b5f6e7d8c9b0a1f2e3d4c",
    "item": {
        "num_iid": "520813250866",
        "title": "2024新款夏季纯棉短袖T恤男女宽松百搭上衣",
        "price": "59.90",
        "desc": "<div class='detail-content'>...</div>",
        "desc_images": [...],
        "detail_url": "https://item.taobao.com/item.htm?id=520813250866",
        "shop_info": {...}
    },
    "error_response": null
}

3.2 核心字段详解

1. 请求追踪字段

字段名	类型	说明
request_id	String	请求唯一标识符，用于问题排查和日志追踪

2. 商品基础信息（item对象）

字段名	类型	示例值	说明
num_iid	Long	520813250866	商品唯一数字ID
title	String	"2024新款夏季纯棉短袖T恤..."	商品完整标题
price	String	"59.90"	商品当前售价（元）
original_price	String	"89.00"	商品原价（如有）
promotion_price	String	"49.90"	促销价（活动期返回）

3. 商品描述核心字段

字段名	类型	说明
desc	String	核心字段，商品详情HTML内容，包含图文混排、规格表、使用说明等
desc_images	Array	描述中包含的图片资源列表（部分版本支持）
detail_url	String	商品详情页原始链接

desc字段内容示例：

<div class="detail-content">
    <div class="detail-item">
        <h3>商品详情</h3>
        <p>精选100%纯棉面料，透气舒适...</p>
        <img src="//img.alicdn.com/imgextra/i1/xxx.jpg" />
    </div>
    <div class="detail-params">
        <table>
            <tr><th>品牌</th><td>XX服饰</td></tr>
            <tr><th>材质</th><td>100%棉</td></tr>
            <tr><th>尺码</th><td>S/M/L/XL/XXL</td></tr>
        </table>
    </div>
</div>

4. 描述图片资源（desc_images）

当接口支持返回结构化图片数据时，格式如下：

"desc_images": [
    {
        "url": "https://img.alicdn.com/imgextra/i1/2688/TB2abc123.jpg",
        "position": 1,
        "width": 750,
        "height": 800
    },
    {
        "url": "https://img.alicdn.com/imgextra/i2/2688/TB2def456.jpg", 
        "position": 2,
        "width": 750,
        "height": 800
    }
]

5. 店铺信息（shop_info）

字段名	类型	说明
shop_id	String	店铺ID
shop_name	String	店铺名称
shop_type	String	店铺类型：taobao（淘宝）/ tmall（天猫）
score	Float	店铺综合评分（如4.8）

---

四、扩展字段与特殊场景

4.1 SKU规格信息（部分版本）

部分API版本会在描述接口中返回SKU基础信息：

"skus": {
    "sku": [
        {
            "sku_id": "123456",
            "properties": "1627207:28341;20509:28314",
            "properties_name": "颜色:白色;尺码:M",
            "price": "59.90",
            "stock": 320,
            "outer_id": "SKU-001"
        }
    ]
}

4.2 促销与活动标签

促销信息可能以两种方式呈现：

1. 结构化字段（部分版本支持）：

   "promotion_price": "49.90",
   "promotion_start_time": "2024-11-01 00:00:00",
   "promotion_end_time": "2024-11-11 23:59:59",
   "promotion_desc": "双11限时特惠"

2. HTML嵌入：在desc字段的HTML中通过特定class标识活动标签

4.3 错误响应结构

当请求失败时，error_response对象包含：

{
    "error_response": {
        "code": 40,
        "msg": "Insufficient isv permissions",
        "sub_code": "isv.permission-ip-whitelist-limit",
        "sub_msg": "IP白名单限制"
    }
}

常见错误码：

错误码	说明	解决方案
40	权限不足	申请相应API权限
7	参数错误	检查num_iid是否有效
15	频率限制	降低调用频率，申请更高QPS
27	无效密钥	检查App Key/Secret

---

五、数据处理与实战应用

5.1 HTML内容处理方案

由于desc字段返回的是HTML格式，需要特殊处理才能在前端安全展示：

5.2 完整调用示例（Python）

Python

复制

import requests
import time
import hashlib

def get_item_desc(app_key, app_secret, num_iid):
    """
    获取淘宝商品描述信息
    """
    url = "https://api-gw.onebound.cn/taobao/item_get_desc/"
    
    # 构造请求参数
    params = {
        'key': app_key,
        'secret': app_secret,
        'num_iid': num_iid,
        'cache': 'yes',
        'result_type': 'json',
        'lang': 'cn'
    }
    
    try:
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        
        data = response.json()
        
        # 检查错误
        if data.get('error_response'):
            error = data['error_response']
            print(f"API错误: {error.get('msg')}")
            return None
            
        item = data.get('item', {})
        
        # 提取核心数据
        result = {
            'item_id': item.get('num_iid'),
            'title': item.get('title'),
            'price': float(item.get('price', 0)),
            'description_html': item.get('desc'),
            'detail_url': item.get('detail_url'),
            'shop_name': item.get('shop_info', {}).get('shop_name'),
            'request_id': data.get('request_id')
        }
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")
        return None

# 使用示例
if __name__ == "__main__":
    item_data = get_item_desc(
        app_key="your_app_key",
        app_secret="your_app_secret", 
        num_iid="520813250866"
    )
    
    if item_data:
        print(f"商品标题: {item_data['title']}")
        print(f"商品价格: ¥{item_data['price']}")
        print(f"描述长度: {len(item_data['description_html'])} 字符")

---

六、注意事项与最佳实践

6.1 合规与权限

1. 官方渠道：确保通过淘宝开放平台或授权服务商接入，避免使用非合规爬虫方案

2. 权限申请：需申请taobao.item.get或商品描述相关API权限

3. IP白名单：在开放平台配置服务器IP白名单

6.2 性能优化

1. 缓存策略：对热门商品启用缓存（cache=yes），减少API调用次数

2. 字段选择：如果仅需描述信息，避免调用全量数据接口

3. 批量处理：如需批量获取，考虑使用taobao.item_get_batch接口

6.3 数据安全

1. 密钥保护：App Secret禁止在客户端代码中暴露

2. 内容过滤：对返回的HTML进行XSS过滤后再展示

3. 图片转存：建议将商品图片转存至自有CDN，避免防盗链失效

6.4 版本差异

• 天猫 vs 淘宝：天猫商品通常返回更规范的规格参数表

• C店 vs B店：企业店铺可能包含更多认证信息字段

• API版本：不同版本返回字段可能存在差异，需以实际返回为准

---

七、总结

taobao.item_get_desc接口是获取淘宝/天猫商品详情描述的核心工具，其返回的HTML格式数据包含了商品最完整的图文介绍信息。开发者在使用时需注意：

1. 核心字段：重点关注desc（HTML描述）、price（价格）、desc_images（图片资源）

2. 数据处理：必须对HTML进行安全过滤和图片链接处理

3. 合规调用：遵守平台规则，合理控制调用频率

4. 错误处理：完善对各类异常情况和错误码的处理机制

通过合理利用该接口，可以构建完整的商品详情展示、比价分析、内容营销等电商应用场景。