linkfox-seerfar-ozon-shop-search

Seerfar Ozon ショップ検索

このスキルは、Seerfar の分析データベースから、特定の Ozon ショップ（販売者）の商品を一覧表示します。ショップの id を指定すると、各商品の過去30日間の販売数、価格、評価、重量、フルフィルメントモデル（FBO/FBS）、販売者の種類（国内／越境）、返品・キャンセル率に加えて、ショップ全体の過去30日間の販売数を返します。競合ショップの商品分析、ベストセラーの特定、販売者カタログの詳細分析の出発点となります。

主な概念

データの単位は商品で、1つのショップに限定されます：ショップの id を1つ指定すると、そのショップの商品カタログとパフォーマンス指標が返されます。これは「ショップ単位」の表示であり、キーワードやカテゴリー単位の表示ではありません。

ショップの id の取得元：id は Seerfar の販売者／ショップ識別子であり、他の Seerfar Ozon ツール（商品レポート／商品詳細検索など）が返す sellerId と同じものです。負の ID（例：-2 Ozon Express、-4 Ozon Fresh）は Ozon のプラットフォーム自身の販売者で、正の ID はサードパーティの販売者です。ユーザーがショップ名または商品しか把握していない場合は、まず商品レベルの Seerfar Ozon ソースから sellerId を取得してから、このスキルを呼び出してください。

販売者の種類：各商品には sellerType が含まれます。0 は国内（本土）、1 は越境（跨境）です。通常、ショップの商品はすべて同じ種類です。これを使って、競合が国内販売者か越境販売者かを判断できます。

販売数と価格の通貨：sales／monthlySalesUnits は過去30日間の販売個数です。price はロシアルーブル（₽）で、通貨は currency に示されます。

パラメーター

パラメーター	型	必須	説明
id	integer	はい	ショップ（販売者）ID。ほかの Seerfar Ozon ツールが返す sellerId です。負の値は Ozon のプラットフォーム販売者を示します。
page	object	はい	ページネーション {page, pageSize, orders[]}。
page.page	integer	いいえ	ページ番号。1から始まり、デフォルトは1です。
page.pageSize	integer	いいえ	ページサイズ。デフォルトは20です。最大20。これを超える値は拒否されます（errcode 1002）。
page.orders	array	いいえ	並べ替えルール。要素は {field, direction} で、direction は DESC／ASC です。一般的なフィールド：sales、price、reviewRating、upTime。
uId	string	いいえ	ユーザー ID。
memberId	string	いいえ	メンバー ID（データの帰属先）。

必須なのは id と page のみです。

呼び出し方法

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

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

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

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

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

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

異常な状態

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

使用例

1. ショップのベストセラー（過去30日間の販売数順）

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. ショップの新着商品（掲載時刻順）

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "upTime", "direction": "DESC"}]}}

3. ショップの高価格商品

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. ショップの商品カタログをさらにページ送りして表示

