淘宝商品详情API技术说明文档（taobao.item.get｜含原始 JSON + 落地结构化模型）

原创

wx19970108018

发布于 2026-06-11 11:39:59

1050

文章被收录于专栏：经验经验

一、接口基础

接口名称：taobao.item_get（淘宝 / 天猫通用商品详情查询 API）
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
接口版本：2.0
鉴权方式：AppKey + AppSecret 签名校验（MD5/HMAC-SHA256）
使用前提：淘宝开放平台企业认证、创建应用、申请对应接口权限，个人开发者权限受限。
调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存处理。
核心作用：根据商品 ID，获取商品标题、价格、SKU、库存、图文、类目、销量、规格属性等全量详情数据。

二、请求核心参数

分为公共参数和业务参数，均参与签名计算。

1. 公共参数（必传）

表格

参数名	类型	说明
method	String	固定值：taobao.item.get
app_key	String	应用唯一标识
timestamp	String	时间戳，格式 yyyy-MM-dd HH:mm:ss
format	String	响应格式，推荐 json
v	String	接口版本，固定 2.0
sign	String	加密签名，根据所有参数 + AppSecret 生成

2. 业务参数（核心）

表格

参数名	是否必填	类型	说明
num_iid	是	String	商品 ID，商品详情页 URL 中的 id 值
fields	否	String	指定返回字段，按需精简可提升响应速度；不传默认返回全量字段

三、完整返回 JSON 示例

json

{
    "taobao_item_get_response": {
        "code": 0,
        "msg": "成功",
        "item": {
            "num_iid": "723456789012",
            "title": "夏季纯棉短袖男女宽松百搭休闲上衣",
            "price": "59.90",
            "orginal_price": "99.00",
            "pic_url": "https://img10.360buyimg.com/imagetools/jfs/t1/xxx.jpg",
            "num": 2360,
            "sales": 12580,
            "category_id": "123456",
            "category_name": "女装>短袖T恤",
            "status": "normal",
            "props_name": "颜色:白色;尺码:M",
            "desc": "精选纯棉面料，透气舒适，多种尺码可选",
            "skus": {
                "sku": [
                    {
                        "sku_id": "1122334455",
                        "properties": "白色;M",
                        "price": "59.90",
                        "stock_num": 520
                    },
                    {
                        "sku_id": "1122334456",
                        "properties": "黑色;L",
                        "price": "59.90",
                        "stock_num": 386
                    }
                ]
            },
            "detail_url": "https://item.taobao.com/item.htm?id=723456789012"
        }
    }
}

四、JSON 结构 & 字段简要说明

整体根节点为 taobao_item_get_response，内部分为状态码与商品主体数据：

顶层公共字段
code：状态码，0 代表调用成功，非 0 为异常
msg：状态描述信息

item 商品主体字段 num_iid：商品唯一 ID

title：商品完整标题

price：在售售价

orginal_price：原价 / 划线价

pic_url：商品主图地址
num：总库存数量
sales：累计销量
category_id：类目 ID
category_name：类目名称
status：商品状态，normal = 正常在售，down = 下架，instock = 预售
props_name：商品基础属性
desc：商品简介 / 短描述
detail_url：淘宝商品原生链接

skus 规格集合
- sku_id：单品规格 ID
- properties：规格组合（颜色、尺码等）
- price：该规格单独售价
- stock_num：该规格剩余库存

五、常见错误返回示例

示例 1：AppKey 错误 / 应用未授权

json

{
    "error_response": {
        "code": 15,
        "msg": "应用授权无效",
        "sub_msg": "app_key不存在"
    }
}

示例 2：商品 ID（num_iid）不存在或已删除

json

{
    "error_response": {
        "code": 26,
        "msg": "获取商品数据失败",
        "sub_msg": "该商品不存在或已被删除"
    }
}

示例 3：签名错误（参数排序 / 密钥错误）

json

{
    "error_response": {
        "code": 41,
        "msg": "签名错误",
        "sub_msg": "sign校验不通过，请检查参数与加密规则"
    }
}

示例 4：调用超限 / 频率受限

json

{
    "error_response": {
        "code": 17,
        "msg": "调用频次超限",
        "sub_msg": "接口调用次数已达当日上限"
    }
}

六、技术要点小结

签名规则：所有公共参数 + 业务参数按键名升序排列，拼接后结合 AppSecret 加密，签名错误是最常见问题。
参数优化：业务场景明确时，使用 fields 限定返回字段，减少数据传输、提升接口响应速度。
限流与缓存：接口有配额和频率限制，批量采集场景必须增加请求队列、分时调用、本地缓存，避免触发风控。
数据处理：SKU 为数组结构，开发时需做循环解析；图片链接为阿里 CDN 地址，如需长期使用建议本地化存储。
异常处理：必须捕获各类错误码，针对签名失败、商品不存在、调用超限、网络超时做重试、告警、熔断处理。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

大数据

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

大数据

#淘宝商品详情API

登录后参与评论

0 条评论

热度

淘宝商品详情API技术说明文档（taobao.item.get｜含原始 JSON + 落地结构化模型）

淘宝商品详情API技术说明文档（taobao.item.get｜含原始 JSON + 落地结构化模型）

一、接口基础

二、请求核心参数

1. 公共参数（必传）

2. 业务参数（核心）

三、完整返回 JSON 示例

四、JSON 结构 & 字段简要说明

五、常见错误返回示例

示例 1：AppKey 错误 / 应用未授权

示例 2：商品 ID（num_iid）不存在或已删除

示例 3：签名错误（参数排序 / 密钥错误）

示例 4：调用超限 / 频率受限

六、技术要点小结

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