linkfox-amazon-store-report

Amazon 店铺报告获取

本 skill 提供 亚马逊卖家后台报告的端到端自动化获取：请求 → 轮询 → 下载 → 解压 → 预览。支持 95+ 种报告类型（库存 / 订单 / 销售 / 财务 / FBA / 退货 / Brand Analytics 等）。

---

⚠️ Prerequisites — MUST READ FIRST

本 skill 依赖 linkfox-amazon-store-auth（授权与店铺/令牌管理）。

🛑 如果 linkfox-amazon-store-auth 未安装 / 未加载，请先安装它，再回到本 skill。

怎样判断 linkfox-amazon-store-auth 是否可用

在执行任何报告任务之前，agent 必须先进行依赖检查：

1. 读取下列任一路径（skill 加载路径取决于运行环境；scripts/check_auth_dependency.py 会按相同规则自动探测）：
   • 仓库 / 通用扁平目录：<skills_dir>/linkfox-amazon-store-auth/SKILL.md
   • Claude：~/.claude/skills/linkfox-amazon-store-auth/SKILL.md
   • Cursor：~/.cursor/skills/...、~/.cursor/skills-cursor/...
   • OpenClaw：<OPENCLAW_WORKSPACE>/skills/...、~/.openclaw/skills/...、~/.agents/skills/...（与 OpenClaw Skills 文档 的常见路径一致）
   • Hermes Agent：~/.hermes/skills/<category>/linkfox-amazon-store-auth/SKILL.md，以及 ~/.hermes/plugins/<plugin>/skills/linkfox-amazon-store-auth/SKILL.md（与 Hermes Skills 文档 的布局一致）
2. 或直接运行脚本：python scripts/check_auth_dependency.py，脚本会在缺失时以 exit code 42 退出，并在 stderr 输出结构化提示（以 DEPENDENCY_MISSING: 开头）。脚本已内置 OpenClaw / Hermes 路径判断；若在 Hermes 的 config.yaml 里配置了 skills.external_dirs，请设置环境变量 HERMES_SKILLS_EXTERNAL_DIRS（使用系统路径分隔符串联多个目录）以便探测。
3. 如果上述检查全部失败，则判定为 linkfox-amazon-store-auth 未安装。

发现未安装时的标准处置

当检测到 linkfox-amazon-store-auth 未安装时，agent 必须按以下顺序执行：

1. 尝试自动安装（优先）：
   • 如果当前运行时具备 skill 安装工具（例如 skill 市场 / skill 管理 MCP / install_skill 类工具），立即调用安装 linkfox-amazon-store-auth。
   • 安装成功后，重新加载并从头执行本 skill。
2. 引导用户手动安装（兜底）：
   • 向用户说明：「本技能依赖 linkfox-amazon-store-auth，尚未安装。请前往 LinkFox Skills 安装该 skill，安装完成后告诉我一声，我会继续为你拉取报告。」
   • 不要绕过依赖直接去调 /spApi/authorizeUrl、/spApi/storeTokens、/spApi/authorizedStores 等接口——这些接口的选店铺、令牌流程属于 linkfox-amazon-store-auth 的职责，本 skill 只负责报告业务本身。
3. 不得静默降级：如果既无法自动安装也未获得用户确认，必须停止执行并把依赖缺失的事实回报给用户，不要擅自尝试替代方案。

依赖已满足后的协作方式

• 本 skill 依赖 auth 选店（sellerId+region），直接经 /spApi/developerProxy 执行报告生命周期（服务端解析 token）。
• 授权、授权的前置选店铺、令牌刷新等操作——交由 linkfox-amazon-store-auth；本 skill 不重复做这些事。

---

Core Concepts

• Report Type（报告类型）：亚马逊官方报告类型枚举，例如 GET_MERCHANT_LISTINGS_ALL_DATA、GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL。完整列表见 references/report-types.md。
• Marketplace ID：区域内具体站点 ID，例如 US = ATVPDKIKX0DER。
• Report lifecycle：请求报告 → 轮询 processingStatus（IN_QUEUE / IN_PROGRESS / DONE / FATAL / CANCELLED）→ DONE 后拿到 reportDocumentId → 取下载 URL → 下载（多为 gzip TSV）→ 解压。
• Rate limits：Reports API 约 0.0222 req/s；轮询需保留间隔（默认 30s）。

