株式会社renue
AI導入・DXの悩みをプロに相談してみませんか？
AIやDXに関する悩みがありましたら、お気軽にrenueの無料相談をご利用ください。 renueのAI支援実績、コンサルティングの方針や進め方をご紹介します。
Amazon Selling Partner API(SP-API)はAmazon出品者向けの統一APIだが、「LWA(Login with Amazon)認証」「リージョン別エンドポイント」「注文/カタログ/在庫/レポート/財務の5大リソース」「ページネーションNextToken」といった独自概念が多く、初見では実装に詰まるポイントが多い。本記事では、SP-API統合の本番品質パターンを解説する。
SP-APIの全体像: 何が独自で何が標準か
SP-APIはRESTful設計だが、以下の点で一般的なSaaS APIと異なる。
- 3リージョン分離: NA(北米)/EU(欧州)/FE(極東)でエンドポイントが完全分離
- LWA認証: Login with AmazonのOAuth 2.0 refresh_token flow — アクセストークンは1時間で失効
- Marketplace ID必須: ほぼ全リクエストで出品先マーケットプレイスIDを指定
- NextToken方式: ページネーションがpage番号ではなく不透明な継続トークン
- x-amz-access-tokenヘッダ: Authorizationヘッダではなく独自ヘッダ名
- レポートは非同期: 大量データはCreate→Poll→Downloadの3段階
日本の出品者が知っておくべき値
| 項目 | 値 |
|---|---|
| 日本のMarketplace ID | A1VC38T7YXB528 |
| 極東(FE)エンドポイント | https://sellingpartnerapi-fe.amazon.com |
| LWAトークンエンドポイント | https://api.amazon.com/auth/o2/token |
| アクセストークン有効期限 | 3600秒(1時間) |
| 1ページの最大件数(Orders) | 100 |
| 1ページの最大件数(Catalog) | 20 |
レイヤー1: リージョン別エンドポイント設計
SP-APIで最初にやるべきはリージョン別エンドポイントを定数化することだ。一度実装すれば欧米展開時の追加コストがほぼゼロになる。
region="fe"をデフォルトにしているのは日本市場を中心に扱う想定のため。グローバル出品を扱う場合はregionパラメータを必須化する設計に変える。
レイヤー2: LWAリフレッシュトークンフロー
SP-APIの認証はOAuth 2.0 refresh_token flowそのもの。既存のLWA refresh_tokenを使って毎回アクセストークンを取得する。
初期化時の自動フォールバック
クライアント初期化時にaccess_tokenが未指定なら自動的にrefreshする設計にすると、呼び出し側がシンプルになる。
開発時は短命アクセストークンを直接渡す、本番はrefresh_tokenのみ環境変数に入れる、という柔軟な運用ができる。
レイヤー3: x-amz-access-token ヘッダ
SP-APIはAuthorization ヘッダではなく x-amz-access-tokenという独自ヘッダにトークンを載せる。この仕様を知らないとひたすら401で詰まる。
通常のREST APIでありがちなAuthorization: Bearer {token}を書いてしまうと認証が通らない。ヘッダ名だけはSP-API固有と覚えておく。
レイヤー4: 統一requestメソッド + エラー階層
Orders/Catalog/Inventory/Reports/Financesを横断するrequestメソッドを一つ用意し、各API関数はその薄いラッパーにするのが設計の要点。
errorsフィールドの抽出が重要
SP-APIのエラーレスポンスは{"errors": [{"code": "...", "message": "..."}]}形式。単にresponse.textを投げるとデバッグできないので、errors[0].message を必ず抽出する。これだけで本番でのトラブルシューティング時間が10分の1になる。
レイヤー5: 5大リソースの薄いラッパー
Orders API
OrderStatusesはカンマ区切り(Unshipped,PartiallyShipped)で渡すのがAmazon仕様。["Unshipped", "PartiallyShipped"]をそのまま渡すと配列エラーになる。
Catalog API
CatalogはpageSize最大20という厳しい制限がある。Orders(100)と混同すると400エラーになる。
Inventory API (FBA)
Inventory APIはgranularityType/granularityIdという独自概念がある。基本はMarketplace粒度で問題ない。
Reports API(非同期フロー)
Reports APIは大量データ向けの非同期方式で、Create Report → Poll Status → Download Documentの3段階。
非同期フローなので呼び出し側はCeleryタスクやバックグラウンドジョブで組むのが基本。待機ループをサーバー同期コードで書くのはアンチパターン。
NextTokenページネーション: 全件取得パターン
SP-APIはNextToken方式のため、全件取得はwhileループで「NextTokenがnilになるまで」回す。
重要なのは初回リクエストではfilterを渡し、2回目以降はNextTokenのみ渡すパターン。Amazonは「NextTokenと他のフィルタを併用するな」という暗黙の仕様があり、両方渡すと400エラーになる。
運用Tips
レート制限(トークンバケット)
SP-APIはエンドポイントごとに「バーストレート/リフィルレート」のトークンバケット方式でレート制限される。OrdersはBurst 20, Refill 0.0167/s(1分あたり1)のように非常に厳しい。レポート優先で取得し、リアルタイム性が必要な部分だけOrdersを叩く設計が推奨。
アクセストークンキャッシュ
アクセストークン有効期限は1時間。毎リクエストで取得するとLWA側にもレート制限がかかる。クライアントインスタンスに_token_expires_atを持たせてキャッシュする改良を入れると本番安定度が上がる。
エラーリトライ
SP-APIは429/500/502/503/504は指数バックオフでリトライすべきとAmazonが公式に推奨している。本記事の実装は基本形なので、本番ではtenacity等でリトライラッパーを被せるとよい。
まとめ
- リージョン別エンドポイント定数化(NA/EU/FE)で多国展開に備える
- LWA refresh_token flowで1時間アクセストークンを自動取得
- x-amz-access-tokenヘッダ(Authorizationヘッダではない)
- 統一requestメソッド + errors[0].message抽出でデバッグ性を確保
- Orders 100 / Catalog 20 のページサイズ違いに注意
- Reports APIは非同期3段階でバックグラウンドジョブ必須
- NextToken併用時はフィルタを渡さない(暗黙仕様)
