linkfox-seerfar-ozon-product-report-search

Seerfar Ozon 商品レポート検索

このスキルは、Seerfar Ozon 商品データベースを検索し、豊富なパフォーマンス指標（月間販売数、売上高、成長率、カート・注文コンバージョン率、価格、評価、レビュー、ブランド、販売者、フルフィルメントモデル、出品期間、粗利益率など）で商品を絞り込みます。返される各行には完全な商品レポートレコードが含まれているため、Ozon の商品選定（选品）、競合商品の分析、ベストセラーの発掘、価格・コンバージョン帯のスクリーニングを始める際の起点となります。

基本概念

データ単位はキーワードではなく商品です：このエンドポイントは、完全なレポート指標が付加された商品レベルの行（SKU ごとに 1 行）を返します。市場キーワードエンドポイントが検索語を返すのとは異なり、条件に合う「商品」を見つけられます。

商品スクリーナー／商品レポートです：キーワード・ブランド・販売者だけでなく、指標の範囲（{min, max}）で Ozon 商品データベースを絞り込みます。monthlySales の下限を高く、price の上限を低く設定すると、手頃な価格で販売数の多い商品を抽出できます。また、convToCartPdp の下限を高く、returnCancellationRate の上限を低く設定すると、コンバージョンの品質を条件にできます。sales の降順で並べ替えると、ベストセラーを発掘できます。

統合フィールドと元の重複フィールド：レスポンスには、同じ値を別々のキー名で保持する 6 組のエイリアスがあります。sku/productId、sales/monthlySalesUnits、revenue/monthlySalesRevenue、reviewRating/rating、brandName/brand、productUrl/productPageUrl です。どちらを参照してもかまいません。値が異なることは想定しないでください。

日付の意味：searchDate はデータの月を指定します。2026 年 3 月のデータには 2026-04-01 を指定します。省略した場合は過去 30 日間のデータが対象になります。販売数・売上高は、選択した期間に基づきます。

data と products は同一です：トップレベルの 2 つの配列には、同じ商品行が含まれます。total は条件に一致した件数です（例：フィルターなしの場合は約 2,780 万件、単一の SKU に絞り込んだ場合は 1 件）。

対象は Ozon のみです：sourceType は ozon に固定されています。fulfillment の値は OZON、FBO、FBS、RFBS、FBP です。

パラメーター

パラメーター	型	必須	説明
page	object	はい	ページネーション＋並べ替え：{page, pageSize, orders[]}。page は 1 から（デフォルトは 1）、pageSize のデフォルトは 20 です。orders[] = {field, direction}。direction は DESC／ASC です。
skus	array	いいえ	対象を限定する SKU のリスト（最大 10 件）。
keywords	array	いいえ	商品タイトルの絞り込みに使うキーワードのリスト。
categoryIds	array	いいえ	Seerfar カテゴリー ID のリスト。
sellerName	array	いいえ	販売者名のリスト。
brand	object	いいえ	{brandName: array<string>, type: int}。type：0 含める、1 除外する、2 ブランドなし。
fulfillment	array	いいえ	フルフィルメントの絞り込み：OZON／FBO／FBS／RFBS／FBP。
labels	array	いいえ	バッジの絞り込み：0 新着、1 正規品、2 ベストセラー。
creationDate	integer	いいえ	出品からの経過期間による絞り込み（月）：1／3／6／12／24。
variationsMerge	integer	いいえ	バリエーションを統合：0 しない、1 する。
searchDate	string	いいえ	データの日付 yyyy-MM-dd。デフォルトは過去 30 日間です。2026-04-01 → 2026 年 3 月。
tag	string	いいえ	タグの語句。
monthlySales	{min,max}	いいえ	月間販売数の範囲。
monthlySalesRate	{min,max}	いいえ	販売成長率の範囲（salesRate を絞り込みます）。
monthlyRevenue	{min,max}	いいえ	月間売上の範囲。
price	{min,max}	いいえ	価格の範囲（RUB）。
convToCartPdp	{min,max}	いいえ	カートへのコンバージョン率の範囲。
reviewRating	{min,max}	いいえ	評価の範囲。
reviewCount	{min,max}	いいえ	レビュー数の範囲。
questionsAndAnswers	{min,max}	いいえ	Q&A 件数の範囲。
variants	{min,max}	いいえ	バリエーション数の範囲。
drr	{min,max}	いいえ	広告費比率の範囲。
grossMargin	{min,max}	いいえ	粗利益率の範囲。
returnCancellationRate	{min,max}	いいえ	返品・キャンセル率の範囲。
weight	{min,max}	いいえ	重量の範囲（g）。
volume	{min,max}	いいえ	容積の範囲（L）。
uId / memberId	string	いいえ	ユーザー／メンバー ID（データ帰属用）。

すべての範囲フィルターは {min, max} オブジェクトです。いずれか一方、または両方の境界値を指定してください。必須なのは page のみです。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-product-report-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. 現在の売れ筋商品（販売数順に並べ替え）

{"page": {"page": 1, "pageSize": 10, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. ブルーオーシャン商品 — 販売数が多く、価格帯が低い商品

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}, "monthlySales": {"min": 5000}, "price": {"max": 500}}

3. カテゴリー内のベストセラー、FBO フルフィルメント

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}, "categoryIds": ["15621031_200000933_93182"], "fulfillment": ["FBO"], "labels": [2]}

4. 過去 30 日間の新規出品を成長率順に並べ替え

