ギフト券コードの作成

連携を開始する前に、必ず Amazon インセンティブ API アカウントを設定してください。インセンティブ API アカウントを作成します。

インセンティブ API を使用すると、Amazon ギフト券コードをインターネット経由で迅速に作成および配布できます。

Amazon ギフト券コードは、ウェブサービスを使用して購入でき、顧客に配布できます。このドキュメントでは、開発者が AGCOD API を使用して Amazon ギフト券コードを作成する方法について説明します。これらのコードは、次のようなさまざまな方法で使用できます。

電子ギフト券への Amazon ギフト券コードの挿入
グループギフト
ロイヤルティプログラム (ポイントプログラムなど) での Amazon ギフト券コードのリアルタイム交換。

操作
エラー処理
- エラーコード
Amazon ギフト券コードの取り扱い
トランザクション金額制限
デジタルコード作成テストスクリプト

操作

ユーザーのプログラムにより、署名済み HTTP POST リクエストがエンドポイントに送信され、Amazon ギフト券コードが作成またはキャンセルされます。(SOAP リクエストは受け付けていません。) HTTP リクエストの本文には JSON または XML が含まれます。

注：インセンティブ API 操作エンドポイントへのすべてのリクエストは、インセンティブ API セキュリティ認証情報と署名バージョン 4 署名アルゴリズムを使用してデジタル署名する必要があります。

操作	説明
`CreateGiftCard`	十分な金額が前払い口座にある場合、資金を差し引き、有効なギフト券コードをその他のトランザクション詳細とともに返します。
`CancelGiftCard`	Amazon カスタマーがギフト券を取得しておらず、有効期限が切れていない場合、有効なギフト券コードをキャンセルします。
`GetAvailableFunds`	前払い口座の残高を返します。

次の表では、これらのエンドポイントを呼び出すときに使用する概念と要素について説明します。

項目	説明
`partnerId`	Amazon チームにより提供される一意の識別子 (大文字小文字を区別、最初の文字が大文字、残りの 4 文字が小文字)。この値は、すべての AGCOD ゲートウェイリクエストのペイロードに表示されます。
`creationRequestId`	CreateGiftCard リクエストごとに一意の識別子。Create リクエストごとに新しい値を生成する必要があります (再試行を除く)。(以下の注意事項を参照してください。)
`CreateGiftCard` レスポンスと `CancelGiftCard` レスポンス	これらのエンドポイントへの各リクエストに対して返されるレスポンスのユーザーのプログラムを解析し、必要に応じて保存してください。
`Transaction`	トランザクションとは、Amazon システム内でギフト券の作成/キャンセルを行うリクエストまたはレスポンスを指します。

creationRequestId をグローバルに一意に保つには、次の要件に従います。

システム内で一意の英数字の値を生成します。この ID には最大 40 文字の英数字を使用できます。
creationRequestId はパートナー ID で始まるようにします。

