linkfox-tiktok-shop-product-detail

TikTok Shop 产品详情查询

通过产品 URL 或 19 位产品 ID，获取一个 TikTok Shop 产品当前公开的详情，可选指定市场区域。

核心概念

• 每次调用查询一个产品：productInput 用于标识一个产品；这不是搜索或排名工具。
• 市场环境：region 用于选择店铺环境，默认值为 US。
• 分组数据易读：服务会返回一组稳定、易读的产品详情分组。
• 当前快照：数值反映请求时公开店铺展示的信息，而非历史分析数据。

数据字段

data 中的每个对象可能包含以下顶层分组：

字段	描述
productId	TikTok Shop 产品 ID
status	平台产品状态码；不要仅凭此字段推断产品是否有货
title	产品标题
category	类别名称和 ID
pricing	货币、售价、原价、折扣及来源定价字段
sales	公开售出数量及相关销售展示数据
inventory	总库存、SKU、变体属性、价格及默认选项
media	产品图片 URL 和图片元数据
seller	卖家 ID、店铺名称、评分、所在地及可用的店铺数据
reviews	可用时提供的公开评论摘要
shipping	可用时提供的物流和配送模块
actions	购买按钮和收藏状态数据
additional	其他易读的促销、权益、评论入口和产品模块

嵌套字段因产品和地区而异。请保留返回的值，不要臆造缺失字段。

参数指南

参数	必填	默认值	描述
productInput	是	-	TikTok HTTPS URL，域名为 tiktok.com 或其子域名，使用默认 HTTPS 端口，且路径包含 product/<19-digit-id>；或以字符串形式传入的 19 位产品 ID
region	否	US	大写店铺区域代码：US、GB、ID、MY、TH、VN、PH、SG、DE、FR、IT 或 ES

调用方式

• API 端点：POST /tiktok/shop/product/detail（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/tiktok_shop_product_detail.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-tiktok-shop-product-detail-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读取数据建议：先查看摘要，判断信息是否足够；需要具体字段时，优先使用 jq 或 ConvertFrom-Json 从保存的 json 文件中按需提取，避免将整份 JSON 载入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置 API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应 401 或 402 状态码。
• 响应提示算力或余额不足：消息含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义。

使用示例

产品 URL

python scripts/tiktok_shop_product_detail.py '{"productInput":"https://shop.tiktok.com/view/product/1729937400435937604","region":"US"}'

英国店铺的产品 ID

python scripts/tiktok_shop_product_detail.py '{"productInput":"1729937400435937604","region":"GB"}'

显示规则

1. 先显示产品标题、产品 ID、所请求的地区、类别和返回状态。
2. 显示售价／原价及返回的货币；除非用户另行要求，否则不要换算货币。
3. 如有 SKU 变体、变体价格和库存，请用表格呈现。
4. 在有用时内嵌显示产品图片，但不要一次显示所有图片，以免内容过多。
5. 仅在有相关信息时显示卖家、公开销量、评价摘要和配送信息。
6. 综合判断 status、库存和购买按钮数据；不能仅凭单个字段就称产品“有货”。
7. 缺失、为空或不一致的字段应报告为不可用，而非估算。
8. 对于大型嵌套部分，先概述；仅在需要时从已保存的 JSON 中读取具体字段。

重要限制

1. 公开字段可能因产品、卖家、地区和店铺上下文而异。
2. URL 输入必须包含 product/<19-digit-id> 路径段；如果无法使用其他 TikTok URL 格式，请直接使用 19 位产品 ID。
3. 即使产品已下架、不可用或缺货，仍可能返回结构化元数据。
4. 此工具不提供历史价格／库存趋势、排名列表或有保证的销售分析数据。
5. 此工具不管理经过授权的卖家账户，也不编辑商品信息；卖家操作请使用 TikTok Shop ERP 商品技能。
6. 由于 SKU、媒体、配送和其他模块会保留嵌套的源字段，可读响应可能很长。

用户表达与场景速查

适用 — 已知的单个 TikTok Shop 商品：

用户说	场景
“查这个 TikTok Shop 链接的商品详情”	URL 详情查询
“这个 19 位 TikTok 商品 ID 卖什么？”	产品 ID 查询
“看看这个商品的价格、SKU 和库存”	当前商品信息审查
“提取这个 TikTok 商品的图片和店铺信息”	媒体和卖家信息提取

不适用：

• TikTok 商品搜索、畅销商品排名或多商品筛选
• 历史 GMV、创作者、直播或视频归因分析
• 经过授权的店铺商品创建、编辑、价格变更或库存变更
• TikTok 视频页面或创作者个人资料分析

算力消耗规则

消耗 63 算力。

用户会因算力消耗而支付费用。查询不同地区或不同商品会分别计费；继续调用前应让用户知晓额外消耗。

反馈：

当所述能力与实际行为不符、结果未能满足用户意图、用户表达赞赏或不满，或技能有改进空间时，通过 Feedback API 自动检测并报告反馈。请遵循 references/api.md，不要打断用户的使用流程。

---

如需更多高质量、专业的跨境电商技能，请访问 LinkFox Skills。