Data Fields

Report Request Input

Field	Type	Required	Description
sellerId	string	Yes	已授权的 Amazon Seller ID
region	string	Yes	NA / EU / FE
reportType	string	Yes	报告类型枚举值
marketplaceIds	array	Yes	目标 marketplace ID 列表
dataStartTime	string	No	ISO 8601，报告起始时间
dataEndTime	string	No	ISO 8601，报告结束时间
lastUpdatedDate	string	No	部分 Vendor 报告必填，见 references/report-requests/ 对应 md
reportOptions	object	No	如 Brand Analytics 的 reportPeriod、asin/asins；销售流量的 dateGranularity/asinGranularity 等。每一 reportType 说明：references/report-requests/types/<REPORT_TYPE>.md（索引 types/README.md）；有 JSON Schema 的另见 report-requests/README.md
pollInterval	int	No	轮询间隔秒数（默认 30）
maxAttempts	int	No	最大轮询次数（默认 20）

レポート出力

フィールド	型	説明
reportId	string	レポートリクエスト ID
reportDocumentId	string	レポートドキュメント ID
downloadPath	string	ローカルにダウンロードした後の絶対パス（解凍済み、ファイル名を含む）
fileName	string	保存するファイル名（downloadPath の末尾と一致）
localFileUri	string	クライアントがローカルファイルを開く際に便利な、ローカルマシンの file:// URI
extractedFileHttpUrl	string	ブラウザーで解凍済みファイルをダウンロードするためのローカルマシン上の一時 HTTP 直リンク（デフォルトで serveExtractedFileHttp は有効）
extractedFileHttpServeSeconds	int	ローカル HTTP サービスの稼働時間（デフォルト 300、最小 10）
extractedFileHttpNote	string	このリンクはローカルマシン限定で、有効期限があることを示す説明
amazonDownloadUrl	string	（任意）includeAmazonSourceUrl: true の場合のみ表示：Amazon の元の URL。通常は圧縮ファイルで、一般ユーザーに渡す必要は通常ありません
compressionAlgorithm	string	API が圧縮アルゴリズムを返した場合に含まれます（例：GZIP）
tempDirectory	string	一時ディレクトリ
fileSize	int	ファイルサイズ（バイト）

呼び出し方法

• API エンドポイント：POST /spApi/developerProxy（操作はリクエスト本文で区別します。パラメーター、レスポンス、エラーコードの全一覧は references/api.md を参照してください）
• Python スクリプト：python scripts/<脚本名>.py '<JSON 参数>' [--inline]（利用可能なスクリプトは以下のスクリプト一覧を参照してください）
• コストに関する制約：このツールは計算リソースを消費します。失敗または結果が空の場合、自動的にキーワードを変更したり、ページをめくったり、連続して試行したりしてはいけません。検索を続ける必要がある場合は、追加の消費が発生することを先にユーザーに説明してください。

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<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 または ConvertFrom-Json を使って必要なデータを抽出し、JSON 全体がコンテキストに入るのを避けてください。

利用可能なスクリプト

• scripts/get_report.py ⭐ — レポート取得をエンドツーエンドで自動化（推奨）
• scripts/check_auth_dependency.py — 依存する skill linkfox-amazon-store-auth がインストール済みかどうかを事前に確認します

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

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

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY と LINKFOXAGENT_API_KEY のどちらも設定されていません。
• レスポンスのステータスコードが 401 または 402
• レスポンスに計算リソースまたは残高の不足が示される：メッセージに「計算リソース残高不足／課金不足／残高不足／quota exceeded／insufficient balance／プランの有効期限切れ／チャージが必要／チャージしてください」、または同様の意味の内容が含まれています。

使用シナリオ

