🛍️ 淘宝商品详情API（taobao.item.get）Python/Java调用实战与字段解析

一、接口关键信息

⚠️ 淘宝商品ID（num_iid）可从商品URL中提取：https://item.taobao.com/item.htm?id=654321098765→ num_iid=654321098765

二、Python完整调用封装（复用TOP签名Client）

# top_item_get.py
"""
淘宝商品详情 taobao.item.get 调用示例
依赖: top_api_client.py (TaobaoTopClient from 上文)
"""
from top_api_client import TaobaoTopClient

# 封装好API供应商demo url=https://console.open.onebound.cn/console/?i=Lex
def get_tb_item_detail(num_iid: str, fields: str = None,
                        app_key=None, app_secret=None,
                        session=None, sandbox=True):
    """
    获取淘宝/天猫商品详情

    Args:
        num_iid:   商品ID (num_iid)
        fields:    返回字段，逗号分隔；
                   推荐: "num_iid,title,price,org_price,pic_url,item_imgs,skus,"
                           "props_name,desc,approve_status,num,outer_id"
        session:    卖家授权token（取SKU库存等需传）
        sandbox:    True=沙箱 False=生产
    Returns:
        item 字典
    """
    client = TaobaoTopClient(
        app_key=app_key,
        app_secret=app_secret,
        sandbox=sandbox
    )

    fields = fields or (
        "num_iid,title,price,org_price,pic_url,item_imgs,"
        "skus,props_name,desc,approve_status,num,outer_id,"
        "seller_nick,cid,input_str"
    )

    result = client.call(
        "taobao.item.get",
        biz_params={"num_iid": num_iid, "fields": fields},
        session=session
    )
    return result.get("item", result)


# ======================= 使用示例 =======================
if __name__ == "__main__":
    ITEM_ID = "654321098765"   # ← 替换真实商品ID（自己的店铺商品或公开商品）

    try:
        item = get_tb_item_detail(
            num_iid=ITEM_ID,
            app_key="YOUR_TOP_APP_KEY",
            app_secret="YOUR_TOP_APP_SECRET",
            sandbox=True   # 生产切 False；公开商品沙箱返回mock
            # session="SELLER_SESSION"  # 查自己店铺商品SKU库存需传
        )

        print("✅ 商品标题:", item.get("title"))
        print("   一口价:", item.get("price"))
        print("   主图:", item.get("pic_url"))
        print("   库存:", item.get("num"))
        print("   SKU数:", len(item.get("skus") or []))

        # 解析SKU
        for sku in (item.get("skus") or [])[:3]:
            print(f"     SKU {sku.get('properties_name')} → 价:{sku.get('price')} 库:{sku.get('quantity')}")

        if not item.get("skus"):
            print("   ℹ️  skus为空 → 若是自己店铺商品需传 seller session 再查")

    except Exception as e:
        print("❌", e)

三、核心返回字段解析（B2B/B2C铺货重点）

SKU 典型结构

{
  "sku_id": "1234567890",
  "properties": "1627207:28335;20509:28381",
  "properties_name": "颜色:红色;尺码:M",
  "price": "199.00",
  "quantity": 50,
  "outer_id": "SKU-RED-M"
}

四、Java调用核心片段（TOP Java SDK）

// TaobaoClient + JsonParser 由 top-sdk-java 提供
TaobaoClient client = new DefaultTaobaoClient(
    "https://gw.api.taobao.com/router/rest",
    "APP_KEY", "APP_SECRET"
);

ItemGetRequest req = new ItemGetRequest();
req.setNumIid(654321098765L);
req.setFields("num_iid,title,price,pic_url,skus,desc,num");

ItemGetResponse rsp = client.execute(req);  // session传null查公开字段
Item item = rsp.getItem();

System.out.println(item.getTitle());
System.out.println(item.getPrice());

五、高频避坑

六、面试/方案一句话

taobao.item.get按 num_iid+ fields获取商品结构化数据；公开字段（标题/价格/主图）可不传session，SKU库存和商家编码需卖家AccessToken；返回SKU用 properties_name做规格映射，图片需转存目标平台图床再上架。