linkfox-echotik-batch-product-detail

EchoTik TikTok バッチ商品詳細

このスキルでは、TikTok Shop の商品の詳細なパフォーマンス指標を一括取得する方法を説明します。販売者や運用担当者が、売上、GMV、ライブ配信、動画、インフルエンサーのデータを使って候補商品を横並びで比較できます。

コアコンセプト

このツールは、1 回の呼び出しで最大 1000 件の TikTok Shop 商品の詳細指標を取得します。商品 ID、および／または TikTok Shop 商品 URL で商品を指定します。バックエンドは各 URL から productId を抽出し、指定された ID と統合して、商品ごとの分析データを返します。

入力オプション（少なくとも 1 つ必要です。両方を組み合わせることもできます）：

• productIds — TikTok 商品 ID の配列
• productUrls — TikTok Shop 商品 URL の配列（例：https://shop.tiktok.com/us/pdp/<slug>/<productId>?...）。各 URL の末尾にある productId が抽出されます

複数期間の指標：売上、GMV、ライブ配信数、動画数、インフルエンサー数、視聴数はそれぞれ、1d / 7d / 15d / 30d / 60d / 90d の期間と累計で報告されるため、直近の勢いと長期的な合計の両方を確認できます。

価格の通貨は USD：minPrice、maxPrice、spuAvgPrice は USD での値です。

ステータスフラグ（整数）：salesTrendFlag — 0=安定、1=上昇、2=下降。isSShop — 完全管理（全托管）ショップ。offMark — 販売停止。freeShipping — 送料無料。

検索との違い：このツールは、既知の商品（ID／URL をすでに把握している商品）の詳細を照会するためのものです。キーワードで商品を見つけるには linkfox-echotik-product-search を、新商品ランキングには linkfox-echotik-new-product-rank を使用してください。

パラメーターガイド

パラメーター	型	必須	説明	デフォルト
productIds	array<string>	いいえ*	TikTok 商品 ID（最大 1000 件）	-
productUrls	array<string>	いいえ*	TikTok Shop 商品 URL。各 URL から productId が抽出され、productIds と統合されます（最大 1000 件）	-

* productIds／productUrls の少なくとも一方を指定する必要があります。両方を同時に渡すこともできます。

呼び出し方法

• API エンドポイント：POST /echotik/batchProductDetail（パラメーター／レスポンス／エラーコードの詳細は references/api.md を参照）
• Python スクリプト：python scripts/echotik_batch_product_detail.py '<JSON 参数>' [--inline]
• コスト制限：このツールは計算リソースを消費します。同一セッション内で同じパラメーターの組み合わせを使う呼び出しは、デフォルトで 1 回のみです。スクリプトには 24 時間のローカルキャッシュがあります。失敗や空の結果が返された場合、キーワードの変更、ページ送り、郵便番号の変更を行って自動的に再試行してはいけません。検索を続ける必要がある場合は、追加の消費が発生することを先にユーザーに伝えてください。

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-batch-product-detail-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリにあたります。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクに応じて自動的にまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的なカウント値、最大のリストフィールドの長さと先頭 3 件のサンプル）
• --inline を指定すると、stdout に全件を強制的に出力します（同様にファイルにも保存されます）

データの読み取りに関する推奨事項：まず要約を確認し、十分かどうかを判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに読み込まずに済むよう、保存された json ファイルから jq または ConvertFrom-Json を使って必要なデータを抽出してください。

認証と計算リソースに関する問題の解決

以下の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY と LINKFOXAGENT_API_KEY のどちらも設定されていません。
• 401 または 402 のレスポンスステータスコード
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值」など、または同様の意味の内容が含まれています。

使用例

1. 商品 ID による一括照会

{
  "productIds": ["1729382310407603945", "1729382310407603946"]
}

2. 商品 URL による一括照会

{
  "productUrls": [
    "https://shop.tiktok.com/us/pdp/phone-case/1729382310407603945",
    "https://shop.tiktok.com/us/pdp/case-for-phone/1729382310407603946"
  ]
}