シナリオ 0：依存関係の確認（最初に必ず実行）

この skill を開くたびに、まずこの手順を実行してください。

1. linkfox-amazon-store-auth/SKILL.md を読み取ってみます（ツールが許可する場合）
2. または次を実行します：

   python scripts/check_auth_dependency.py
   

3. 終了コードが 0 以外、または stderr に DEPENDENCY_MISSING: が含まれる場合は、上記の「未インストールが見つかった場合の標準的な対応」手順に従ってください
4. 依存関係が満たされたら、通常の業務シナリオに進みます

シナリオ 1：Amazon レポートを取得（自動化、推奨）

ユーザーのリクエスト：「在庫レポートを取得したい」／「注文レポートを取得」／「販売トラフィックレポートをダウンロード」など

手順：

1. 依存関係の確認（シナリオ 0）
2. 事前にストアを選択：linkfox-amazon-store-auth に委任します
   • /spApi/authorizedStores を呼び出してユーザーにストアを選択してもらい、sellerId と region を確定します
   • raw token を取得するために /spApi/storeTokens を先に呼び出してはいけません。スクリプトはセレクターを使って developerProxy 経由で直接渡します
3. レポートの種類を特定：ユーザーの要望に基づいて reportType を照合します
   • 在庫：GET_MERCHANT_LISTINGS_ALL_DATA、GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA
   • 注文：GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL
   • 販売トラフィック：GET_SALES_AND_TRAFFIC_REPORT
   • 財務：GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE
   • 全一覧：references/report-types.md
4. スクリプトを実行します：

   python scripts/get_report.py '{
     "sellerId": "A1EC6SZ7XAMURH",
     "region": "NA",
     "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
     "marketplaceIds": ["ATVPDKIKX0DER"]
   }'
   

5. スクリプトは次の処理を自動的に行います：sellerId と region を使って developerProxy を呼び出す（サーバー側で token を解析）→ レポートをリクエスト → ポーリング → ダウンロード → 解凍 → プレビュー → JSON を出力。完了後、stderr と JSON にローカルの絶対パス（downloadPath）とローカルマシンの file URI（localFileUri）を出力し、デフォルトで短時間のローカル HTTP サービスを起動して、同じマシンのブラウザーで解凍済みファイルをダウンロードするための extractedFileHttpUrl を生成します。ユーザーに表示する際は、少なくとも extractedFileHttpUrl、downloadPath、fileName を提示してください。スクリプトは serveSeconds の経過後にサービスを停止するため、リンクはその時点で無効になります。Amazon の元の URL（多くは圧縮ファイル）が必要な場合は、デバッグ時のみ includeAmazonSourceUrl: true を設定してください。

シナリオ 2：レポートの手動取得（上級）

細かな制御が必要なシナリオでは、/spApi/developerProxy を使って手動で操作できます。

1. 既存のレポートを取得（より高速）：

   path: reports/2021-06-30/reports
   method: GET
   queryString: reportTypes=<type>&marketplaceIds=<ids>
   

2. 新しいレポートを作成：

   path: reports/2021-06-30/reports
   method: POST
   body: {"reportType": "...", "marketplaceIds": [...]}
   

3. ステータスを確認：

   path: reports/2021-06-30/reports/{reportId}
   method: GET
   

4. ダウンロードリンクを取得：

   path: reports/2021-06-30/documents/{reportDocumentId}
   method: GET
   

シナリオ 3：カスタム日付範囲／ポーリング

python scripts/get_report.py '{
  "sellerId": "A1EC6SZ7XAMURH",
  "region": "NA",
  "reportType": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
  "marketplaceIds": ["ATVPDKIKX0DER"],
  "dataStartTime": "2024-01-01T00:00:00Z",
  "dataEndTime": "2024-01-31T23:59:59Z",
  "pollInterval": 15,
  "maxAttempts": 40
}'

リージョン別マーケットプレイス ID

