linkfox-seerfar-ozon-product-detail-search

Seerfar Ozon 商品详情搜索

此スキルは、Seerfar 分析データベースから SKU を指定して、単一の Ozon 商品の詳細情報をすべて取得します。取得できる情報は、タイトル、価格（₽）、評価、レビュー数、Q&A 数、販売数（合計＋日次平均＋日次推移）、売上高、在庫、カテゴリー順位、ブランド、販売者、フルフィルメント（FBO/FBS/OZON）、重量、出品期間です。単一商品の詳細分析、競合商品の分析、商品ページの診断、販売トレンドの追跡を始める際に使用します。

基本概念

データの単位は sku で検索する単一商品です：Ozon の SKU を 1 つ渡すと、その商品の詳細情報をすべて取得できます。これは商品単位（1 SKU）の表示であり、ショップの商品カタログ、キーワード、カテゴリー単位の表示ではありません。

SKU の取得元：sku は Ozon 商品の SKU です。ほかの Seerfar Ozon ツール（ショップ検索、キーワード逆引き検索、カテゴリー検索、市場キーワード検索）が返す sku と同じものです。ユーザーが商品名、URL、ショップしか持っていない場合は、まずそれらの商品一覧レベルの情報源から sku を取得し、その後、このスキルを呼び出して詳細を分析します。

販売期間：dateRange で販売数／指標の対象期間を指定します。totalSales、dailySales、totalRevenue、salesTrendVOList は、この期間を対象に算出されます。デフォルトは past_30_days です。選択肢：past_7_days / past_30_days / past_60_days / past_90_days / past_180_days / past_365_days。

販売数と価格の通貨：price はロシアルーブル（₽）で、currency で示されます。totalSales は期間内の販売個数、dailySales は1日あたりの平均販売個数、totalRevenue は期間内の売上高です。

出品期間：upTime は出品時刻（ミリ秒）です。upDays / upMonths は、日数／月数で表した出品期間です。

パラメーター

パラメーター	型	必須	説明
sku	string	はい	Ozon 商品の SKU（例：175924376）。ほかの Seerfar Ozon ツールが返すものと同じ sku です。
dateRange	string	いいえ	販売数／指標の対象期間。デフォルトは past_30_days です。次のいずれか：past_7_days、past_30_days、past_60_days、past_90_days、past_180_days、past_365_days。
uId	string	いいえ	ユーザー ID。
memberId	string	いいえ	メンバー ID（データの帰属先）。

必須なのは sku のみです。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-product-detail-search-<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. 商品のデフォルト設定による 30 日間の詳細

{"sku": "175924376"}

2. 直近 7 日間（最近の勢い）

{"sku": "175924376", "dateRange": "past_7_days"}

3. 直近 90 日間（四半期のトレンド）

{"sku": "175924376", "dateRange": "past_90_days"}

4. 1 年間（ライフサイクルの確認）

{"sku": "175924376", "dateRange": "past_365_days"}

クエリの作成方法

1. まず SKU を特定します：ユーザーが SKU ではなく商品名、URL、ショップを指定した場合は、このスキルを呼び出す前に、一覧レベルの Seerfar Ozon ソース（ショップ検索／キーワード逆引き検索／カテゴリー検索／マーケットキーワード検索）から sku を取得します。
2. 意図に応じて dateRange を選びます：最近の勢いや現在の在庫を確認する場合は短い期間（past_7_days／past_30_days）、ライフサイクル、季節性、ランキングの安定性を確認する場合は長い期間（past_90_days／past_180_days／past_365_days）を選びます。
3. 集計値を確認してから推移を見ます：まずトップレベルの totalSales／dailySales／totalRevenue／stock／categoryRanks でスナップショットを確認し、次に salesTrendVOList で日次データを詳しく調べます。
4. 1 回の呼び出しにつき SKU は 1 つです：このエンドポイントが受け取る sku は 1 つです。商品を比較する場合は、SKU ごとに呼び出してください。

表示ルール

