Click here for English version
AmazonインセンティブAPIとの統合プロセスについて
Amazon インセンティブAPI導入のご決定をいただき、ありがとうございます。貴社のアプリケーションをAmazonインセンティブのAPIと統合する手順を下記にご説明します。ご不明な点がありましたら、よくある質問(FAQ)をご覧いただくか、incentives-api@amazon.comまでEメールでお問い合わせください 。 お問い合わせの際には「パートナーID」を必ずご記入ください。
統合プロセスの概要
- はじめに - アカウントの作成
- 貴社のアプリケーションをAmazon インセンティブAPIと統合
- アカウントに入金
- アプリケーションを起動
ステップ1:はじめに - アカウントの作成
(a)新しいAmazonアカウントを作成する
入出金履歴の確認、支払いの通知、アラート の受け取りなどのために、APIクライアント向け のポータルサイト( 法人向けAmazonギフト券 ポータルサイト)をご用意しております。このポータルサイトにアクセスするには新しいAmazonアカウントが必要となりますので、以下の手順で作成して下さい。
- Amazon.co.jpにアクセスして新しいAmazonアカウントを作成する。
- 貴社用のアカウント作成には貴社ドメインの電子メールアドレスを使用してください。
重要:私用のショッピング用Amazonアカウントや、既存の「Amazonインセンティブ オンライン注文サイト」用のAmazonアカウントと同じメールアドレスを紐づけないようにしてください。
Note: 作成するアカウントは、法人向けAmazonギフト券 ポータルサイトに通常のログインをするアカウントと、セキュリティ情報を管理するシステム管理者用のAmazonアカウントの二つが必要です。システム管理者用アカウントは、通常ログイン用のアカウントと同一にすることも可能です。別にする場合は二つのアカウントをユーザーとして登録し、一つは法人向けAmazonギフト券 ポータルサイトへの通常のログイン、もう一つのアカウントは特別なセキュリティ関連機能が利用できます。
(b) アカウントのアクセスキー情報をAmazonにメールで知らせる
Eメールにて下記の情報をお送りください。24縲鰀48時間以内に開発環境についてご案内するEメールをお送りします。 (Eメールテンプレートが必要な場合にはこちらをご利用ください:Getting Started Info/アクセスキー情報)
<送信内容>
宛先:incentives-api@amazon.com
Cc:担当営業のメールアドレス
件名:Getting Started Info/アクセスキー情報
本文:
- 上記ステップ1(a)の手順にて作成したAmazonアカウント用のメールアドレス:
- セキュリティ管理の目的で使われる貴社システム管理者用のメールアドレス:
※システム管理者かもしくはAPIのアクセスキー情報やその他のセキュリティ担当者のメールアドレスにすること。上記ステップ1(a)で作成したメールアドレスと同一でも構いません - 貴社技術チームの連絡先(メールアドレス):
※セキュリティ関連の通知やシステムに関する通知(サービスの中断やAPIのアップデートが発生する場合)に連絡させていただきます。必ずチームエイリアスやメーリングリストなどを設定し、特定の個人メールアドレスは避けてください。 - パートナーID
※パートナーIDがない場合には、開発環境のご準備ができませんので、必ず「AmazonインセンティブAPIの利用申込み」を行ってください(ご参考:ページ上部のボタンから「AmazonインセンティブAPIの利用申込み」)
ステップ2:アプリケーションを統合する
貴社システムを以下のいずれかの機能と統合します。
(a)ギフト券コードの発券
(b)ログイン&レシーブ
(c)ウェブアクティベーション
ステップ3:アカウントに入金する
下記の手順にて、Amazonギフト券購入資金を貴社アカウントへ入金します:
- 法人向けAmazonギフト券 ポータルサイトにログインし、メニューにある「送金の方法」より、振り込み先の銀行口座をご確認ください。
- 貴社より、Amazon指定の銀行口座に入金
*AmazonインセンティブAPIをお使いになる初回月一か月分の資金額のご入金をおすすめしております。 - Amazon側にて、着金が確認出来次第、1営業日以内に貴社アカウントへ入金処理を行います。
各企業様・アカウント毎に異なる固有の銀行口座番号を割り当てて、ご入金を管理しています。一括発注アカウントとAPIアカウントを両方ご利用のお客様は、それぞれ銀行口座は異なりますのでご留意ください。
法人向けAmazonギフト券 ポータルサイト: JP | US | CA | FR | IT | ES | DE | UK | UAE | TR | AU | SG
ステップ4:アプリケーションを起動する
- 本番環境(プロダクション)用のAPI アクセスキーを発行します。
- 本番環境(プロダクション)テストを行うにあたり、貴社アプリケーションのコードに書かれた、エンドポイントをテスト用(サンドボックス)から本番用(プロダクション)に書き換えます。
- 各機能の検証項目リストを参照しながら法人向けAmazonギフト券 ポータルサイト内のトランザクションを表示して、本番環境でアプリケーションの動作を検証します。 詳細は、こちらの ビデオ(英語)をご覧ください。
API アクセスキー
アクセスキーは貴社 Incentives APIアカウントの認証情報です。 APIをリクエストする際の署名に必要な情報で、二つの要素で構成されています: アクセスキーID (例: AKIAIOSFODNN7EXAMPLE) 、シークレットアクセスキー (例: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY)。 ユーザー名とパスワードのように、 貴社のすべてのAPIリクエストの認証するためにアクセスキーIDとシークレットアクセスキーのペアを一緒に使うことが必須となります。 他のサービスにおけるユーザー名とパスワードを管理するように、貴社アクセスキーペアの情報は安全に保存してください。アクセスキーの管理
貴社アカウントのアクセスキーの管理は、法人向けポータルサイト内の APIセキュリティ認証情報(AGCOD認証情報)ページ にて行います。アクセスキーの作成、変更、削除
- 法人向けAmazonギフト券 ポータルサイトにログインし、 APIセキュリティ認証情報(AGCOD認証情報)ページを開く
- 環境を選択する (プロダクション環境 または サンドボックス環境).
- アクセスキー の項目にて、 以下の操作を行う
- アクセスキーを作成するには、アクセスキーの作成を選択し、セキュリティ上安全な場所にアクセスキーIDとセキュリティアクセスキーを保存してください。シークレットアクセスキーの表示は一度のみで、アクセスキーを表示したウィンドウを閉じた後には再表示はできません。 アクセスキーを作成した後は、そのキーペアはデフォルトで有効になりますので、すぐにご利用が可能です。
- 有効なアクセスキーを無効にするには、「ディアクティベート」を選択する。
- 無効なアクセスキーを再度有効にするには、「アクティベート」を選択する。
- アクセスキーを削除するには、「削除」を選択する。確認画面にて「キーの削除」を選択する。アクセスキーを削除すると完全に削除されるため、元に戻すことはできませんが、新しいアクセスキーはいつでも作成が可能です。削除できるのは無効なアクセスキーのみです。
Note: キーローテーションを行う場合を除き、有効なアクセスキーは常に一つにしておくようにしてください。
アクセスキーのローテション
セキュリティのベストプラクティスとして、定期的にアクセスキーのローテーションを行うことをお勧めします。 アクセスキーのローテーションは 法人向けポータルサイト内のAPIセキュリティ認証情報(AGCOD認証情報)ページ にて行ってください。 もしAPIセキュリティ認証情報(AGCOD認証情報)ページを参照できない場合には、貴社のシステム管理者に確認してください。(システム管理者のみがこのページにアクセスが可能です。)定期的にアクセスキーをローテーションすることは、セキュリティのベストプラクティスとしてよく知られています。なぜならアクセスキーがアクティブな期間が短くなるので、万が一情報漏洩した際のビジネスインパクトをより小さく抑えられます。定期的にキーローテーションを行うプロセスを確立しておくと、キーローテーションに関わる手順を確実に実行できるので、キーローテーションが恐れるべき作業ではなくなります。
アクセスキーのローテーションの頻度は最低でも180日(もしくは6か月)に1回行うことを推奨します。 キーローテーションの作業を行っていただくために、期限の30日前にはリマインダーのメールが送信されます。もしご質問があれば、貴社営業担当もしくは incentives-api@amazon.com宛にお問い合わせください。
アクセスキーのローテーションを行うためには、以下の手順に従ってください:
- 現在使用しているアクセスキーに加えて、二番目のアクセスキーを作成する
- 貴社アプリケーションにおいて新しいアクセスキーを利用するように変更し、AGCODのAPIリクエストが成功するか確認する。
- 古いアクセスキーの状態を「無効」に変更する。
- 貴社アプリケーションにおいて問題なく期待通りに動作するか確認する。 一度削除したアクセスキーは元に戻せないため、この確認のプロセスは確実に行ってください。
- 無効なアクセスキーを削除する。
よくある質問 (FAQ)
- Q: 貴社のシステム内でのギフト券番号(ClaimCode)の保存のガイドラインについて教えてください。
A: パートナーがギフト券番号(ClaimCode)を保存することは認められていません。 詳しくはインセンティブAPI (AGCOD) データ保存ガイドラインをご参照ください。 - Q: APIの残高を確認するにはどうすればよいですか?
A: 確認する方法は2つあります:- 法人向けAmazonギフト券 ポータルサイトにログインする。
- Balance Inquiry API機能を使用してください(技術仕様書/開発者ガイドを参照してください)
- Q: APIを使用してコードの登録状況を確認できますか?
A: いいえ。コードの登録状況は、外部のパートナー様には開示できません 。 現時点では、コードの登録状況を確認するためのAPIはありません。エンドユーザー様自身ではコードの登録有無はAmazonギフト券を登録するページ(https://www.amazon.co.jp/gc/redeem)で1つずつ登録することにより確認することが可能です。 - Q: 購入資金は必要に応じて追加できますか?
A: 法人向けAmazonギフト券 ポータルサイトで入出金履歴のレポートがダウンロードできますので、貴社アカウントの残高をご確認の上、必要に応じて追加資金の金額をご連絡ください。 - Q: 法人向けAmazonギフト券 ポータルサイトのURLを教えてください。
A: 日本向けURL:https://www.amazon.co.jp/gc/corp/payments/dashboard - Q: 推奨のタイムアウト設定の時間を教えてください。
A: パートナーのアプリケーションにおいて、6秒が推奨のタイムアウト時間です。 - Q: ギフト券番号(ClaimCode)を発行後、キャンセルするまでに時間制限はありますか?
A: ギフト券番号(ClaimCode)発行後のキャンセルは推奨しません。しかしながら、どうしてもキャンセルが必要な場合には、発行後15分以内のみキャンセルが可能です。 - Q: セキュリティはどのようにAPIで動作しますか?
A: 安全なデータ伝送、エンドポイント証明書はSHA-256以上(TLS 1.2)をサポートします。 - 契約締結しているパートナーないしはその指定パートナーにのみ、APIの使用が許可されています。
- リクエストにはAWS v4シグネチャを使用してデジタル署名する必要があります。リクエストに署名するには、AWSサービス、地域、アクション、タイムスタンプ、AWSアクセスキーなどの情報を組み合わせて署名を計算します。 署名を計算した後、要求のヘッダーにパラメータとして、またはクエリ文字列パラメータとして要求に追加します。 AWSは要求を受け取ると、完了した手順と同じ手順を実行して署名を計算します。 AWSは、計算された署名と、要求で送信した署名とを比較します。 署名が一致する場合、要求は処理されます。 署名が一致しない場合、要求は拒否されます。
- Q: 入金も完了したので本番環境が使えるはずですが、本番環境になりません。どうすればよいですか?
A: エンドポイントの書き換えを行っていただく必要がございます。貴社アプリケーションのコードに書かれた、エンドポイントをテスト用(サンドボックス)から本番用(プロダクション)に書き換えてください。
お問い合わせ
incentives-api@amazon.comにご連絡ください。