【開発者向け】PA-API v5からCreators APIへの書き換えコード例

開発者の方に向けて、従来の PA-API v5 から Creators API (v3.3) への移行に伴うコードレベルの変更点をまとめました。

最大の違いは、認証方式が AWS署名 (v4) から OAuth 2.0 (LwA) に変わったこと、そしてリクエストの パラメータ名が小文字開始 に統一されたことです。

1. 主要な仕様変更の比較
2. 【重要】認証プロセスの変化
1. Access Token 取得の cURL 例
3. リクエストコードの書き換え例 (PHP)
1. 旧：PA-API v5
2. 新：Creators API
4. レスポンス処理の変更点
5. 移行のためのチェックリスト
まとめ

1. 主要な仕様変更の比較

項目	PA-API v5 (旧)	Creators API (新)
認証方式	HMAC-SHA256 (AWS SigV4)	OAuth 2.0 (LwA)
エンドポイント	`webservices.amazon.co.jp`	`creatorsapi.amazon.com`
HTTPメソッド	POST	POST
JSONキー	アッパーキャメル (`Keywords`)	ローワーキャメル (`keywords`)
商品情報	`Offers.Listings`	`offersV2.listings`

2. 【重要】認証プロセスの変化

PA-API v5ではリクエストごとに署名を生成していましたが、Creators APIでは Access Token を事前に取得し、それを Authorization ヘッダーに乗せる方式になります。

Access Token 取得の cURL 例

curl -X POST https://api.amazon.co.jp/auth/o2/token \
  -H "Content-Type: x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CREDENTIAL_ID" \
  -d "client_secret=YOUR_CREDENTIAL_SECRET" \
  -d "scope=amazon_creators_api"

注: 取得した access_token は通常1時間有効です。有効期限内は再利用し、期限が切れたら再取得する実装が必要です。

3. リクエストコードの書き換え例 (PHP)

SearchItems を例に、パラメータ構造の変化を確認してください。

旧：PA-API v5

// PA-API v5のリクエストボディ
$payload = json_encode([
    "Keywords" => "Harry Potter",
    "PartnerTag" => "your-tag-22",
    "PartnerType" => "Associates",
    "SearchIndex" => "All",
    "Resources" => ["ItemInfo.Title", "Offers.Listings.Price"]
]);

新：Creators API

// Creators APIのリクエストボディ（キーが小文字開始に変更）
$payload = json_encode([
    "keywords" => "Harry Potter",
    "partnerTag" => "your-tag-22",
    "searchIndex" => "All",
    "resources" => [
        "itemInfo.title", 
        "offersV2.listings.price" // リソース名も変更
    ],
    "marketplace" => "www.amazon.co.jp" // 必須項目
]);

// ヘッダーには取得済みのBearer Tokenをセット
$headers = [
    'Authorization: Bearer Atc|...',
    'Content-Type: application/json',
    'x-amz-creators-api-target: com.amazon.creators.v1.AmazonCreatorsApi.SearchItems'
];

4. レスポンス処理の変更点

レスポンスの構造も、キャメルケースからスモールキャメルケースへ変更されています。

旧: $response['SearchResult']['Items'][0]['ASIN']
新: $response['searchResult']['items'][0]['asin']

特に 価格情報 を取得していた場合、Offers.Listings ではなく offersV2.listings を指定し、その下の price.money.displayAmount などを参照する形になります。

5. 移行のためのチェックリスト

SDKの導入: 署名処理を自作するより、公式の amazon-creators-api SDK（Node.js, PHP, Python対応）を利用することを強く推奨します。
Marketplaceパラメータ: marketplace フィールド（例: www.amazon.co.jp）が必須となりました。
大文字・小文字の修正: 全てのJSONキーを小文字開始に置換してください。
48時間ルール: 新しい認証情報（Credential ID）を発行した後、実際にAPIが通るまで最大48時間のラグがあるため、テストは余裕を持って行いましょう。