例：パートナー ID が Amzn1 の場合、creationRequestId を Amzn1 で始め、その後に希望する文字を追加します (例： Amzn154321）。インセンティブ API は冪等であるため、以前に使用された creationRequestId でリクエストが送信された場合、インセンティブ API は creationRequestId が最初に使用されたときに作成された元のステータスを返します。

CreateGiftCard

CreateGiftCard操作では、有効なギフト券コードが作成され、その金額が前払い口座から差し引かれます。レスポンスには、保存する必要がある詳細が含まれています。

creationRequestId の値は、各作成リクエストを一意に識別し、金額、通貨などの情報 (そのリクエストに関するメタデータ、認証情報など) が含まれます。

この操作を実行するには、次の手順を実行します。

インセンティブ API に CreateGiftCard リクエストを送信します。
Amazon は、前払い口座を確認して、このリクエストに対して十分な資金があることを確認します。
Amazon は注文金額を差し引き、gcClaimCode (有効なギフト券コード) と gcExpirationDate (有効期限、米国、カナダ、オーストラリアで作成されたギフト券以外) が含まれる同期された CreateGiftCard レスポンスメッセージを返します。
ユーザーのプログラムには、creationRequestId、amount、および currencyCode の値を格納する必要があり、gcClaimCode を安全に処理する必要があります。詳細については、データストレージのガイドラインを参照してください。

リクエストの例

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

レスポンスの例

<CreateGiftCardResponse>
    <gcClaimCode>W3GU-YD4NGH-88C8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>EUR</currencyCode>
            <amount>1.00</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A3B6AC387ESRIX</gcId>
    <creationRequestId> AwssbTSpecTest001</creationRequestId>
    <gcExpirationDate>Mon Jun 09 21:59:59 UTC 2025</gcExpirationDate>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

この操作は冪等であるため、インセンティブ API が同じ creationRequestId を持つ複数のリクエストを受信した場合、最初のリクエストに対してのみ新しいギフト券が作成され、後続のすべてのレスポンスは同じギフト券を返します。異なるトランザクションとして扱われることはありません。

CreateGiftCard を 1 回呼び出すと、ギフト券コードが 1 つのみ作成されます (現時点では一括作成はサポートされていません)。

再販業者に必須： ProgramID

programID フィールドを使用すると、クライアントとユースケースのトランザクションを追跡できます。programID は、申請により Amazon から提供される承認された識別子です。まず、パートナー申請プロセスを通じて、クライアントとユースケース情報を提出する必要があります。申請が承認されると、API に対する各トランザクション呼び出しでユーザーのプログラムに含める programID と呼ばれる参照番号を受け取ります。programID は英数字で、最大文字数は 100 文字です。

以下の例のメッセージは、programID フィールドに対応するために必要な変更を示しています。

<CreateGiftCardRequest>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <partnerId>Awssb</partnerId>
  <value>
    <currencyCode>EUR</currencyCode>
    <amount>1.00</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</CreateGiftCardRequest>

Amazon 種類別商品券に必須：productType

productType フィールドは、Amazon 種類別商品券のギフト券コードの作成に必要です。このフィールドを使用するには、認証を受ける必要があります。このフィールドは、種類別商品券の種類ごとに異なり、一意となります。この任意フィールドが渡されない場合、返されるギフト券コードは Amazon ギフト券用のコードになります。この属性は英数字で、最大長は 50 文字です。

注：種類別商品券を作成できるのは、承認されたパートナーのみです。詳細については、アカウントマネージャーにお問い合わせください。

code class="highlighter-rouge">productType に指定可能な値はこのスプレッドシートを参照してください。

<CreateGiftCardRequest>
  <creationRequestId>Humana_2018072650</creationRequestId>
  <partnerId>Humana</partnerId>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>25</amount>
  </value>
  <productType>bookPV</productType>
</CreateGiftCardRequest>

実店舗での追加要件

実店舗で発生する CreateGiftCard 呼び出しごとに、トランザクションが発生した場所の詳細を含める必要があります。これらのエンドポイントへのリクエストには、イベントの物理的な場所を記述する transactionSource オブジェクトを含めることができます。

Field in `transactionSource`	説明
`sourceId`	トランザクションソースエンティティの識別子 (例：ストア番号またはストア ID)。
`institutionId`	トランザクションソースの親エンティティの識別子 (例：マーチャント ID)。親エンティティが存在しない場合は、`sourceId` をコピーします。
`sourceDetails`	トランザクションソースの詳細情報を提供する文字列。これは、`institutionName` キーと、その値としてソース名 (マーチャント名など) が含まれている必要があります。ソースの場所、電話番号などの情報を含める必要があります。
`institutionParentCompany`	`instituitionName` の親会社名です。親会社がない場合は、`institutionName` を繰り返す必要があります。

Amazon に店舗ロケーションデータを送信するには、次の 2 つのオプションがあります。

長い形式 - パートナーは、トランザクションごとに特定の店舗ロケーションデータを含めます (sourceId、institutionId、sourceDetails を含める必要があります)。
短い形式 - パートナーは API リクエストに sourceId と institutionId のみを指定します。これらの識別子を物理的な場所にマップする個別のロケーションマッピングファイルを送信する必要があります。ロケーションマッピングファイルの手順はこのスプレッドシートを参照してください。

XML 形式と JSON 形式のトランザクションソースの「長い形式」ペイロードのサンプルを以下に示します。sourceDetails は JSON blob としてフォーマットする必要があることに注意してください。JSON の例では、JSON blob はバックスラッシュを使用して引用符をエスケープします。

XML 本文の長い形式の例 (sourceDetails の値はJSON blob としてフォーマットする必要があります)：

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

XML 本文の短い形式の例：

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

JSON 本文の短い形式の例：

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceId": "59990492",
    "institutionId": "99990492"
  }
}

JSON 本文の長い形式の例：

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

