# 淘宝/天猫商品详情 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` 参数中提取。 |

示例商品链接：

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

对应 `itemId`：

```text
824950233983
```

## 4. 使用 `voc_api_call` 调用

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

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

也可以先读取接口文档：

```json
{
  "id": "taobao.get_item_detail_v7"
}
```

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

```json
{
  "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` 中返回时效判断信息：

```json
{
  "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 优惠和最终结算价的单一接口。