リージョン	国	マーケットプレイス ID
NA	United States	ATVPDKIKX0DER
NA	Canada	A2EUQ1WTGCTBG2
NA	Mexico	A1AM78C64UM0Y8
EU	United Kingdom	A1F83G8C2ARO7P
EU	Germany	A1PA6795UKMFR9
FE	Japan	A1VC38T7YXB528

その他のマーケットプレイス ID については、references/report-types.md を参照してください。

表示ルール

1. 依存関係を先に、業務を後に：依存関係の確認が完了するまでは、レポート関連の呼び出しを開始してはいけません。
2. データのみを表示：レポート取得の進捗、ダウンロードパス、冒頭数行のプレビューを表示します。業務上の解釈は行いません。
3. ユーザーが選択したレポートタイプを尊重：ユーザーがレポートタイプを指定した場合は、そのタイプのみを取得します。勝手に別のタイプへ切り替えてはいけません。
4. エラーを明確に伝える：レポート取得に失敗した場合（FATAL／403 など）は、原因を説明し、次の判断をユーザーに委ねます。
5. 安全性：raw token を出力または伝達しません。業務では sellerId+region のみを使用します。
6. 完了後にアドレスとローカルダウンロードリンクを表示：スクリプトが正常終了したら、extractedFileHttpUrl（解凍済みファイルのローカル HTTP ダウンロードリンク、有効期限あり）、downloadPath（ローカルの絶対パス）、fileName（ファイル名）、および localFileUri を必ずユーザーに知らせます。また、「スクリプトを実行した同じコンピューターでのみ、サービスが稼働している間は利用できます」と説明します。Amazon の元の URL をユーザーのダウンロード先として既定で使用してはいけません。includeAmazonSourceUrl を使用するのは、ユーザーから明示的に求められた場合、またはトラブルシューティングが必要な場合に限ります。

重要：レポート取得失敗時の対応ルール

• ユーザーが指定したレポートの取得に失敗した場合、別のレポートタイプを自動的に試してはいけません。
• レポート取得に失敗した場合（FATAL、403 など）は、ただちに停止し、失敗した事実をユーザーに伝えてください。
• どのレポートを取得するかをユーザーに代わって決めてはいけません。
• 失敗原因を明確に伝え、次の対応（再試行／別のタイプへの変更／権限の確認など）はユーザーに判断してもらいます。
• 例：GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT の取得に失敗しても、GET_MERCHANT_LISTINGS_ALL_DATA を自動的に取得してはいけません。

よくあるレポート取得失敗の原因

• 403 Unauthorized：API 権限がない、または Amazon Brand Registry に登録されていない
• FATAL：このレポートタイプが当該ストアでサポートされていない、またはデータが不足している
• Brand Analytics 系のレポートにはブランド登録が必要です
• Vendor 系のレポートは Vendor アカウントに限られます

重要な制限事項

• linkfox-amazon-store-auth に依存します：インストールされていない場合は、必ず先にインストールしてください。Prerequisites を参照してください。
• トークンの有効期限：サーバー側のトークンは約 1 時間で期限切れになります。developerProxy は sellerId+region に基づいて自動的に解決／更新できます。期限切れの場合は、auth skill の refreshToken を介してから再試行することもできます。
• レート制限：Reports API は 0.0222 req/s です。既定の 30s ポーリングは安全な間隔です。
• レポートの生成時間：一部の財務レポートは 10～30 分かかる場合があります。必要に応じて maxAttempts を増やしてください。
• パスの許可リスト：バックエンドの sp-api.developer-proxy.allowed-path-prefixes で reports/2021-06-30/reports を許可する必要があります。

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

該当する — レポート取得のシナリオ：

ユーザーの発言	シナリオ
「Amazon の在庫レポートを取得して」／「在庫レポートを取得して」	シナリオ 1
「注文データをダウンロードして」／「注文レポートをダウンロードして」	シナリオ 1
「販売・トラフィックレポートを取得して」／「販売・トラフィックレポート」	シナリオ 1
「決済レポートを取得して」／「決済レポート」	シナリオ 1
「FBA 在庫を確認して」／「FBA 在庫レポート」	シナリオ 1
「指定期間の注文レポートを取得して」／「2024-01-01 からの注文」	シナリオ 3