任意：外部参照属性

externalReference フィールドを使用すると、ギフト券コードのリクエスト時に独自の参照識別子を文字列として渡すことができます (最大 100 文字の Unicode 文字)。externalReference フィールドは、トラッキングに役立つ便利なマッピングを保存するために使用できます。たとえば、保険請求、キオスク、カスタマーケース、注文 ID、再販業者のカスタマーアカウント、または店舗情報を externalReference フィールド内に指定できます。

注：このフィールドでは、自然言語コンテンツのない不透明な順序参照のみが許可されます。

externalReference フィールドで渡された識別子は、インセンティブ API ポータルの詳細アクティビティダウンロードでトランザクションとともに表示されます。

次の例には externalReference フィールドが含まれています。

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
    <externalReference>889jj14797</externalReference>
</CreateGiftCardRequest>

レスポンスの項目

これらの項目は、CreateGiftCard 操作の呼び出しが成功した場合のレスポンス本文に表示されます。

項目	説明
`gcClaimCode`	顧客が後で手動で引き換えるために使用できるコードです。ただし、安全に保管し、配布後に消去してください。Amazon では、CreateGiftCard と同じ呼び出しで後から利用できます (下記参照)。
`amount`	カード金額 (カード通貨単位)。
`currencyCode`	カードの通貨を指定する ISO-4217 通貨コード。
`cardStatus`	操作後のカードのステータス。成功値： `Fulfilled`
`gcId`	CreateGiftCard 呼び出しによって gcClaimCode が発生したことを示す一意のギフト券識別子。
`creationRequestId`	このリクエストの一意の識別子。パートナー ID で始まります。
`gcExpirationDate`	有効期限です。この日付を過ぎると、顧客がカードを請求することはできません。(米国、カナダ、オーストラリアで発行されたカードには表示されません。)
`status`	この操作の結果です。成功値： `SUCCESS`

既存の gcClaimCode は、CreateGiftCard を同じ creationRequestId、currencyCode、amount の値で呼び出すことで、再リクエストすることができます。

CreateGiftCard エンドポイントは、ギフト券コードの現在の cardStatus を返します。

Fulfilled - ギフト券コードが正常に作成されました。

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

RefundedToPurchaser - CancelGiftCard の前回の呼び出しでギフト券コードが正常にキャンセルされ、返金されました。

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>RefundedToPurchaser</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Expired - 有効期限より前にギフト券コードが申請されませんでした。

<CreateGiftCardResponse>
    <gcClaimCode>G22G-WACQNJ-27S8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>JPY</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Expired</cardStatus>
    </cardInfo>
    <gcId>A2BWWZ1SGEZF2F</gcId>
    <creationRequestId>Awssb-ABR-10</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

CancelGiftCard

Amazon カスタマーがギフト券を請求していない限り、ギフト券をキャンセルすることができます。ギフト券をキャンセルするには、ギフト券の作成に使用された元の creationRequestId が必要です。

注：この操作を実行できるのは、作成リクエストのタイムスタンプから 15 分以内に限られます。この期間が過ぎると、ギフト券コードはキャンセルできなくなり、前払い口座から請求が差し引かれます。

この操作を実行するには、CancelGiftCard リクエストを送信し、インセンティブ API が同期されたCancelGiftCardResponse で応答する必要があります。

CreateGiftCard 操作と CancelGiftCard 操作の両方は冪等であるため、インセンティブ API が同じ creationRequestId で同様のリクエストを複数受け取った場合、最初のリクエストではギフト券リクエストの作成/キャンセルが行われますが、後続のすべてのレスポンスでは何も行われず、一意のトランザクションとして扱われません。

リクエストの例

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
</CancelGiftCardRequest>

レスポンスの例

<CancelGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <status>SUCCESS</status>
</CancelGiftCardResponse>

GetAvailableFunds

この操作は、Amazon インセンティブアカウントで現在利用可能な資金の金額を返します。インセンティブ API ポータルにログインして利用可能な資金を表示する操作の代替手段になります。この操作を使用して残高を監視し、アラートを発生させることができます。

注：

この操作は、1 秒あたり 1 トランザクションに調整されます。そのレートを超える分の操作が実行されても、それらは無視されます。
サンドボックスには実際のアカウントの残高はないため、GetAvailableFunds 操作は常に残高 0 を返します。

リクエストパラメータ	説明
`partnerId`	Amazon がアカウントに割り当てる、大文字と小文字を区別する一意の識別子

