> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 研究TikTok Shop商品，怎样从搜索结果读出买家在意的使用问题？

> 固定商品与地区，从相关候选读取评价，分开规格、使用体验、包装配送与筛选样本，形成有原句的问题清单。

研究一类 TikTok Shop 商品时，先用 `tiktok.shop.web.fetch_search_products_list_v2` 在一个地区搜商品，选中具体商品 ID 后，在同一地区用 `tiktok.shop.web.fetch_product_reviews_v2` 读该商品的买家评价。已有商品 ID 时直接从评价开始。交付时把商品规格、使用体验和配送问题分列，每条原句放在所属商品下面。

例如对比瑜伽垫，先确认长度与厚度，再区分买家反馈的是收纳、尺寸还是防滑。评价没写规格时，标为待核，留在同一商品的样本里。

## 1. 固定地区和本轮问题

商品、价格和评价都属于选定的市场，所以搜索和评价请求使用同一个 `region`。BeatAPI V2 当前支持 US、SG、MY、PH、TH、VN、ID、JP、MX，GB 和 BR 不支持；实际状态以响应返回为准。

不支持的地区可能返回 HTTP 200、`data.region_supported: false` 和支持的地区列表。`data.region_supported: false` 表示本次地区不可用，不是该市场没有商品或买家评价。先记录状态，再决定下一步。

## 2. 搜索首批相关商品

调用 `tiktok.shop.web.fetch_search_products_list_v2`，美国站示例：

```json
{
  "action": "tiktok.shop.web.fetch_search_products_list_v2",
  "params": {"search_word": "yoga mat", "region": "US", "offset": 0, "page_token": ""}
}
```

把请求体提交到 `POST https://api.beatapi.io/v1/social-data/call`，使用常规 BeatAPI Bearer 鉴权。保留关键词、地区、取得时间、原始响应和请求号。

读取实际的商品对象，核对名称、店铺、规格和来源后，再保存原始商品编号；商品编号不是视频 ID 或作者账号 ID。价格、币种、评分和销量有返回时，保留原字段名和单位，缺失留空，不根据地区补币种，也不从价格猜品质。

商品搜索不提供固定的顶层列表、价格、销量或店铺路径，不要假定 `data.items` 或 `metrics.sold`，也不要用未核对的字段自动选「销量前五」。先按实际相关性挑要读的商品。

## 3. 读取选中商品的最新评论

调用 `tiktok.shop.web.fetch_product_reviews_v2`，先看全部评分、按最新排序：

```json
{
  "action": "tiktok.shop.web.fetch_product_reviews_v2",
  "params": {"product_id": "<confirmed_product_id>", "region": "US", "page_start": 1, "sort_rule": 2, "filter_type": 1, "filter_value": 6}
}
```

V2 评价输入没有 `page_size`，实际条数按返回记录。排序和筛选决定样本范围，首批评价不是商品的全部历史评价。

| 需要补读什么    | V2选择                                 |
| --------- | ------------------------------------ |
| 最新与推荐口径   | `sort_rule: 2` 最新，1 推荐               |
| 全部评分      | `filter_type: 1`、`filter_value: 6`   |
| 某一星级      | `filter_type: 1`、`filter_value: 1–5` |
| 带图片或视频的评价 | `filter_type: 2`、`filter_value: 1`   |
| 平台的已购评价筛选 | `filter_type: 3`、`filter_value: 1`   |

有具体问题时再补读低星或带媒体的样本，并保留筛选条件。低星样本用来找问题，不能单独用来估算全体买家中某个问题的比例。画面分析必须实际读取媒体，评价文字不等于已经看过图片内容。

## 4. 哪些内容值得整理？

下表演示如何整理和分类买家评价：

| 评价方向           | 保留什么         | 下一步               |
| -------------- | ------------ | ----------------- |
| “收卷后放不进袋子”     | 实际规格、袋子信息与原句 | 核对尺寸说明和配套信息       |
| “包装有损，但物品可用”   | 包装与产品状态分别记   | 客服/配送核对，不直接归为使用缺陷 |
| “尺寸适合我的空间”     | 实际尺寸和使用场景    | 留作有条件的正面体验        |
| “买错了厚度，换规格后好了” | 原规格、纠正与后续情况  | 分规格比较，补选购说明       |

工作表保留以下字段：商品/地区、评价的实际标识与来源、评分（有则记）、规格、原句、主题、使用条件、判断理由、待核项、取得时间和请求号。

同一条评价跨页出现时，按实际标识核对；译文和原句分列。没写规格的评价，规格列标待核，不替买家补款式。评分与文字不一致时两者都保留，先读上下文。

## 5. 怎样继续而不丢筛选范围？

1. 实际响应返回 `has_more=1` 时，用当前 `page_start + 1` 继续翻页。请从真实响应确认 `has_more` 的具体位置，不要套用 `page.next_cursor`。

2. 商品、地区、排序和筛选保持不变，每次另存原始响应。

3. 商品搜索另用 `offset` 和 `page_token` 翻页，按搜索响应的实际返回值续读，与评价页号分开保存。搜索目前没有固定的续页输出路径，不要按猜测的每页长度递增 offset。

每读一批，先看是否补到了新规格、使用条件或纠正。达到本轮页数计划、没有可用的续页标志、内容重复或读取失败时，说明停止原因和未完成的部分。

## 6. 给团队的交付怎样写？

先列证据最充分的问题和正面体验，每项附原句、商品/规格、地区和实际样本范围；再分组列出产品说明、包装配送和需要追问的条件。只读了某一评分或带媒体的筛选样本时，结论也标明该筛选条件。

可以这样向助手交代任务：

> 在美国站找相关瑜伽垫，按实际商品与规格选候选，再读最新评价。把收纳、尺寸、包装与使用体验分开，每项附原句、条件和来源。需要低星或晒图材料时说明用途，保留筛选条件，不将筛选样本比例视作全体买家比例。

按当前[价格页](https://beatapi.io/zh/pricing)规划实际的商品搜索页和评价页。统一字段的自动 CSV 还需要本地输出映射；阅读时直接复用已保存的原始响应。

## 需要给入选商品补详情时

需要核对规格、页面描述或价格时，把已确认的 `product_id` 和同一市场的 `region` 传给 `tiktok.shop.web.fetch_product_detail_v3`。显式填写 `region`，让详情请求与搜索地区一致。遇到 `data.region_supported:false` 时，记录该市场不可用；价格、运费、销量和规格只登记响应里实际出现的字段。公开商品研究从可用的市场样本开始。自己店铺的库存、订单或退款，使用你已获授权的卖家后台资料。