Amazon SP-API認証で詰まる「Refresh Token」問題と解決法

Amazon SP-API（Selling Partner API）はEC事業者の自動化に欠かせないAPI。だが、認証周り、特にRefresh Tokenの扱いで躔る人が後を絶たない。

弊社でも自社受注管理システム「VOMS」のSP-API連携を組む過程で、Refresh Token周りで延゙20時間以上溶かした。今回は、その経験から詰まりやすい3つのパターンと解決策をまとめる。

【そもそもSP-API認証フローのおさらい】

SP-APIにアクセスするには、3つの認証情報が必要。

∶1. LWA（Login with Amazon）の Refresh Token：これが最重要
∶2. AWS IAM の Access Key / Secret
∶3. Application ID（Client ID / Client Secret）

このうち、Refresh Tokenがいちばん厲介。一度こけると最初からやり直しになるケースが多い。

【詰まりパターン①】Refresh Tokenの取得URLを間違える

これは初見で全員が踏むトラップ。マーケットプレイスを跨いだ時のURLが違う。

・日本マーケットプレイス：sellercentral.amazon.co.jp
・米国マーケットプレイス：sellercentral.amazon.com

弊社は最初に米国でRefresh Tokenを発行してしまい、日本セラーへのAPI呼び出しが全て401エラーになった。認可フローをやり直した。

必ず「co.jp」のURLから認可フロー開始。

【詰まりパターン②】Self-authorizationとWorkflow authorizationを混同

SP-APIの認証フローは2種類ある。

・Self-authorization：自分のセラーアカウントだけに使う場合
・Workflow authorization：他のセラーに自分のアプリを使ってもらう場合（公開アプリ）

弊社のような自社運用が目的なSelf-authorizationで十分だが、Selling Partner Appsの管理画面はデフォルトでWorkflow用フローになっている。

Self-authorizationは「アプリ詳細 → 認可」ボタンを別途押す必要がある。これに気付かずWorkflow URLから認可してしまうと、unauthorized_clientエラーが返ってくる。

【詰まりパターン③】Refresh Tokenが「サイレントに失効」する

ここが本記事最大のトラップ。Refresh Tokenは原則「無期限」と公式ドキュメントに書いてある。だが、実際には失効する条件がいくつかある。

弊社で踏んだ失効パターン：

1. セラーアカウントのパスワードを変更した → 全Refresh Tokenが即時失効
2. アプリの権限スコープを変更した → 旧Refresh Tokenは静かに無効化
3. 180日以上 SP-API を呼び出していない → 自動失効

特に3番目は気付きにくい。普段使うAPIだけ動いていて、たまにしか使わないAPIで突然 invalid_grant エラーが出る。

【解決策：月次ヘルスチェック】

・Refresh Tokenを安全に保管しつつ、月回のヘルスチェックスクリプトを組む
・Sandboxモードで全エンドポイントを軽く叩くだけでOK
・失効を検知したら Chatwork や Slack で通知

弊社のヘルスチェックは GitHub Actions で月回自動実行している。

【PHPで実装する場合の注意点】

弊社は秘書AI「vj-secretary」をPHP（Xサーバー）で実装中で、PHP公式SDKがないSP-APIの実装で苦戦している。

Access Tokenは1時間で切れるので、毎回 LWA Token を確認する必要がある。キャッシュ層（Redisやファイルキャッシュ）を立てて、Access Tokenを55分間キャッシュする実装にした。

【まとめ：SP-API認証チェックリスト】

☐ マーケットプレイスURL（.com or .co.jp）を確認した
☐ Self-authorizationフローを使った
☐ Refresh Tokenを安全な場所に保管した
☐ 月回のヘルスチェック自動化を仕込んだ
☐ PHP/Pythonいずれの場合も、Access Tokenキャッシュ層を持っている

弊社ではSP-API、Yahoo!ショッピングAPI、Qoo10 APIなどマルチモールEC運営の自動化を実装代行しています。ココナラのDMからお気軽にご相談ください。