{"page": {"page": 1, "pageSize": 20, "orders": [{"field": "salesRate", "direction": "DESC"}]}, "creationDate": 1}

5. 特定の SKU を検索

{"page": {"page": 1, "pageSize": 10}, "skus": [2107989735]}

クエリの作成方法

1. page.ordersを先頭に設定する：データセットは非常に大規模（数千万件の製品）です。常に、重視する指標で並べ替えてください（ベストセラーは sales DESC、売上上昇中の製品は salesRate DESC、低価格帯の大量販売商品は price ASC、高評価商品は reviewRating DESC）。
2. 範囲フィルターを組み合わせて機会を見つける：monthlySalesに下限を設けてpriceに上限を設定するか、convToCartPdpに下限を設けてreturnCancellationRateを低く設定し、需要とリスクの両面で絞り込みます。
3. categoryIds／brand／sellerNameで対象を絞る：並べ替える前にニッチな対象へ絞り、上位の行が関連性の高いものになるようにします。
4. creationDateとlabelsで新たな需要を見つける：creationDate: 1（新着商品）とlabels: [2]（ベストセラーバッジ）を組み合わせると、急成長中の商品を見つけられます。
5. 適切なsearchDateを選ぶ：現在のトレンド（過去30日間）を調べる場合は省略します。月ごとの比較には、明示的な日付を指定します。

表示ルール

1. データのみを提示する：主観的なアドバイスを加えず、製品指標を分かりやすい表で表示します。
2. 製品情報の列を先に並べる：title、sku、price（₽）、sales、revenue、rating、reviewCount、続いてbrand／sellerName／fulfillmentを表示します。
3. 通貨：price／revenue／missedRevenueの単位はロシアルーブル（₽）です。桁の解釈を誤らないよう、通貨を表示してください。
4. 統合フィールドと生データの別名：統合フィールド（productId、monthlySalesUnits、monthlySalesRevenue、rating、brand、productPageUrl）を優先するか、生データのフィールドと同じ値であることを明記してください。独立した値であるかのように両方を表示しないでください。
5. 大量の結果：totalが大きい場合は、上位の行を表示し、以下の大容量レスポンスのパターンを使ってレスポンス全体を保存できること、またはpage.pageでページを進められることをユーザーに伝えます。
6. エラー処理：codeが200以外（またはerrcodeが200以外）の場合は、msg／errmsgから理由を説明し、フィルターの調整または再試行を提案します（レート制限は1003）。

重要な制限事項

• pageは必須です：pageのないペイロードは拒否されます。
• skusの上限：1回のリクエストにつき最大10件のSKUです。
• カテゴリIDは不透明な値です：categoryIdsには、人間が読めるカテゴリ名ではなく、カテゴリ検索で取得したSeerfarのカテゴリIDが必要です。
• 重複する別名の組み合わせ：6つのフィールドが生データと統合フィールドのキーで重複しています（「基本概念」を参照）。値は同じですが、キーは2つあります。
• totalは一致件数の合計です：フィルターがなければ数千万件に達する場合があります。むやみに全件を処理せず、常に並べ替えとページ分割を行ってください。
• レート制限：errcode 1003（「リクエストが多すぎます。しばらくしてからもう一度お試しください」）はスロットリングを意味します。pageSizeを小さくするのではなく、待ってから再試行してください。
• 並べ替えフィールド：有効なorders[].fieldの値は、レスポンスの指標フィールドです（例：sales、revenue、price、reviewRating、reviewCount、salesRate）。columns配列には、並べ替え可能なフィールドが示されます。

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

該当 — Ozonの製品レベルのスクリーニング：

ユーザーの発言	シナリオ
「Ozonの製品選定／販売数・売上高で商品を絞り込む」	製品スクリーナー（範囲フィルター＋並べ替え）
「Ozonの売れ筋商品／ベストセラー」	ベストセラーの抽出（labels:[2]または sales DESCで並べ替え）
「Ozonの上昇中の商品／新商品のヒット商品」	上昇中／新着の商品（creationDate:1、 salesRate DESCで並べ替え）
「Ozonの高転換率・低返品商品」	転換品質のスクリーニング（convToCartPdpの下限、returnCancellationRateの上限）
「Ozonの特定ブランド／販売者の商品実績」	ブランド／販売者フィルター＋並べ替え
「これらのSKUのレポートを確認」	skusによる検索

該当しない — 製品レベルのレポートを超えるデータが必要な場合：

• キーワードの市場データ（検索語、検索ボリューム）→ market-keyword-search。
• シードキーワードを使ったキーワードの拡張 → keyword-mining。
• 特定のショップの全商品カタログ → shop-search。
• カテゴリレベルの集計を含むカテゴリ商品 → category-search。
• 製品からキーワードを逆引き → keyword-back-search。
• Ozon以外のマーケットプレイス → 対象外です。

判断の目安：ユーザーが指標でOzonの商品を絞り込み、製品レベルのレポート行を確認したい場合は、ここから始めます。キーワードレベルの市場データ、単一ショップの商品カタログ、またはカテゴリ集計が必要な場合は、該当するSeerfar Ozonデータソースに振り分けます。

計算リソース消費ルール

計算リソースを15消費します。

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

フィードバック：

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

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

references/api.mdに記載されているとおりにFeedback APIを呼び出してください。ユーザーの作業を中断しないでください。

---

より高品質でプロフェッショナルな越境ECスキルを利用するには、LinkFox Skillsを設定してください。