3. ID と URL を混在させた一括照会（サーバー側で統合）

{
  "productIds": ["1729382310407603945"],
  "productUrls": ["https://shop.tiktok.com/us/pdp/phone-case/1729382310407603946"]
}

表示ルール

1. 比較表を表示する：商品ごとに1行を設け、主要な列（名前、価格（USD）、総販売数、直近30日間の販売数、総 GMV、評価、レビュー数、コミッション率、プロモーションを行うインフルエンサー数）を含めます
2. 複数期間の情報を示す：勢いを比較する際は、累計だけでなく、関連する期間（例：7日／30日）も併記します
3. 通貨：価格は USD です。USD と明記します
4. コミッション率の表示：productCommissionRate はパーセンテージで表示します（例：0.05 → 「5%」）
5. トレンドフラグ：salesTrendFlag は、ひと目で確認できるよう「横ばい／上昇／下降」として表示します
6. ステータスバッジ：isSShop（全托管）、offMark（販売終了）、freeShipping を該当する場合に表示し、販売終了商品を知らずに比較することがないようにします
7. 画像の参照：imageUrl／productImageUrls がある場合は、画像を利用できることを記載します
8. 長い説明文：descDetail は HTML／テキストが長い場合があるため、全文を表示せず、要約するか利用可能であることを記載します
9. 商品が見つからない場合の対応：指定した商品が見つからない場合は、データがなかった ID／URL を列挙し、ユーザーが確認できるようにします
10. エラー処理：クエリに失敗した場合は、errmsg／error フィールドにある理由を説明し、ID／URL の確認を提案します

重要な制限事項

• 一括処理の上限：1リクエストにつき最大1000商品
• 価格の通貨：価格フィールドはすべて USD です
• 推定データ：販売数、GMV、アトリビューションの数値は分析上の推定値であり、プラットフォームの正確な数値ではありません
• 照会のみ：このツールではキーワードやカテゴリによる検索はできません。すでに把握している特定の ID／URL を照会します

ユーザーの表現とシナリオのクイックリファレンス

対応するシナリオ

ユーザーの発言	シナリオ
「これらの TikTok 商品の詳細を調べて」	商品 ID による一括詳細照会
「これらの TikTok リンクの販売データを取得して」	商品 URL による一括詳細照会
「これらの TikTok 商品の GMV を比較して」	一括照会、GMV の列を表示
「これらの TikTok 商品のうち、売上が伸びているのはどれ？」	一括照会、salesTrendFlag を確認
「これらの TikTok 商品に販売終了／全托管の商品はある？」	一括照会、offMark／isSShop を確認
「これらの TikTok 商品のライブ配信販売数を取得して」	一括照会、ライブ配信の販売数／GMV を表示

対応しないシナリオ

• キーワードによる商品検索（linkfox-echotik-product-search を使用）
• 新商品／人気商品のランキング（linkfox-echotik-new-product-rank を使用）
• 商品に関連付けられたプロモーション動画（linkfox-echotik-product-video を使用）
• TikTok 動画のダウンロードリンクの解決（linkfox-echotik-get-video-download-url を使用）
• TikTok クリエイター／インフルエンサーのプロフィール分析
• TikTok 以外のプラットフォームの商品データ

適用範囲の判断

ユーザーが「これらの TikTok 商品を分析して」と言った場合、すでに特定の商品 ID または TikTok Shop の URL を持っているのか（このスキル）、それともキーワード／カテゴリで商品を見つけたいのか（検索スキル）を確認します。ID／URL のリストを貼り付けて、販売数／GMV／ライブ配信の詳細を求めている場合は、このスキルが適用されます。「TikTok で何を販売すべきか」や「人気商品を見つけて」と尋ねている場合は適用されません。

算力消耗规则

算力消耗为 5。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

出现以下任一情况时，通过 Feedback API 自动检测并提交反馈：

1. 此技能所述的功能或用途与实际行为不符
2. 技能的结果与用户意图不符
3. 用户对该技能表达不满或赞扬
4. 任何你认为可以改进的情况

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

---

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