該当しない — この skill の対象外：

• 新しいストアの認可、認可済みストアの一覧表示、トークンの更新／確認 → linkfox-amazon-store-auth を使用してください
• 商品 listing の管理、注文処理、広告配信 → 他の skill が担当します

範囲の判断：

• この skill が担当するのは「依存関係の確認＋レポート取得業務」のみです。認可／トークンは依存 skill の担当です。
• この skill に入る呼び出しは、すべて最初にシナリオ 0 を実行する必要があります。

---

Amazon SP-API のインターフェース保護と再試行ガイド

同じストアで Amazon SP-API から 400、403、404、または 429 が連続して返されると、ゲートウェイは 450、453、454、または 459 を返し、短時間のクールダウンに入ります。これらのカスタムステータスコードは Amazon 本来のステータスではなく、アカウント停止を意味するものでもありません。異常なリクエストや高頻度の呼び出しが続いてストアのリスクが高まるのを防ぐためのものです。

ステータスと message	範囲	発生条件とクールダウン	対応
450：400，请求异常，请优化您的参数	ストア＋インターフェース	60 秒以内に 3 回超：5 分間；10 分以内に 4 回超：20 分間	同じパラメーターでの再試行を停止し、必須フィールド、marketplace、ID、日付、リクエスト本文を確認します
453：403，店铺未授权，请先授权	ストアの全インターフェース	60 秒以内に 2 回超：5 分間；10 分以内に 4 回超：30 分間	このストアへの呼び出しを停止し、認可、権限、ストアの所有関係、リージョンを確認します
454：404，资源不存在，请优化您的参数	ストア＋インターフェース	60 秒以内に 3 回超：5 分間；10 分以内に 4 回超：30 分間	リソース ID、対象のストア／サイト、リソースの状態、インターフェースパスを確認します
459：429限流中，请降低频率	ストア＋インターフェース	初回：15 秒間；2 分以内に 2 回超：30 秒間；3 分以内に 4 回超：2 分間	並列数、ページネーション、ポーリング頻度を下げ、段階的にバックオフします

• 自動または並列の再試行をただちに停止してください。保護を回避するために、別のスクリプトを使ったり、タスクを重複して作成したりしてはいけません。まず retryAfter と blockedUntil に従い、これらがない場合は表に記載された時間を適用してください。
• 450／453／454 の場合は、パラメーター、認可、またはリソース識別子を修正してからクールダウン後に、慎重に最大 1 回だけ再試行してください。再び発生した場合は呼び出しを停止します。453 の間は、そのストアに対するすべての SP-API 呼び出しを停止してください。
• 既存の reportId、feedId などのタスク ID は保持してください。書き込み操作の結果が不明な場合は、直接再実行せず、まず状態を確認してください。
• まずストア保護についてユーザーに説明し、そのうえで原因、対応、待機時間を伝えてください。次のように返信できます：「お客様の Amazon ストアを保護するため、Amazon SP-API から{原因}が連続して返されたことを検知し、現在、一時的な保護が有効になっています。まず{対応内容}を行い、約{待機時間}後に再度お試しください。これはアカウント停止を意味するものではなく、プランやコンピューティングリソースの制限でもありません。」「LinkFox のレート制限」や「サーバーがビジー状態」とだけ伝えてはいけません。

コンピューティングリソース消費のルール

コンピューティングリソースを消費しません。

フィードバック：

以下のいずれかに該当する場合は、Feedback API を自動的に呼び出して報告します。

1. この skill の機能説明と実際の動作が一致しない
2. 結果がユーザーの意図と一致しない
3. ユーザーが不満または称賛を表明した
4. その他、改善できる点があると判断した場合

references/api.md の仕様に従って Feedback API を呼び出し、ユーザーの主な操作を中断しないでください。

---

高品質なプロフェッショナル向け越境 EC skill をお探しの場合は、LinkFox Skills をご覧ください。