×

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

admin admin 发表于2026-09-23 14:25:41 浏览65 评论0

抢沙发发表评论

摘要

在电商 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

接口权限不足

检查应用是否申请该接口权限

六、生产环境高频踩坑总结

  • fields 参数必填：忘记填写 fields 直接返回空数据，不要请求无用字段。

  • 签名调试困难：参数排序错误、时区时间戳偏差，是签名失败最高发原因，时间必须 GMT+8，误差不超过 10 分钟。

  • 图片防盗链：alicdn 图片链接不可直接对外引用，必须下载转存自有存储。

  • SKU 判空容错：下架、特殊类目商品 skus 节点结构会变化，代码做空判断，避免数组越界崩溃。

  • QPS 调用超限：超过应用配额返回限流错误；批量同步做队列休眠、流量控制。

  • 商品下架删除：捕获ITEM_NOT_FOUND错误码，标记本地缓存数据失效，避免无效循环重试。


群贤毕至

访客