linkfox-etsy-product-detail

Etsy 商品詳細の検索

商品調査や競合ページの監査のため、Etsy の商品 URL から、1 件の出品の現在の公開詳細を取得します。

基本概念

• 出品の直接 URL が必要です：パスが /listing/<numeric-id> または /listing/<numeric-id>/<one-slug-segment> で、末尾のスラッシュとクエリ文字列は任意の Etsy HTTPS URL を使用してください。
• 1 回の呼び出しにつき 1 件の出品：これは詳細検索であり、Etsy のキーワード検索や一括スクリーニングではありません。
• 公開ページの構造化データ：レスポンスには、出品、価格、メディア、ショップ、配送、レビュー概要の各フィールドが含まれます。
• 現在のスナップショット：値は照会時に公開出品ページで確認できる情報を反映しており、欠落または不整合がある場合があります。

データフィールド

フィールド	説明
productId / productUrl	Etsy の出品 ID と正規 URL／商品 URL
title / description	出品のタイトルと説明セクション
image / images	メイン画像と画像一覧
price / lowPrice / highPrice / oldPrice	現在価格、価格帯、以前の価格を表す文字列（取得可能な場合）
currency	返される通貨コード
maxQuantity / variants	報告された最大数量とバリエーションの選択肢
category	Etsy のカテゴリー階層
countryShippingFrom	発送元の国
deliveryDaysMin / deliveryDaysMax	配達予定期間。null または省略される場合があります
shopId / shopName / shopUrl / shopSales	ショップの識別情報と公開販売データ
reviews / star / shopReviews	出品のレビュー件数、評価、ショップのレビュー件数
highlightsTags / reviewsTags	購入者のフィードバックに関するハイライトとタグの頻度
reviewsScores	動的なレビュー評価の内訳。キーは出品によって異なります
yearsOnEtsy	ショップの公開運営年数
hasRatingsBadge / hasConvosBadge / hasShippingBadge	ショップ／出品の公開バッジの有無
moreLikeUrl / searchPosition	関連リンクまたは検索元の掲載位置に関するフィールド（取得可能な場合）

このツールが返すのはレビューの集計情報であり、個々のレビュー記録ではありません。

パラメーターガイド

パラメーター	必須	デフォルト	説明
productUrl	はい	-	etsy.com またはそのサブドメイン上の公開 Etsy HTTPS 出品 URL。認証情報を含めず、デフォルトの HTTPS ポートを使用してください。パスは /listing/<numeric-id> とし、スラッグセグメントは最大 1 つです。末尾のスラッシュとクエリ文字列は任意です

検索ページ、ショップページ、Etsy 以外のホスト、数値の出品 ID を含まない出品 URL は有効な入力ではありません。

呼び出し方法

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

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-etsy-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／プランの期限切れ／チャージが必要／チャージしてください」、または同様の意味の内容が含まれています。

使用例

python scripts/etsy_product_detail.py '{"productUrl":"https://www.etsy.com/listing/1710567856/its-okay-to-make-some-mistakes-shirt"}'

表示ルール

1. タイトル、出品ID、ショップ名、カテゴリー、価格帯、通貨を先頭に表示します。
2. メイン画像をインラインで表示し、残りの画像はすべてデフォルトで表示せず、残りの枚数を示します。
3. バリエーションと数量は、取得できた場合にのみ表示します。バリエーションが空のリストでも有効な結果です。
4. 出品商品のレビューとショップのレビューを区別し、購入者フィードバックのタグは集計結果であることを明示します。
5. 配送予定は、ソースの両方の値に意味がある場合にのみ表示します。null は利用不可として保持します。
6. ユーザーから明示的な依頼がない限り、価格文字列を正規化または変換しないでください。
7. 欠落、空、または不自然なショップ情報は抽出の不確実性として扱い、黙って修正しないでください。
8. 長い説明文や画像配列は、まず要約し、必要に応じて保存済みの JSON から正確な内容を抽出します。

重要な制限事項

1. Etsy 公開ページの構造が変更されると、フィールドが欠落したり、空になったり、まれに誤認識されたりすることがあります。
2. star、価格フィールド、配送予定、ショップのメタデータ、バッジは、すべての出品商品で取得できるとは限りません。
3. レスポンスにはレビュー数、タグ、集計スコアが含まれますが、個々の購入者レビューは含まれません。
4. このツールは、過去の価格、Etsy のキーワードランキング、保証された販売予測を提供しません。
5. このツールでは Etsy を検索できません。キーワード検索や複数のフィルターを使った商品検索が必要な場合は、Etsy 商品クエリスキルを使用してください。

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

該当するケース — URL が判明している Etsy の出品商品が 1 件：

ユーザーの発言	シナリオ
“查这个 Etsy 商品链接的详情”	出品商品詳細の検索
“提取这个 Etsy Listing 的标题、描述和图片”	出品商品コンテンツの抽出
“看看它的价格区间、变体和发货信息”	商品内容と配送情報の確認
“这个 Etsy 商品的店铺和评论概况如何？”	ショップとレビュー概要の検索

該当しないケース：

• Etsy のキーワード検索、カテゴリー検索、複数商品のスクリーニング
• 特定の出品商品 URL を指定しない Etsy ショップの検索／ランキング
• レビュー本文全体からの個別レビュー取得や感情分析
• 出品商品の作成・編集、注文管理、その他の出品者アカウント操作

算力消費ルール

算力を 6 消費します。

ユーザーは算力の消費に対して料金を支払います。他の出品商品を繰り返し検索する場合は、その都度料金が発生します。追加で実行する前に、追加の消費についてユーザーに知らせてください。

フィードバック：

説明されている機能と実際の動作に違いがある場合、結果がユーザーの意図に沿わない場合、ユーザーが称賛または不満を表明した場合、またはスキルを改善できる場合は、Feedback API を使用してフィードバックを自動検出し、報告します。ユーザーの操作を中断せずに references/api.md に従ってください。

---

高品質でプロフェッショナルな越境 EC スキルについては、LinkFox Skills をご覧ください。