1. データのみを提示します：主観的なアドバイスは加えず、商品指標をわかりやすいレイアウトで表示します。
2. 商品情報とスナップショットを先に表示します：title、sku、price（₽）、reviewRating（reviewCount 件のレビュー、questionsAndAnswers 件の Q&A）、続いて販売スナップショット（totalSales、dailySales、totalRevenue、stock）と期間（startDate–endDate）を表示します。
3. カテゴリーランキング：categoryRanks は月ごとのランキング履歴（{date, rank, count}）です。カテゴリー名は含まれないため、ランキング履歴と合わせて categoryInfo のカテゴリー階層（titlePath／cnTitlePath）を表示します。
4. 販売推移：salesTrendVOList は日次データ（{date, sales, revenue, price, stock, reviewCount, reviewRating}）です。すべての行をそのまま表示するのではなく、ピーク日と推移の方向を要約し、全データについては保存済みファイルを案内します。sales: 0 の日がある場合、データ欠損ではなく販売なしとして扱います。
5. 販売者とブランド：ユーザーが販売者／ブランドを確認できるよう、sellerName（sellerId — 負の値は Ozon のプラットフォーム販売者を意味します）と brandName（brandId）を表示します。
6. フルフィルメント：fulfillment は配列です（例：["FBO"]、プラットフォーム販売商品の場合は ["OZON"]）。複数の値は / で連結します。
7. 掲載期間：upTime は日付（ミリ秒タイムスタンプ）として、upDays／upMonths と合わせて表示します。
8. 条件付きフィールド：weight（物理商品のみ）と grossMargin はスキーマで定義されていますが、一部の商品（デジタル商品や Ozon プラットフォーム販売者など）では存在しません。欠落している場合はエラーにせず - を表示します。monthlySalesUnits／monthlySalesRevenue は期間内の totalSales／totalRevenue と同じ値なので、そのまま参照できます。
9. 結果が空の場合：存在しない sku に対しては、成功として total:0 と空の products が返されます。システムエラーと報告するのではなく、SKU が誤っている可能性があることをユーザーに伝えます。
10. エラー処理：code が "200" ではない場合（または errcode が 200 ではない場合）、msg／errmsg に基づいて説明し、修正方法（SKU の確認、レート制限時の再試行）を提案します。

重要な制限事項

• sku は必須です。省略するとパラメーターエラーが返されます。
• 単一 SKU のエンドポイントです：1 商品の詳細を返します。一括取得／一覧取得には対応していません。商品を比較するには、SKU ごとに呼び出してください。
• dateRange が影響するのは販売集計値と推移のみです：商品メタデータ（タイトル、価格、評価、ブランド、販売者、重量、フルフィルメント）は期間指定のない、ある時点のスナップショットです。
• 条件付きフィールド：weight（物理商品のみ）と grossMargin はスキーマで定義されていますが、常に返されるとは限りません。デジタル商品／Ozon プラットフォーム販売者の場合は存在しません。monthlySalesUnits／monthlySalesRevenue は返され、期間内の totalSales／totalRevenue と同じ値です。
• 販売数／売上は、選択した期間における Seerfar のモデル推定値であり、Ozon の公式数値ではありません。
• total は返されたレコード数を示します（SKU が見つかった場合は 1）。カタログ全体の件数ではありません。

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

該当する場合 — Ozon の商品を1つ詳しく調べる場合：

ユーザーの発言	シナリオ
「この Ozon 商品の詳細を確認して」／「この SKU のデータ」	単一商品の詳細
「この競合商品は最近30日間でいくつ売れた？」／「1日あたりの平均販売数は？」	販売スナップショット（totalSales／dailySales）
「この商品の売上高はいくら？」	売上高（totalRevenue）
「この商品の在庫はいくつ？」	在庫確認（stock）
「この商品はカテゴリー内で何位？」	カテゴリーランキング（categoryRanks）
「この商品の最近の販売傾向は？」／「最も売れた日はいつ？」	日次販売傾向（salesTrendVOList）
「この商品はどこの会社のもの？／どのブランド？」	販売者＋ブランド（sellerName／brandName）
「この商品が出品されてからどれくらい経つ？」	出品期間（upDays／upMonths）

該当しない場合 — 1つの商品詳細を超える情報が必要な場合：

• ショップの商品カタログ全体 → Seerfar Ozon のショップ検索スキルを使用してください。
• Ozon のキーワードの発見 → 市場キーワード検索／キーワードマイニング／キーワード逆検索を使用してください。
• カテゴリーツリーの閲覧 → カテゴリー検索を使用してください。
• 複数商品の概要を一度に取得 → SKU ごとにこのスキルを呼び出すか、出品レベルの情報源を使用してください。

利用範囲の判断：ユーザーが特定の Ozon SKU をすでに把握している（または出品レベルの情報源から取得した）うえで、その商品の販売数、売上高、在庫、カテゴリーランキング、傾向、ブランド、販売者などの指標全体を知りたい場合は、ここから始めてください。商品、キーワード、ショップを見つけたい場合は、まず対応する Seerfar Ozon スキルに案内してください。

算力の消費ルール

算力を5消費します。

ユーザーは算力の消費に対して料金を支払います。十分に検討してください。このスキルを高頻度で呼び出す必要がある場合、またはユーザーが算力の消費量を正確に把握していない場合は、必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

次のいずれかに該当する場合は、フィードバック API を通じてフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能や目的が実際の動作と一致しない
2. スキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルに対する不満または称賛を表明した
4. 改善できると思われる点がある

references/api.md に記載された方法でフィードバック API を呼び出してください。ユーザーの操作を妨げないでください。

---

高品質で専門的な越境ECスキルをさらに利用するには、LinkFox Skillsを設定してください。