摘要
在电商 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 错误码，标记本地缓存数据失效，避免无效循环重试。
