linkfox-amazon-store-auth

Amazon ストアの認証と管理

このスキルは、Amazon 出品者ストアの OAuth 認証、認証済みストア一覧、認証状態の照会、トークンの更新、ローカルでの認証解除を担当します。レポートの取得、在庫の照会、注文の同期など、すべての下流操作に先立って必要です。下流の業務では、developerProxy に sellerId+region を渡すだけでよく、事前に raw token を取得する必要はありません。

📌 関連スキル：ユーザーがAmazon ストアのレポートを取得（在庫／注文／売上／財務レポートなど）する必要がある場合は、linkfox-amazon-store-report に切り替えてください。このスキルは、本スキルが提供する認証とトークン機能に依存します。

コアコンセプト

Selling Partner API は、Amazon が出品者向けに提供する公式インターフェースです。本スキルは OAuth 2.0 認証フローとトークンのライフサイクル管理を担当します。

認証フロー：認証 URL を生成 → ユーザーが Amazon で認証を完了 → Amazon が認証コードを付けてコールバック → システムが認証コードでトークンを取得 → トークンを安全に保存。

ストア名（sellerName）は必須：/spApi/authorizeUrl を呼び出す前に、必ずユーザーに確認し、明確で空ではないストア名を取得してください。この名前は「認証済みストア一覧」でアカウントを識別するために使用します。空欄や空白文字列は使用しないでください。

トークンのライフサイクル：accessToken は通常 1 時間で有効期限が切れます。refreshToken を使用すると、再認証せずに新しい accessToken に更新できます。

データフィールド

認証 URL のレスポンス

フィールド	型	説明
authorizeUrl	string	ユーザーがブラウザーで開く Amazon 認証リンク

認証済みストアの項目

フィールド	型	説明
sellerId	string	Amazon Seller ID（Merchant ID）
sellerName	string	ストア名（認証時に必須）
region	string	マーケットプレイスの地域コード NA／EU／FE

ストアトークン（認証状態。raw token の引き渡しではありません）

POST /spApi/storeTokens は状態とメタデータを返します（具体的なフィールドはゲートウェイに準じます）。認証が有効かどうかや、有効期限を確認するために使用します。レスポンスを下流の developerProxy に渡す token の取得元として扱わないでください。

フィールド	型	説明
status	string	認証／トークンの状態（有効、期限切れ、未設定など）
authRecordId	integer	認証レコード ID（存在する場合）
expiresIn	integer	accessToken の有効期限までの秒数（存在する場合）
tokenExpiresAt	string	絶対有効期限（存在する場合）
message	string	補足説明
errcode / errmsg	integer / string	ゲートウェイのエラー（失敗時）

互換性に関する注意：旧バージョンのゲートウェイでは、引き続き accessToken／refreshToken が返される場合があります。Agent はこれらを優先して読み取ったり、下流に渡したりしないでください。下流では sellerId+region を使用して developerProxy を呼び出してください。

対応リージョン

コード	名称	マーケットプレイス
NA	北米	米国、カナダ、メキシコ
EU	ヨーロッパ	英国、ドイツ、フランス、イタリア、スペイン、オランダなど
FE	極東	日本、オーストラリア、シンガポール、インド

デフォルトのリージョンは NA です。認証解除時は Scenario 5 に従って対象リージョンを明示してください。

呼び出し方法

• API エンドポイント：POST /spApi/{authorizeUrl|storeTokens|authorizedStores|refreshToken|cancelAuthorization}（パラメーター／レスポンス／エラーコードの詳細は 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 には要約のみ出力します（トップレベルのフィールド、一般的な件数、最も大きなリストフィールドの長さと先頭 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／プランの有効期限切れ／チャージが必要／チャージしてください」、または同様の意味の内容が含まれる場合。

使用シナリオ

Scenario 1: 新しいストアを認証する

ユーザーの依頼：「Amazon の北米ストアを認証したい」

手順：

1. ストア名 sellerName を確認します（ユーザーが提示していない場合）。/spApi/authorizeUrl では sellerName に空ではない文字列が必要です。これは LinkFox 内でストアを識別するためのラベルにすぎないことをユーザーに説明し、Seller Central の名前と一致させることを推奨します。
2. /spApi/authorizeUrl を呼び出し、region と sellerName を渡します。
3. 返された authorizeUrl をユーザーに渡し、ブラウザーで開いてもらいます。
4. ユーザーが Amazon で認証を完了 → Amazon がシステムにコールバック → システムが認証情報を自動で保存します。
5. 必要に応じて /spApi/authorizedStores を呼び出し、認証が成功したことを確認します。