レスポンスパラメータ	説明
`amount`	前払い/後払い口座で現在利用可能な資金の金額。注：サンドボックス環境は常に値 0 を返します。
`currencyCode`	ISO-4217 通貨コード
`status`	リクエストのステータス。通常の操作では、この値は `success` です。
`timestamp`	UTC yyyy-MM-dd HH:mm:ss 形式で返される日付

リクエストの例

POST 
/GetAvailableFunds HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657

{"partnerId": "Aptuk"}

レスポンスの例

{
"availableFunds":{
"amount":10.0,
"currencyCode":"USD"
},
"status":"SUCCESS",
"timestamp":20170915T200959Z
}

署名の詳細を含む操作リクエストの例

このセクションでは、署名の値の例を含む、CreateGiftCard と CancelGiftCard の呼び出し例を示します。

必須パラメータ

注：通貨の値 (USD、GBP、EUR、JPY、AUD、TRY、AED) はロケールにより異なります。

ヘッダー	値
HTTP リクエスト方法	`POST`
正規 URI	`/CreateGiftCard`
正規クエリ文字列	'' (空の文字列)
正規ヘッダー	(下記参照)
SignedHeaders	`content-type;host;x-amz-date;x-amz-target`
アルゴリズム	`AWS4-HMAC-SHA256`
リクエスト日	`20130910T221949Z`
CredentialScope	`20130910/us-east-1/AGCODService/aws4_request`
サービス名	`AGCODService`
作成リクエストの ID	`AwssbTSpecTest001`
ホスト	`agcod-v2-gamma.amazon.com` (該当するエンドポイントを使用)
地域名	`us-east-1` (該当するエンドポイントを使用)
パートナー ID	`Awssb` (パートナー ID を使用)
金額	`1`
通貨コード	`USD`

正規ヘッダーは次のようになります。

    accept:application/json
    content-type:application/json
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T222620Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

または次のようにします。

    content-type:application/x-www-form-urlencoded; charset=UTF-8
    host:agcod-v2-gamma.amazon.com
    x-amz-date:20130910T221949Z
    x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

CreateGiftCard

注：以下の例は、Amazon テストアカウントを使用して作成されたものです。アクセス識別子 (accessKeyID、partnerID、requestID) は独自の値を使用してください。

JSON ペイロードを使用した CreateGiftCard HTTP POST リクエストの例

ペイロード