{"id": 1362816, "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

クエリの作成方法

1. 常に page.orders を渡してください：カタログは大規模な場合があります。重視する指標で並べ替えてください（ベストセラーは sales DESC、新着商品は upTime DESC、高価格帯の SKU は price DESC）。
2. pageSize は 20 以下にしてください：ゲートウェイがページサイズを 20 に制限しています。ページ分割には page.page を使用し、次のページがあるかどうかは hasNextPage で確認してください。
3. 先にショップの id を特定してください：ユーザーが id ではなくショップ名または商品名を指定した場合は、このスキルを呼び出す前に、商品レベルの Seerfar Ozon ソースから sellerId を取得してください。
4. コンテキストにはショップ単位の集計値を使用してください：totalSales ／ totalRevenue ／ dailySales はショップ全体の合計値（ページに関係なく一定）で、productCount はカタログ全体の商品数、rating はショップの評価、最上位の fulfillment は FBO/FBS の内訳です。いずれもショップ全体の状態をすばやく把握するための指標です。

表示ルール

1. データのみを提示してください：主観的なアドバイスは添えず、ショップの商品指標をわかりやすい表で表示してください。
2. ショップの情報を先に示し、その後に商品列を表示してください：まずショップ単位の集計値（totalSales（30 日間の合計）、totalRevenue（総売上高、₽）、productCount（カタログ内の商品数）、dailySales、rating、fulfillment の内訳（例：FBO 72 / FBS 4））を示し、次に sku、price、sales、reviewRating、weight、sellerType、fulfillment、returnCancellationRate の表を表示してください。
3. 販売者タイプのラベル：sellerType は国内／越境（0/1）として表示し、ユーザーが一目でわかるようにしてください。
4. フルフィルメント：fulfillment は配列です（例：["FBO"]）。複数の値は / で連結してください。
5. returnCancellationRate がない場合：Ozon プラットフォームの販売者（負の id）ではこのフィールドが欠落していることがよくあります。エラーにせず - と表示してください。
6. ページネーションの案内：hasNextPage が true の場合は、page.page を指定して次のページを取得できることをユーザーに伝えてください。また、pageSize の上限が 20 であることも案内してください。
7. ショップが空の場合：存在しない id を指定すると、total=0 でデータなしの成功応答が返されます。システムエラーとして報告するのではなく、id が間違っている可能性があることをユーザーに伝えてください。
8. エラー処理：code が "200" でない場合（または errcode が 200 でない場合）は、msg ／ errmsg に記載された理由を説明し、修正方法（page の追加、pageSize の引き下げ、レート制限時の再試行）を提案してください。

重要な制限事項

• id と page はどちらも必須です。どちらかを省略すると errcode 400 が返されます。
• pageSize の上限は 20 です：上限を超えると errcode 1002 が返されます。
• total はページ内の行数であり、ショップのカタログ全体の商品数ではありません。さらにページを取得するかどうかは hasNextPage で判断してください。
• テキスト／キーワードによるフィルターはありません：このエンドポイントでの絞り込みはショップ単位のみです。ショップ名からショップを検索する場合は、先に別の Seerfar Ozon ソースを使用してください。
• 販売者タイプによるフィールドの差異：returnCancellationRate はサードパーティ販売者には設定されていますが、Ozon プラットフォームの販売者（負の id）では欠落していることがよくあります。スキーマで定義されている productPageUrl、monthlySalesRevenue、brand は返されません（上流にデータソースがないため、null ではなく省略されます）。

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

該当するケース — 1つの Ozon ショップ／販売者の商品カタログを分析する場合：

ユーザーの発言	シナリオ
「この Ozon ショップの商品を分析して」／「この販売者は何を販売していますか」	ショップの商品カタログ
「このショップで最も売れている商品は何ですか」	ベストセラーの抽出（販売数で並べ替え）
「このショップでは最近どんな新商品が発売されましたか」	新着商品（upTime で並べ替え）
「この競合ショップの価格帯／客単価を教えて」	価格帯分析（価格で並べ替え）
「このショップは国内販売者ですか、それとも越境販売者ですか」	販売者タイプの確認（sellerType）
「このショップの総販売数はいくつですか」	ショップの状況（totalSales）

該当しないケース — 1つのショップの商品カタログの範囲を超える場合：

• 市場指標から Ozon のキーワードを見つける → Seerfar Ozon の市場キーワード検索スキルを使用してください。
• 1つの商品について詳しい情報を取得する → 商品単位の Seerfar Ozon ソースを使用してください（このスキルで取得できるのはカタログレベルのフィールドのみです）。
• カテゴリーツリーを閲覧する → カテゴリーレベルの Seerfar Ozon ソースを使用してください。
• 特定の商品を販売しているショップを見つける → まず商品レベルの Seerfar Ozon ソースを使って sellerId を取得してください。

適用範囲の判断：ユーザーがすでにショップ／販売者 ID（または商品検索で取得した sellerId）を持っており、そのショップの商品を販売数／価格／評価で列挙またはランキングしたい場合は、ここから始めてください。市場レベルでのキーワード検索や、1つの商品について詳細情報を求めている場合は、該当する Seerfar Ozon スキルに案内してください。

計算リソース消費ルール

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

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

フィードバック：

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

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

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

---

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