淘宝天猫商品详情 API 接口解析（附 JSON 样例）

原创

用户1597063760

发布于 2026-09-23 14:10:56

3080

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

摘要

在电商 ERP 开发、竞品监控、货源选品、跨平台铺货等业务中，经常需要获取淘宝、天猫商品完整结构化信息。很多项目初期选择网页爬虫抓取详情页，但会遇到页面 DOM 改版、验证码拦截、IP 风控、HTML 脏数据清洗困难等一系列问题，长期维护成本很高。

淘宝开放平台 TOP 提供taobao.item.get商品详情 API，支持获取淘宝、天猫公开商品的标题、价格、SKU、图集、属性、店铺、销量等标准化 JSON 数据。本文完整解析接口基础信息、请求参数、返回字段，附带正常 / 异常 JSON 样例、调用流程、错误码与生产踩坑经验。

一、接口基础信息

1. 接口基础信息

taobao .item_get（淘宝天猫商品详情 API），输入参数为商品唯一 ID num_iid，返回完整商品详情结构化 JSON 数据。

接口简介

接口名称：taobao.item_get（淘宝商品详情API，taobaoapi2014前往体验）

请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）

接口版本：2.0

调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存处理。

核心作用：根据商品 ID，获取商品标题、价格、SKU、库存、图文、类目、销量、规格属性等全量详情数据。

接口能力覆盖

商品基础元数据：标题、售价、划线价、销量、库存、发货地

多媒体资源：主图、轮播图、HTML 详情描述

SKU 规格集合：多规格价格、库存、规格文本

商品属性参数：材质、尺码、品牌等类目属性

店铺信息：店铺 ID、店铺昵称、店铺类型

营销促销信息：活动价、优惠券标签

2.适用业务场景

ERP 系统：定时同步商品，监控价格、库存变动
竞品分析：采集竞品商品基础信息，做价格波动监测
货源选品：提取标题、规格、图片做市场品类分析
跨平台铺货：清洗商品素材用于其他平台刊登
电商数据中台：对外输出标准化商品数据源

二、请求核心参数

公共请求参数

参数名	类型	是否必填	说明
method	string	是	固定taobao.item.get
app_key	string	是	开放平台分配应用密钥
timestamp	string	是	GMT+8 时区，格式yyyy‑MM‑dd HH:mm:ss；时间误差不可超过 10 分钟
v	string	是	协议版本，固定2.0
sign_method	string	是	签名算法，hmac‑sha256 /md5
sign	string	是	加密生成签名字符串
session	string	否	商家私有数据，需要 OAuth 授权获取 session

业务入参

参数名	类型	是否必填	说明
num_iid	long	是	淘宝 / 天猫商品宝贝 ID，从商品链接提取淘宝开放平...
fields	string	是	指定返回字段，逗号分隔；按需配置，不要全量获取，减少报文体积

三、完整 JSON 样例

{
    "item_get_response": {
        "request_id": "req‑20260923141000123456",
        "item": {
            "num_iid": "721456789234",
            "title": "夏季速干运动短袖男士透气健身T恤",
            "cid": 50015261,
            "pic_url": "https://img.alicdn.com/imgextra/i1/xxxx.jpg",
            "item_imgs": [
                {"url":"https://img.alicdn.com/imgextra/i1/xxx1.jpg"},
                {"url":"https://img.alicdn.com/imgextra/i1/xxx2.jpg"}
            ],
            "price": "69.00",
            "orginal_price": "129.00",
            "num": 5200,
            "sales": 3680,
            "seller_nick": "运动服饰旗舰店",
            "seller_id": "234567891",
            "location": "浙江杭州",
            "list_time": "2026‑03‑15 10:20:00",
            "desc": "<p>面料采用速干面料，适合跑步健身运动</p>",
            "props": "面料:聚酯纤维;版型:宽松",
            "skus": {
                "sku": [
                    {
                        "sku_id": "3214567890123",
                        "properties": "颜色:黑色;尺码:L",
                        "price": "69.00",
                        "quantity": 1200
                    },
                    {
                        "sku_id": "3214567890124",
                        "properties": "颜色:白色;尺码:XL",
                        "price": "69.00",
                        "quantity": 860
                    }
                ]
            }
        }
    }
}

四、核心返回字段释义

字段	释义	业务处理提示
num_iid	商品宝贝 ID	业务主键，用于重复调用，关联商品列表接口
title	商品标题	展示、AI 翻译、生成铺货标题
cid	商品类目 ID	类目筛选、市场统计分析
pic_url	商品主图	阿里 CDN 图片带防盗链，需下载转存自有对象存储
item_imgs	商品轮播图集	多图素材来源
price	销售价格	字符串类型，业务层转为 Decimal 做成本计算
orginal_price	划线原价	市场价展示使用
num	商品总库存	汇总库存；SKU 粒度库存读取 skus 数组
sales	商品销量	选品热度评估指标
seller_nick	卖家店铺昵称	店铺标识
location	发货地	供应链评估发货时效
desc	商品详情 HTML	业务清洗 HTML 标签提取纯文本
skus.sku	SKU 规格数组	循环解析；下架、特殊类目务必判空，防止数组越界

五、常见错误码说明

sub_code	错误说明	处理方案
isv.item‑get‑service‑error:ITEM_NOT_FOUND	未找到宝贝，商品删除 / 违规下架	捕获错误，本地标记商品失效，不再重试
isv.missing‑parameter:iid‑or‑numIid	缺少 num_iid 参数	入参校验，保证必传字段不为空
isp.system‑busy	调用频率过高，系统繁忙	降低 QPS，增加休眠、队列限流
isv.invalid‑permission	接口权限不足	检查应用是否申请该接口权限