淘宝商品详情 API（taobao.item.get）完整介绍与标准 JSON 返回示例

一、接口基础信息

1. 基础调用参数

接口名称：taobao.item.get（淘宝 TOP 开放平台标准商品详情接口）
网关地址：www.o0b.cn/anzexi
请求方式：POST（推荐）/ GET
返回格式：JSON
鉴权规则：app_key + app_secret 按 ASCII 升序生成签名 sign，携带 timestamp 时间戳防重放
核心入参：
1. method：固定 taobao.item.get
2. num_iid：商品数字 ID（必填）
3. fields：指定需要返回的字段（必填，按需拉取减少配额消耗）
权限要求：开发者后台申请接口调用权限，图片、SKU、销量等部分字段需额外权限包

2. 接口核心能力

传入商品num_iid，可获取商品标题、类目、原价 / 促销价、主图详情图、多规格 SKU、库存、发货地、商家信息、商品参数、卖点、详情 HTML 等全量商品结构化数据，是电商比价、竞品监控、ERP 铺货、选品分析的核心接口。

3. 主流业务落地场景

竞品价格监控：定时抓取同行商品售价、活动优惠，配置降价预警
多店铺 ERP 同步：拉取 SKU、库存、图文，同步至自有进销存系统
导购比价工具：采集商品基础信息搭建好物对比页面
跨境独立站铺货：批量提取标题、参数、素材用于海外站点上架
选品数据分析：通过价格、规格、发货地筛选潜力爆款

二、标准成功返回 JSON（官方完整脱敏示例）

复制代码

{
    "item_get_response": {
        "code": 0,
        "msg": "success",
        "request_id": "req_202607031120009966",
        "item": {
            "num_iid": "689235711245",
            "title": "2026夏季纯棉短袖女宽松百搭纯色基础T恤",
            "nick": "简禾服饰旗舰店",
            "cid": 16234,
            "category_name": "女装 > T恤",
            "type": "fixed",
            "price": "79.90",
            "promotion_price": "59.00",
            "has_discount": true,
            "location": "浙江杭州",
            "express_fee": "0.00",
            "sell_point": "100%纯棉面料，不起球不褪色，多色可选",
            "pic_url": "https://img.alicdn.com/imgextra/i1/O1CN01a12345.jpg",
            "item_imgs": [
                {
                    "url": "https://img.alicdn.com/imgextra/i1/O1CN01a12345.jpg"
                },
                {
                    "url": "https://img.alicdn.com/imgextra/i1/O1CN01a67890.jpg"
                }
            ],
            "desc": "<p>100%精梳纯棉，透气吸汗，日常通勤百搭，多种尺码颜色可选...</p>",
            "skus": [
                {
                    "sku_id": "123456789001",
                    "properties": "颜色:白色;尺码:M",
                    "price": "59.00",
                    "stock": 180,
                    "sku_img": "https://img.alicdn.com/imgextra/i1/white_m.jpg"
                },
                {
                    "sku_id": "123456789002",
                    "properties": "颜色:黑色;尺码:XL",
                    "price": "59.00",
                    "stock": 125,
                    "sku_img": "https://img.alicdn.com/imgextra/i1/black_xl.jpg"
                }
            ],
            "props_list": [
                {
                    "name": "面料",
                    "value": "100%纯棉"
                },
                {
                    "name": "版型",
                    "value": "宽松常规"
                },
                {
                    "name": "适用季节",
                    "value": "夏季"
                }
            ],
            "total_stock": 460,
            "detail_url": "https://item.taobao.com/item.htm?id=689235711245"
        }
    }
}

三、高频异常错误 JSON 示例

1. 签名校验失败 code=15

复制代码

{
    "item_get_response": {
        "code": 15,
        "msg": "Invalid signature",
        "request_id": "req_202607031122001234",
        "error_response": {
            "sub_code": "isv.invalid-sign",
            "sub_msg": "检查AppSecret、参数排序、服务器时间"
        }
    }
}

2. 接口 / 字段权限不足 code=11

复制代码

{
    "item_get_response": {
        "code": 11,
        "msg": "Insufficient permissions",
        "request_id": "req_202607031123005678",
        "error_response": {
            "sub_code": "isv.api-no-auth",
            "sub_msg": "未申请taobao.item.get接口权限或字段越权"
        }
    }
}

3. 商品不存在 / 已下架 code=27

复制代码

{
    "item_get_response": {
        "code": 27,
        "msg": "item not found",
        "request_id": "req_202607031124009012",
        "item": null
    }
}

4. 调用频率 / 日额度超限 code=7 / 429

复制代码

{
    "item_get_response": {
        "code": 7,
        "msg": "App Call Limited",
        "request_id": "req_202607031125003456",
        "error_response": {
            "sub_msg": "请求频次超出限制，请增加调用间隔"
        }
    }
}

5. 必填参数缺失 code=40

复制代码

{
    "item_get_response": {
        "code": 40,
        "msg": "Missing required parameter num_iid",
        "request_id": "req_202607031126007890"
    }
}

四、核心字段分类释义

1. 顶层通用状态

item_get_response：淘宝商品接口统一外层容器
code=0：请求正常；非 0 为平台 / 业务错误码
request_id：全局请求流水号，日志排查故障专用

2. 商品基础标识

num_iid：商品唯一数字 ID，查询核心主键
title：商品标题；nick：卖家店铺昵称
cid/category_name：叶子类目 ID 与类目名称
detail_url：淘宝商品详情页链接

3. 价格与物流

price：商品原价；promotion_price：实时促销券后价
has_discount：布尔值，是否有活动优惠
location：商品发货地；express_fee：快递运费（0 包邮）

4. 素材媒体信息

pic_url：商品主图地址
item_imgs：详情轮播图片数组，无图为空数组
desc：商品详情 HTML 富文本

5. SKU 规格模块

skus：多颜色、尺码规格数组
sku_id：子规格唯一 ID；properties：规格文字（颜色 + 尺码）
price：单规格售价；stock：单规格库存

6. 属性与库存

props_list：商品材质、尺寸、功能等参数数组
total_stock：商品总可售库存
sell_point：商品短卖点文案

五、开发接入注意事项

价格字段全部为字符串类型，金额计算时需转换为浮点型；
skus、item_imgs、props_list为数组，代码必须做空值判断，防止 JSON 解析崩溃；
接口 QPS 限制约 2 次 / 秒，批量采集需增加延时、本地缓存减少请求；
fields按需填写，只拉取业务需要的字段，节省每日调用配额；
签名生成严格遵循参数 ASCII 升序拼接，时间戳偏差超过 10 分钟会报签名错误；
仅允许合规运营、数据分析场景使用，禁止批量抓取倒卖第三方商品数据；
下架、删除商品返回item:null，业务代码需单独判空处理。