Scenario 2: 認証済みストアを表示する

ユーザーの依頼：「認証済みの Amazon ストアを一覧表示して」

手順：

1. /spApi/authorizedStores を呼び出します。
2. ストア一覧（sellerName／sellerId／region）を表示します。
3. sellerId、region の順に並べ替えます。

Scenario 3: 期限切れトークンを更新する

ユーザーの依頼：「ストアのトークンが期限切れです。更新してください」

手順：

1. /spApi/refreshToken を呼び出し、sellerId（region は任意）を渡します。
2. 更新の状態とメタデータ（status、message、expiresIn など）が返され、サーバー側でトークンが更新されます。
3. 下流では同じ sellerId+region を渡して developerProxy をそのまま再試行できます。raw token を読み取る必要はありません。

Scenario 4: ストアトークンの状態を照会する

ユーザーの依頼：「北米ストアの A123 の認証／トークン状態を確認して」

手順：

1. /spApi/storeTokens を呼び出し、sellerId と region を渡します。
2. ユーザーに状態フィールド（status、expiresIn、tokenExpiresAt、message など）を表示します。
3. レスポンスを下流の proxy に渡す token として扱わないでください。業務呼び出しには sellerId+region をそのまま指定します。

シナリオ 5：ローカル認可の取り消し

ユーザーのリクエスト：「Amazon ストアの認可を取り消す／解除する」

ユーザーから要求があった場合にのみ実行します。現在のユーザーは API key に対応するメンバー身份によって識別されます。この身份を共有するユーザーには、まとめて影響が及びます。

手順：

1. ユーザーが指定した対象または /spApi/authorizedStores から sellerId + region を特定します。デフォルトの地域は使用せず、曖昧な場合はユーザーに選択してもらいます。
2. 解除は地域全体に適用されることを説明します。ユーザーが単一サイトのみを希望する場合は、地域全体の解除について明確な同意を得てください。
3. /spApi/cancelAuthorization を呼び出し、選択した sellerId と region を渡します。
4. references/api.md に従って結果を説明します。その後ストアを再照会し、自動的に再認可は行いません。

シナリオ 6：あらゆるストア操作に向けたアカウントセレクターの準備（標準準備ワークフロー）

ユーザーから販売者管理画面のデータに関する依頼（レポートの取得、在庫の確認、注文の確認など）があった場合、この skill は前段の「ストア選択 → 認可確認」を担当し、具体的な業務は対応する下流の skill が引き継ぎます。

手順：

1. 認可済みストアを一覧表示する：/spApi/authorizedStores を呼び出します
2. ユーザーにストアを選択してもらう：複数のストアがある場合は、どのストアを選ぶか明確に指定してもらい、sellerId と region を確定します
3. （任意）/spApi/storeTokens を呼び出し、状態確認のみを行います（期限切れの場合は、先に refreshToken を実行します）
4. sellerId+region を下流の skill に渡します（例：linkfox-amazon-store-report）。下流では直接 developerProxy を呼び出します

このワークフローが重要な理由：

• ユーザーが異なる地域の複数のストアを同時に認可している場合があります
• 各ストアのトークンと権限はそれぞれ独立しています
• ストアに一致する sellerId+region を使用する必要があります。「ストア選択」を省略すると、曖昧さや誤りにつながります

表示ルール

1. ストア名を確認してから認可リンクを生成する：ユーザーが sellerName を指定していない場合、必ず先に確認してください。空の値を指定して /spApi/authorizeUrl を呼び出してはいけません。
2. データのみを表示する：認可結果、ストア一覧、トークン情報のみを表示し、業務上の提案は行いません。
3. セキュリティに配慮する：レスポンスに legacy token フィールドが含まれている場合は、平文で表示しないでください。status や有効期限などのメタデータを優先して表示します。
4. 明確に案内する：認可リンクを返す際は、ブラウザーで開いて認可を完了するよう明確に伝えます。
5. エラーを説明する：認可に失敗した場合は、エラーコードに基づいて理由を説明し、対処方法を提案します。
6. 成功を確認する：認可が完了したらユーザーに確認し、必要に応じてそのストアの基本情報を表示できます。

重要な制限事項