{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

ハッシュ化されたペイロード

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

正規リクエスト

POST
/CreateGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

ハッシュ化された正規リクエスト

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

署名する文字列

AWS4-HMAC-SHA256
20130910T222620Z
20130910/us-east-1/AGCODService/aws4_request
447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

派生した署名キー

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

署名

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

エンドポイント

agcod-v2-gamma.amazon.com

署名済みリクエスト

POST /CreateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71
{"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "value": {"currencyCode": "USD", "amount": 1.00}}

XML ペイロードを使用した CreateGiftCard HTTP POST リクエストの例

ペイロード

<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

ハッシュ化されたペイロード

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

正規リクエスト

POST
/CreateGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

ハッシュ化された正規リクエスト

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

署名する文字列

AWS4-HMAC-SHA256
20130910T221949Z
20130910/us-east-1/AGCODService/aws4_request
4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

派生した署名キー

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

署名

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

エンドポイント

agcod-v2-gamma.amazon.com

署名済みリクエスト

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

CreateGiftCard レスポンスの例

JSON レスポンス本文

{
  "cardInfo": {
    "cardNumber": null,
    "cardStatus": "RefundedToPurchaser",
    "expirationDate": null,
    "value": {
      "amount": 1,
      "currencyCode": "USD"
    }
  },
  "creationRequestId": "AwssbTSpecTest001",
  "gcClaimCode": "Z7NV-LBBG39-75MU",
  "gcExpirationDate": null,
  "gcId": "A2GCN9BRX5QS76",
  "status": "SUCCESS"
}

XML レスポンス本文

<CreateGiftCardResponse>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <cardInfo>
    <value>
      <amount>1.0</amount>
      <currencyCode>USD</currencyCode>
    </value>
    <cardStatus>Fulfilled</cardStatus>
  </cardInfo>
  <status>SUCCESS</status>
  <gcId>A2GCN9BRX5QS76</gcId>
  <gcClaimCode>Z7NV-LBBG39-75MU</gcClaimCode>
</CreateGiftCardResponse>

CancelGiftCard

JSON ペイロードを使用した CancelGiftCard HTTP POST リクエストの例

ペイロード

 {"creationRequestId": "AwssbTSpecTest001", "partnerId": "Awssb", "gcId": "A2GCN9BRX5QS76"}

ハッシュ化されたペイロード

 7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

正規リクエスト

POST
/CancelGiftCard

accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

ハッシュ化された正規リクエスト

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

署名する文字列

AWS4-HMAC-SHA256
20130910T222545Z
20130910/us-east-1/AGCODService/aws4_request
0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

派生した署名キー

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

署名

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

エンドポイント

agcod-v2-gamma.amazon.com

署名済みリクエスト

POST /CancelGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949
{
  "creationRequestId": "AwssbTSpecTest001",
  "partnerId": "Awssb",
  "gcId": "A2GCN9BRX5QS76"
}

XML ペイロードを使用した CancelGiftCard HTTP POST リクエストの例

PAYLOAD

<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

ハッシュ化されたペイロード

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

正規リクエスト

POST
/CancelGiftCard

accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

ハッシュ化された正規リクエスト

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

署名する文字列

AWS4-HMAC-SHA256
20130910T222449Z
20130910/us-east-1/AGCODService/aws4_request
8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

派生した署名キー

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

署名

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

エンドポイント

agcod-v2-gamma.amazon.com

署名済みリクエスト

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

CancelGiftCard レスポンスの例

JSON レスポンス本文

{"creationRequestId":"AwssbTSpecTest001","gcId":"A2GCN9BRX5QS76","status":"SUCCESS"}

XML レスポンス本文

<CancelGiftCardResponse>
<creationRequestId>AwssbTSpecTest001</creationRequestId>
<status>SUCCESS</status>
<gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardResponse>

必須パラメータ

注：通貨の値 (USD、GBP、EUR、JPY、AUD、TRY、AED) はロケールにより異なります。

HTTP リクエストメソッド =POST
正規 URI =/CancelGiftCard
正規クエリ文字列 ='' (空の文字列)

正規ヘッダー =

  accept:application/json
  content-type:application/json
  host:agcod-v2-gamma.amazon.com
  x-amz-date:20130910T222545Z
  x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

または

   accept:application/x-www-form-urlencoded; charset=UTF-8
   content-type:application/x-www-form-urlencoded; charset=UTF-8
   host:agcod-v2-gamma.amazon.com
   x-amz-date:20130910T222449Z
   x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

SignedHeaders=content-type;host;x-amz-date;x-amz-target
Algorithm=AWS4-HMAC-SHA256
Request Date=20130910T222449Z
CredentialScope=20130910/us-east-1/AGCODService/aws4_request
Service Name=AGCODService
Creation Request Id=AwssbTSpecTest001
Host=agcod-v2-gamma.amazon.com (該当するエンドポイントを使用)
Region Name=us-east-1 (該当するエンドポイントを使用)
Partner Id=Awssb (パートナー ID を使用)

既知解の V4 署名例

開発を支援するために、架空の Access Key と Secret Key のテスト例を用いて、以下の署名のさまざまな段階の既知解テストを生成しました。署名の各段階の実行方法の詳細については、こちらをご覧ください。こちらのプロセス図も参照してください。

使用するパラメータ

Partner ID: Test
creationRequestId: Test001
AGCODAccess Key: fake-access-key
AGCOD Secret Key: fake-secret-key
Timestamp: 20140205T171524Z

kSecret: あなたのセキュリティクレデンシャル
kDate: 41b8dd5e0d1716ba90401d46b58b12d500accdd2ea9c2b22a2d275946c9d978e
kRegion: 7b47360ce7afbe1b839e0b0e55834df99979a5414bc7f846b17c9374d230d45d
kService: 68136b0a64b2d01c8934370288b46500243645e468f521503e0d1fa73526d409
kSigning: 27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

ハッシュ化されたペイロード

50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

正規リクエスト

POST
/CreateGiftCard
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

ハッシュ化された正規リクエスト

7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

署名する文字列

AWS4-HMAC-SHA256
20140205T171524Z
20140205/us-east-1/AGCODService/aws4_request
7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

派生した署名キー

27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

署名

 e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1

エンドポイント

agcod-v2-gamma.amazon.com

署名済みリクエスト

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=fake-aws-key/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1
<CreateGiftCardRequest>
    <creationRequestId>Test001</creationRequestId>
    <partnerId>Test</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</CreateGiftCardRequest>

エラー処理

インセンティブ API から送信されるすべてのレスポンスには、特定の操作の実行ステータスを記述する status 要素があります。statusCode の値は次の 3 種類です。 SUCCESS、FAILURE、およびRESEND。詳細については、エラー処理を参照してください。

エラーコード

ユーザーのリクエストが無効な場合のエラーを示すために、F2XX を使用します。原因が Amazon 側にある場合は、F1XX 規約を使用します。

Create/Cancel の呼び出しでの特定のエラーレスポンスをシミュレートするために、モックエラーリクエスト ID を提供しました。エラーレスポンスをシミュレートする場合、通常のリクエスト ID に類似するモックエラーリクエスト ID を creationRequestId フィールドに渡してください。残りのフィールドに渡された値は、レスポンスでそのまま返されるだけです。成功したレスポンスをシミュレートするために、F1000 の値をモックエラーリクエスト ID に渡すことができます。詳細については、モックテストの例とエラー処理を参照してください。

Amazon ギフト券コードの取り扱い

Amazon ギフト券コードは金銭的価値があり、極力安全に取り扱う必要があります。機密データ (Amazon ギフト券コード、セキュリティアクセス認証情報など) を安全に取り扱うための管理を実施することをお勧めします。これには、機密情報が格納されるファイルシステム/データベースに対する適切な監査制御の定義も含まれます。秘密鍵認証情報にアクセスする、インセンティブ API ポータルのアカウントのパスワードを、定期的に変更する必要があります。少なくとも 180 日 (6 ヶ月) に 1 回はアクセスキーをローテーションすることをお勧めします。インセンティブ API ポータルでは、いつでも新しいアクセスキーを生成できます。ただし、AGCOD ではキーの自動ローテーションはサポートされていません。

Amazon ギフト券コードは、Amazon とお客様のシステム間での転送中は機密扱いにする必要があります。
Amazon ギフト券コードは保存しないでください。
お客様の施設で Amazon ギフト券コード (転送中または保管中) にアクセスできる場合、安全なデータ処理方法が導入されている必要があります。

詳細については、インセンティブ API データストレージのガイドラインを参照してください。

注：インセンティブ API が CreateGiftCard リクエストに正常に応答した時点から、お客様は Amazon ギフト券コードに対する責任を負います。

トランザクション金額制限

CreateGiftCard の呼び出しは、発行国で許可されている範囲内で、アカウントが承認した通貨コードを指定する必要があります。

国	通貨コード	範囲
オーストラリア	AUD	$ 1 - $ 2 000
カナダ	CAD	$ 0,01 - $ 5 000
フランス	EUR	€ 0,01 - € 5 000
ドイツ	EUR	€ 0,01 - € 5 000
イタリア	EUR	€ 0,01 - € 5 000
日本	JPY	¥ 1 - ¥ 500 000
メキシコ	MXN	$5 - $ 5 000
スペイン	EUR	€ 0,01 - € 5 000
トルコ	TRY	₺ 1 - ₺ 5 000
アラブ首長国連邦	AED	1 AED - 6 000 AED
英国	GBP	£ 0.01 - £ 5 000
米国	USD	$ 0.01 - $ 2 000

デジタルコード作成テストスクリプト

API との連携を確認するには、次のテストを実行します。

テストの説明	テストケースの詳細	予測される結果
1.ギフト券コードの作成	100 円（通貨単位）など、有効な金額の `CreateGiftCard` リクエストを開始し、受信したレスポンスを処理します。	`SUCCESS` レスポンスを受信する必要があります。システムは、要件に基づいてSUCCESS レスポンスを適切に処理する必要があります。
2.ギフト券コードのキャンセル	テスト (1) で作成した `creationRequestId` に対して `CancelGiftCard` リクエストを開始します。	`SUCCESS` レスポンスを受信する必要があります。システムは、要件に基づいてSUCCESS レスポンスを適切に処理する必要があります。
3.冪等性	1000 円（通貨単位）の `CreateGiftCard` リクエストを開始し、受信したレスポンスを処理します。同じ `creationRequestId` で別の `CreateGiftCard` リクエストを送信します。	`SUCCESS` レスポンス、および同じ `gcId` と `claimCode` を受信する必要があります。