openclaw-voc-skill/claude-code/claude-code-voc-intelligence/docs/taobao-item-detail-v7.md

淘宝/天猫商品详情 V7 接口使用文档

1. 适用范围

V7 用于实时发起淘宝/天猫商品基础详情采集，适合获取较新的标题、基础价格、SKU、库存和店铺信息。

V7 不是商品页全部字段的统一接口。以下信息需要按口径补充其它版本：

• 页面展示的“已售/付款人数”：补充调用 V3，读取 data.sellCount。
• 较完整的商品属性、SKU 标价和促销价：补充调用 V6。
• 券后价或优惠后价：补充调用 V4。
• 账号、地区、会员、店铺券和平台补贴共同影响的最终结算价：以实际结算页为准。

2. 接口信息

项目	值
接口 ID	taobao.get_item_detail_v7
请求路径	taobao/get-item-detail/v7
请求方法	GET
参数位置	Query
通道	ecommerce
计费	1 次接口调用
推荐时效门槛	48 小时

3. 请求参数

参数	类型	必填	说明
itemId	string	是	淘宝或天猫商品 ID。可从商品链接的 id 参数中提取。

示例商品链接：

https://detail.tmall.com/item.htm?id=824950233983

对应 itemId：

824950233983

4. 使用 voc_api_call 调用

推荐使用清单 ID 调用，工具会自动选择 ecommerce 通道并应用重试、业务码识别和时效检查：

{
  "id": "taobao.get_item_detail_v7",
  "params": {
    "itemId": "824950233983"
  }
}

也可以先读取接口文档：

{
  "id": "taobao.get_item_detail_v7"
}

不经过清单 ID 时，等价的原始路径调用参数为：

{
  "rawPath": "taobao/get-item-detail/v7",
  "method": "GET",
  "channel": "ecommerce",
  "query": {
    "itemId": "824950233983"
  }
}

5. 核心返回字段

成功时，voc_api_call 返回 status=ok，上游结果位于 data.result，完整原始响应位于 data.raw。V7 重点读取以下字段：

字段	含义	使用规则
subject	当前采集到的商品标题	可作为当前基础标题，但仍需结合 recordTime 判断时效。
price	基础价格	标注为 V7 基础价，不表述为任意账号的最终结算价。
skuVoList	SKU 列表	可读取规格、SKU 价格和库存；数组长度可作为本次采集到的 SKU 数量。
shopName	店铺名称	用于店铺识别。
recordTime	上游数据采集时间	不是本次 API 请求时间，必须计算滞后时长。
monthSold	月销相关字段	可能为 null，不作为稳定的页面销量来源。
baseAttrList	基础属性列表	可能为 null 或不完整，关键属性应补充 V6。

工具会在 summary 中返回时效判断信息：

{
  "recordTime": "2026-09-01T16:06:58",
  "maxAgeHours": 48,
  "ageHours": 0.5,
  "stale": false
}

6. 时效规则

1. V7 会在调用时实时发起采集，但“实时发起”不等于每个返回字段都与商品页面同一秒刷新。
2. recordTime 表示上游完成数据采集的时间，不是 VOC API 的请求时间。
3. 技能包用“当前时间 - recordTime”计算 ageHours。
4. ageHours <= 48 时，结果可作为当前基础详情使用。
5. ageHours > 48 时，工具返回 status=stale_data；数据仍会保留在结果中，但只能作为历史参考。
6. 上游未承诺固定刷新 SLA，因此结果中应同时注明接口版本、recordTime 和价格/销量口径。

7. 状态与异常处理

状态	含义	处理方式
ok	V7 成功返回，且未超过 48 小时	读取标题、基础价、SKU、库存和店铺信息；按需补 V3/V4/V6。
stale_data	recordTime 已超过 48 小时	仅作历史参考，稍后重试 V7，不表述为当前页面数据。
upstream_unstable	上游业务码 301、5xx、连接失败或重试后仍未恢复	工具默认自动重试；连续失败后稍后再次调用。
not_supported	上游业务码 202	当前商品或数据口径不受该接口支持，检查商品是否下架，并改用其它可用版本核验。
needs_input	缺少 itemId 或参数格式有误	从商品链接提取正确的数字商品 ID 后重试。
needs_valid_token	token 缺失、失效或未被正确读取	配置有效的技能包调用凭据后重试。

HTTP 200 只代表网关请求成功。响应内嵌的业务码 301 或 202 不会再被技能包误判为成功商品详情。

8. 推荐调用顺序

1. 调用 V7 获取较新的标题、基础价格、SKU、库存、店铺和 recordTime。
2. 检查工具状态以及 summary.ageHours，只使用 48 小时内的数据作为当前基础详情。
3. V7 返回 301 时让工具完成自动重试；连续失败后稍后再次调用同一接口。
4. 需要页面展示销量时调用 V3，并同样检查其 recordTime 和 48 小时时效门禁。
5. 需要完整属性或标价/促销价时调用 V6；需要券后价时调用 V4。
6. 汇总时分别标注“V7 基础价”“V6 标价/促销价”“V4 优惠后价”“V3 页面销量”，不要合并成一个无口径说明的“真实价格/付款人数”。

9. 版本职责对照

版本	主要用途	重点字段/口径	注意事项
V7	新鲜基础详情，首选	subject、price、skuVoList、shopName、recordTime	monthSold、baseAttrList 可能为空。
V3	页面展示销量	data.sellCount	不返回价格；超过 48 小时后不能称为当前销量。
V4	优惠后价/券后价	DiscountPrice、SKU 最终价字段	仍会受账号、SKU、地区和活动影响。
V6	较完整详情和属性	标价、促销价、SKU、属性	可能返回历史快照，必须检查 recordTime。
V9	兼容旧口径	num 为销售量级信号，totalCount 为评价总量	两者都不是商品页当前付款人数，属性也可能是旧快照。

10. 2026-09-01 实测记录

商品 ID	V7 结果	说明
824950233983	成功；recordTime=2026-09-01T16:06:58；基础价 21.8；7 个 SKU	V7 返回了当天的新鲜基础详情。
865522000056	成功；基础价 33.8；3 个 SKU	可用于基础价格和 SKU 核验。
872904000992	首次 301，重试后成功；基础价 32；12 个 SKU	说明 301 应先重试，不能直接作为“无数据”。
798980050440	多次返回 301	本次采集不稳定，按 upstream_unstable 处理。
1053323886896	返回 301，页面商品已不存在	商品下架或不存在时，不应继续使用旧版本残留快照作为当前详情。

11. 结论

需要一个优先返回较新基础详情的接口时，使用 V7。需要完整复刻淘宝/天猫商品页时，仍需按字段口径组合 V7、V3、V4 和 V6；当前不存在一个稳定覆盖页面标题、全部属性、页面销量、所有 SKU 优惠和最终结算价的单一接口。