• sellerName は必須です：/spApi/authorizeUrl には空でない sellerName を渡す必要があります。スクリプトと agent は呼び出し前に必ず検証してください。
• トークンの有効期間：accessToken は 1 時間で期限切れになるため、速やかに更新する必要があります。
• 地域ごとの認可：ストアの認可は毎回、特定の地域に紐づきます。地域が異なる場合は、それぞれ別途認可が必要です。
• ユーザーの分離：ユーザーは自分が認可したストアのみを参照・管理できます。
• コールバックの許可リスト：システムのコールバック URL は、認可プロバイダー（紫鳥）で許可リストに登録する必要があります。

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

該当する — 認可とトークン管理のシナリオ：

ユーザーの発言	シナリオ
「Amazon ストアを認可して」 / 「Authorize my Amazon store」	新しいストアの認可
「認可済みの Amazon ストアを確認して」 / 「Show my authorized stores」	認可済みストアの一覧表示
「トークンの有効期限が切れた」 / 「My token expired」	トークンの更新
「XXX ストアの認可状態を確認して」 / 「Check store token status」	認可状態の確認（storeTokens）
「Amazon アカウントを連携して」 / 「Connect my Amazon seller account」	新しいストアの認可
「認可を取り消して」 / 「この Amazon ストアの連携を解除して」 / 「Disconnect seller account」	ローカルで認可を取り消す／解除する

該当しない — この skill の範囲外の業務：

• Amazon レポートの取得 → linkfox-amazon-store-report を使用してください
• 商品 listing の管理、注文処理、在庫管理、広告配信 → 他の skill が担当します

境界の判断：

• この skill が担当するのは、「認可 + ストア管理 + トークンの更新／状態確認 + 下流向けに sellerId+region のストア選択情報を準備すること」のみです。
• 下流の developerProxy 呼び出しのために、storeTokens から raw accessToken を取得しないでください（非常に古いクライアントとの互換性が必要で、かつユーザーから明確な要求がある場合を除きます）。
• ユーザーが具体的な販売者管理画面の業務（レポートの取得など）を依頼した場合：
  1. この skill でシナリオ 6 の標準的な前段フロー（ストア選択）を実行します
  2. 続いて対応する下流の skill に切り替え、developerProxy + sellerId+region を直接使用します
• この skill を迂回して、Amazon の具体的な公開 API を直接呼び出してはいけません。

クイックリファレンス

認可・トークン管理 API

API	パス	目的	認証が必要
認可 URL の取得	/spApi/authorizeUrl	認可リンクを生成する（sellerName が必要）	✅ はい
認可済みストアの一覧表示	/spApi/authorizedStores	ユーザーのストア一覧を照会する	✅ はい
トークンの更新	/spApi/refreshToken	アクセストークンを更新する	✅ はい
ストアのトークン状態の照会	/spApi/storeTokens	ストアの認可／トークン状態を照会する（下流向けのトークン取得元ではありません）	✅ はい
認可の取り消し	/spApi/cancelAuthorization	現在のユーザーのストア認可をローカルで取り消す／解除する	✅ はい

リクエストパラメーター、レスポンス構造、エラーコードの詳細は references/api.md を参照してください。認可フロー全体の図は references/authorization-flow.md を参照してください。クイックスタートの例は references/quick-start.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 が発生した場合、パラメーター、認可、またはリソース識別子を修正してから、クールダウン後に慎重に最大 1 回だけ再試行してください。再度発生した場合は呼び出しを停止します。453 の発生中は、その店舗の SP-API 呼び出しをすべて停止してください。
• 既存の reportId、feedId などのタスク ID は保持してください。書き込み操作の結果が不明な場合は、再実行せずに先にステータスを照会してください。
• まず店舗保護についてユーザーに説明し、その後に原因、対応方法、待機時間を伝えてください。次のように返信できます。「お客様の Amazon 店舗の安全を守るため、Amazon SP-API が{原因}を連続して返したことを検知し、現在、一時的な保護が適用されています。まず{対応方法}を行い、{待機時間}後に再試行してください。これはアカウント停止を意味するものではなく、プランや計算リソースの制限でもありません。」「LinkFox のレート制限」や「サーバーが混み合っています」とだけ伝えるのは避けてください。

計算リソースの消費ルール

計算リソースを消費しません。

Feedback：

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

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

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

---

より高品質でプロフェッショナルな越境 EC 向け skill については、LinkFox Skills をご覧ください。