TikTok Shop User Showcase API

TikTok Shop User Showcase

主要特性

• 单 username Showcase 采集采集一个 TikTok username 公开展示的商品，username 可带或不带开头的 @。
• 市场地区选择从 16 个受支持的 region 中选择目标值，让 Showcase 采集面向指定公开 TikTok Shop 市场。
• 限量去重商品结果可请求 20 至 2,000 条 Showcase 商品，并在逐页采集时按公开商品身份去重。
• 标准化商品与卖家上下文在来源提供时返回商品 ID、标题、说明、规范链接、图片、卖家字段、价格、分类和 SKU 结构。
• 可见商业信号与公开边界保留可用的评分、评价数、已售数量、状态、地区和采集时间，公开来源未提供的字段保持为空。

参数

如何使用

把一个公开 username 和市场作为异步任务提交，再通过 cursor 分页读取已保存的 Showcase 商品。

1. 准备一个公开 TikTok username，选择受支持的 region，并把 results_limit 设为 20 至 2,000。
2. 把请求 POST 到 /v1/tiktok-shop/user-showcase，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务进入 succeeded 或 failed 状态。
4. 从 data.results.items 读取商品；has_more 为 true 时继续传入 next_cursor。

curl -X POST "https://api.socq.ai/v1/tiktok-shop/user-showcase" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"mrtiktokreviews","results_limit":100,"region":"US"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 复核用户 Showcase 商品组合： 结合商品 ID、标题、链接、卖家信息、图片和分类，检查一个 username 公开展示的商品。
• 比较价格与可见需求信号： 在返回的 Showcase 商品之间比较可用价格、币种、折扣、评分、评价数和已售数量。
• 创建区域 Showcase 快照： 保存 input_username、region、商品身份、公开商业字段和 collected_at，形成可重复检查的时间点记录。
• 补全商品研究数据集： 为已有的 username 研究集合补充商品规范 URL、卖家身份、媒体、分类、SKU 上下文和可见指标。

使用建议

• 跨次请求保持 username 写法稳定；接口同时接受 @handle 和 handle，并为每条商品记录保留规范化后的输入 username。
• 选择与目标目录匹配的 region，因为默认值为 US，非美国市场的公开商品可用性可能不同。
• 按所需覆盖范围把 results_limit 设为 20 至 2,000，不要假设每个 Showcase 都包含默认的 100 条商品。
• 任务成功后在 has_more 为 true 时持续使用 next_cursor，避免遗漏已保存但尚未读取的商品。
• 按商品 id 对快照去重，并把空任务以及缺失的卖家、价格、媒体、分类、SKU 或指标字段视为有效的公开来源结果。

相关 API