linkfox-amazon-store-feeds

Amazon ストアの Feeds

このスキルは linkfox-amazon-store-auth などと同じ Amazon Store シリーズです。店舗の選択（sellerId+region）には linkfox-amazon-store-auth が必要です。sellerId+region を指定して POST /spApi/developerProxy を直接呼び出し、トークンはサーバー側で解析します（旧呼び出しとの互換性が必要な場合を除き、amzAccessToken は渡さないでください）。GET / POST / DELETE を転送します。

呼び出し方法

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

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

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-feeds-<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／プランの有効期限切れ／チャージが必要／チャージしてください」または類似の意味の内容が含まれています。

公式リファレンス一覧

機能	ドキュメント
createFeedDocument	createFeedDocument
getFeedDocument	getFeedDocument
createFeed	createFeed
getFeed	getFeed
getFeeds	getFeeds
cancelFeed	cancelFeed

---

前提条件

1. linkfox-amazon-store-auth が必要です。python scripts/check_auth_dependency.py を実行し、exit 42 の場合は先に認証スキルをインストールしてください。
2. アプリには Feeds 関連のロールが必要です。feedType はアップロードするファイル形式と一致させてください（Amazon Feed Type Values ドキュメントを参照）。

---

代表的なワークフロー

1. create_feed_document.py → feedDocumentId と url（アップロード先 URL）を取得します。
2. upload_feed_document.py → url に対して PUT で feed ファイルをアップロードします（developerProxy を経由しません）。
3. create_feed.py → inputFeedDocumentId、feedType、marketplaceIds を渡します。
4. get_feed.py／get_feeds.py → processingStatus（例：IN_QUEUE、IN_PROGRESS、DONE、FATAL）をポーリングします。
5. 処理完了後、get_feed_document.py を使用して resultFeedDocumentId に対応するドキュメントを取得します（返された URL を使って結果ファイルを別途ダウンロードします）。

---

現在の機能

機能	path	method	スクリプト
createFeedDocument	feeds/2021-06-30/documents	POST	create_feed_document.py
getFeedDocument	feeds/2021-06-30/documents/{feedDocumentId}	GET	get_feed_document.py
createFeed	feeds/2021-06-30/feeds	POST	create_feed.py
getFeed	feeds/2021-06-30/feeds/{feedId}	GET	get_feed.py
getFeeds	feeds/2021-06-30/feeds	GET	get_feeds.py
cancelFeed	feeds/2021-06-30/feeds/{feedId}	DELETE	cancel_feed.py
ドキュメント内容のアップロード	createFeedDocument が返す URL	PUT	upload_feed_document.py

共有モジュール：_spapi_feeds_common.py。

---

スクリプトの例

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/create_feed_document.py '{"sellerId":"A1...","region":"NA","contentType":"text/tab-separated-values; charset=UTF-8"}'

python scripts/upload_feed_document.py '{"uploadUrl":"<from createFeedDocument>","contentType":"text/tab-separated-values; charset=UTF-8","filePath":"./inventory.tsv"}'

python scripts/create_feed.py '{"sellerId":"A1...","region":"NA","feedType":"POST_FLAT_FILE_INVLOADER_DATA","marketplaceIds":["ATVPDKIKX0DER"],"inputFeedDocumentId":"<feedDocumentId>"}'

---

表示ルール

1. まず developerProxy.errcode / httpStatus を確認してください。createFeedDocument は通常 201、createFeed は 202 です。
2. getFeeds のページネーション：前のページの nextToken のみを次のリクエストで使用します。Amazon 側のパラメーター名は paginationToken ではなく nextToken です（スクリプトのフィールド名も nextToken）。
3. upload の失敗は SP-API ゲートウェイとは無関係です。uploadUrl の有効期限が切れていないか、Content-Type が createFeedDocument の設定と一致しているかを確認してください。
4. ゲートウェイの path 許可リストには feeds/2021-06-30/ のプレフィックスが必要です。

---

重要な制限事項

• このスキルは、Amazon 側の feed ファイルのスキーマ検証を代行しません。feedType、TSV／XML 形式については公式情報に従ってください。
• getFeedDocument が返す url の内容は、別途 HTTP GET で取得する必要があります（upload と同様、developerProxy を経由しません）。
• 詳細は references/api.md を参照してください。

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 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用。453 期间停止该店铺全部 SP-API。
• 保留已有 reportId、feedId 等任务 ID；写操作结果不确定时先查询状态，不直接重放。
• 向用户先说明店铺保护，再给原因、处理和等待时间。可回复：“为保护您的亚马逊店铺安全，检测到 Amazon SP-API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或算力限制。”不要只说“LinkFox 限流”或“服务器繁忙”。

算力消耗规则

不消耗算力。

Feedback： skillName：linkfox-amazon-store-feeds。

---

更多跨境 skill：LinkFox Skills