linkfox-mpstats-ozon-product-detail

MPSTATS Ozon 商品詳細（単一 SKU）

このスキルは、MPSTATS 経由で Ozon（ロシア）の単一 SKU の完全な商品カードを取得します。返されるフィールドには、価格、Ozon カード価格、割引、評価、レビュー、在庫、月間販売数量、月間売上高、逸失利益、潜在売上高、初回掲載日、画像などが含まれます。

基本概念

単一 SKU の仕様：呼び出しごとに productId を必ず 1 つだけ渡してください。このスキルでは productIds の配列／リストは受け付けません。複数の SKU を扱う場合は、追加のクレジット消費についてユーザーに確認してから、SKU ごとに個別に呼び出してください。

SKU ごとのフルフィルメントモデル：各商品カードには deliveryScheme が含まれます。

• FBO — Ozon によるフルフィルメント（Ozon の倉庫に在庫）
• FBS — 出品者によるフルフィルメント（出品者が発送）

includeFbs: true を渡すと、FBS SKU と FBS 対象の指標がレスポンスに含まれます。false（または省略）の場合は、FBO 中心の結果になります。この切り替えはリクエスト全体に適用されます。

前期間との比較：カードには previousSalesUnits ／ previousRevenue が含まれます。これは [startDate, endDate] の直前にある同じ長さの期間の販売数と売上高です。追加の呼び出しを行わずに、前月比／期間比較の差分を算出できます。

売上ポテンシャル：revenuePotential は、対象期間の毎日 SKU の在庫があった場合に得られた可能性のある売上を予測します。これを monthlySalesRevenue と比較することで、lostProfit ／ lostProfitPercent とあわせて在庫切れによる機会損失を定量化できます。

日付範囲：startDate ／ endDate は、期間集計されるすべての指標の対象期間を定義します。選択できる最新の日付は昨日（T-1）です。当日および未来の日付は拒否されます。

パラメーター

パラメーター	型	必須	説明
productId	integer|string	はい	単一の Ozon SKU ID
startDate	string	いいえ	統計対象期間の開始日、YYYY-MM-DD。選択できる最新の日付は昨日です
endDate	string	いいえ	統計対象期間の終了日、YYYY-MM-DD。選択できる最新の日付は昨日です
includeFbs	boolean	いいえ	FBS データを含める場合は true、false は FBO のみ

呼び出し方法

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

出力方針（スクリプトの既定の動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mpstats-ozon-product-detail-<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. 単一 SKU の詳細

{"productId": 1786874757}

2. 期間を指定した単一 SKU の検索

{
  "productId": 1786874757,
  "startDate": "2025-03-01",
  "endDate": "2025-03-31",
  "includeFbs": true
}

3. FBO のみのスナップショット

{"productId": 1786874757, "includeFbs": false}

4. 上流で特定した SKU — 完全な商品カード

{"productId": <productId from mpstats-ozon-product-search>}

他の Ozon スキルとの連携方法

1. 検索 → 詳細：mpstats-ozon-product-search を使ってキーワード／ブランド／出品者から候補の productId を特定し、SKU を 1 つ選んで、その productId をここに渡すと、詳細な指標を取得できます。
2. 詳細とトレンドの使い分け：このエンドポイントは SKU ごとの期間集計です。単一 SKU の日ごとの時系列データを取得する場合は、mpstats-ozon-product-trend を使ってください。
3. 詳細とドリルダウンの使い分け：入力の切り口がブランド／カテゴリー／出品者（単一 SKU ではない）の場合は、brand-products ／ category-products ／ seller-products を優先してください。これらは、その切り口の SKU ごとの集計済み指標をすでに返します。

表示ルール

1. コンパクトな表 — productId、title、price、monthlySalesUnits、monthlySalesRevenue、rating、reviewCount、balance、deliveryScheme、firstDate を先頭に表示します。在庫切れの影響についてユーザーから質問された場合は、revenuePotential／lostProfit／lostProfitPercent も含めます。
2. 通貨 — Ozon のネイティブ通貨は RUB です。currency フィールドには通貨記号が含まれます。黙って別の通貨として表示しないでください。
3. 失敗時の処理 — レスポンスには successCount／failedCount／failures が含まれます。failedCount > 0 の場合は、失敗した productId を failures から取得してユーザーに提示し、黙って除外しないでください。
4. 期間比較 — 現在のフィールドと previous* フィールドの両方が存在する場合は、横並びまたは差分として表示します。単一期間の数値を「傾向」として報告しないでください。
5. 在庫ありの日と全日 — salesPerDayWithStock／dailySalesRevenueWithStock は、在庫があった日のみを対象にします。通常の salesPerDay／dailySalesRevenue とは区別してください。
6. 配送モデル — FBO と決めつけず、SKU ごとの deliveryScheme の値を優先してください。
7. ビジネス上の助言はしない — データを提示し、幅広い分析なしに「この SKU は販売する価値がある」と推測しないでください。

重要な制限事項

• 単一 SKU のみ入力可能 — productIds ではなく productId を渡してください。配列／リストは無効です。複数の SKU を扱う場合は、追加のクレジット消費を確認してから、SKU ごとに一度ずつ呼び出してください。
• Ozon のみ — このツールは Wildberries やその他のロシアのマーケットプレイスには対応していません。
• T-1 データ — endDate に今日または未来の日付を指定することはできません。
• FBS の対応状況 — 一部のカテゴリーでは FBS の対応範囲が限定的です。入力セットに FBS が多い場合、取得できるカード情報が少なくなることがあります。
• フィールドセットはブランド／セラー向けのものと異なります — このエンドポイントは brandId、country、category、minPrice／maxPrice／averagePrice、balanceFbs、frozenStocks、warehousesCount、daysInSite／daysInStock／turnoverDays、position／categoryPosition／revenueSharePercent、isFbs を返しません。これらが必要な場合は、brand-products／category-products／seller-products を使用してください。
• 翻訳なし — タイトルはロシア語で返されます。中国語／英語のユーザーに提示する場合は、必要に応じて翻訳してください。

ユーザーの表現とシナリオ早見表

対象 — SKU ごとの Ozon カード検索：

ユーザーの発言	シナリオ
"この SKU の Ozon の詳細を取得して"	単一カードの取得
"Ozon の SKU 1786874757 の価格／評価／在庫は？"	単一 SKU カード
"競合の Ozon 出品情報について、売上と評価を教えて"	競合カードの監査
"この SKU の FBO と FBO+FBS の指標を比較して"	フルフィルメントモデルの比較

対象外 — SKU ごとのカード情報を超える要件：

• キーワードによる検索 → mpstats-ozon-product-search を使用
• 1 つの SKU の日別時系列データ → mpstats-ozon-product-trend を使用
• URL を超える出品文、レビュー、画像の分析 → 対象外
• フィルターを使ったブランド／カテゴリー／セラーの詳細分析 → 該当する詳細分析スキルを使用

判断基準：ユーザーがすでに単一の SKU を持っており、売上／価格／在庫／評価を知りたい場合は、このスキルを使用します。複数の SKU が提示された場合は、追加のクレジット消費を確認してから、1 つずつ処理してください。SKU がまだない場合は、まず検索または詳細分析スキルに案内してください。

算力消耗ルール

動的ルールに基づいて課金されます：算力消耗 = 12。productId が空の場合は 0 を返します。

重要：このスキルのサービス料金は倍率に応じて動的に計算され、一度に大量の算力を消耗する可能性があります。必ずユーザーに注意を促し、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

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

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

references/api.md の指定に従って Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

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