Alexa配送通知機能の設定
Amazon Pay Delivery Tracker API を利用して配送追跡用の情報を提供することで、購入者が配送に関する通知を受け取ることができるようになります。この API はチャネル非依存です。つまり、Amazon Pay をどこで使用しても、Delivery Tracker API を使うことができます。
Delivery Tracker API での顧客体験
お客様: アレクサ, 通知を読んで。
配達中通知
アレクサ: Amazon Pay から通知が1件あります。 [セラーセントラルに登録された店舗名] からの商品は [date]までに到着予定です。
配達済み通知
アレクサ: Amazon Pay から通知が1件あります。 [セラーセントラルに登録された店舗名] からの配達が完了しました。
Public Key Id の取得
Amazon Payでは、安全な通信のため非対称暗号を使用しております。そのため、Amazon PayのAPIにアクセスするには、公開鍵と秘密鍵のペアと対応する Public Key ID (キーペアのユニークなAmazon Pay識別子)が必要となります。Amazon Pay のインテグレーションセントラルより、公開鍵と秘密鍵のペアの生成とPublic Key ID にアクセス可能です。
手順:
- Amazon Pay インテグレーションセントラル へアクセス
- インテグレーションチャネルで "Alexa" を選択
- "何をお探しですか?" ドロップダウンメニューより、"配送通知機能の設定"を選択
- "手順を見る"ボタンをクリック
- 公開鍵と秘密鍵のペア の作成
- APIアクセスの、"API キー"セクションまでスクロールダウン
- APIキーペアの作成から、"キーペアの作成"ボタンをクリック
- "何をしたいですか?"は、デフォルトの設定を使用
- APIキーペアに識別可能な名前を入力してください。この名前は、複数キーが登録された際に、インテグレーションセントラルで区別するために使用されますので、誰がそのキーを使うのか、何のために使われるのか識別可能な名前が推奨です。
- "キーの作成"ボタンをクリックし、公開鍵と秘密鍵のペア を生成
- 秘密鍵 と Public Key ID の保存
- キーペアを作成すると、秘密鍵 (.pem) ファイルがブラウザに自動的にダウンロードされます。公開鍵は必要ありません。秘密鍵ファイルをセキュアな場所に保存し、Amazon Pay API にアクセスする際にご使用ください。
- Public Key ID を保存してください。こちらも Amazon Pay API にアクセスする際に必要になります。秘密鍵ファイルとは異なり、インテグレーションセントラルでいつでもPublic Key ID にアクセス可能です。
Note: 秘密鍵は共有しないでください。また、秘密鍵ファイルをダウンロード出来るのはこの一回限りです。もし、秘密鍵を紛失した場合は、再度新しいキーペア作成する必要があります。
API の利用方法
下記の Endpoint, Path, Header に対して HTTP POST リクエストを送信します。
地域 | Endpoint |
---|---|
NA(北アメリカ) | pay-api.amazon.com |
EU | pay-api.amazon.eu |
JP(日本) | pay-api.amazon.jp |
Path: /live/v2/deliveryTrackers
Request headers
Header | 説明 | Type |
---|---|---|
Authorization (必須) |
下記のフォーマットにて、署名アルゴリズム、公開鍵ID、署名されたヘッダ、署名 Signature_Algorithm PublicKeyId=publicKeyId, SignedHeaders=SignedHeaders, Signature=signature |
String |
X-Amz-Pay-Date (必須) |
署名を生成した日時。「YYYYMMDD’T’HHMMS’Z’」のISO 8601フォーマットです。 | String |
Request parameters
Parameter | 説明 | Type |
---|---|---|
amazonOrderReferenceId (必須) |
追跡される配送に紐づけられたOrderのOrder Reference ID(Amazonが採番した受注番号) | String |
trackingNumber (必須) |
配送会社より提供されたtracking number(お問い合わせ番号・追跡番号) | String |
carrierCode (必須) |
商品を顧客に届けるのに使用される配送会社コード Download carrierCode list |
String |
Request と Response のサンプル
Request メッセージの例
POST /live/v2/deliveryTrackers HTTP/1.1
Host: pay-api.amazon.jp
Accept: application/json
Authorization: AMZN-PAY-RSASSA-PSS PublicKeyId=f4fc06fc-c5a7-11e7-abc4-cec278b6b50a, SignedHeaders=content-type;x-amz-pay-date, Signature=4164128ec5d1b9da1700167ab2ccda8125f472c8bb9de447cebf5d741ee317c8
X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json
{
"amazonOrderReferenceId" : "P01-5728498-6728743",
"deliveryDetails" : [{
"trackingNumber" : "1Z999AA10123456784",
"carrierCode" : "UPS"
}]
}
成功時の Response メッセージの例
HTTP/1.1 200 OK
Host: pay-api.amazon.jp
Content-type: application/json
{
"amazonOrderReferenceId" : "P01-5728498-6728743",
"deliveryDetails" : [{
"trackingNumber" : "1Z999AA10123456784",
"carrierCode" : "UPS"
}]
}
成功時の response headers
Header | 説明 |
---|---|
Content-Type | application/json |
成功時の response parameters
Parameter | 説明 | Type |
---|---|---|
amazonOrderReferenceId | 追跡される配送に紐づけられたOrderのOrder Reference ID(Amazonが採番した受注番号) | String |
trackingNumber | 配送会社より提供されたtracking number(お問い合わせ番号・追跡番号) | String |
carrierCode | 商品を顧客に届けるのに使用される配送会社コード | String |
エラー時の Response
HTTP/1.1 400 Bad Request
Content-Type: application/json;
{
"reasonCode": "InvalidParameterValue",
"message": "The amazonOrderReferenceId that you submitted in this request is invalid.”
}
Error response parameters
Parameter | 説明 | Type |
---|---|---|
reasonCode | Machine readable error code エラーコード | String |
message | Human-readable error description エラー詳細 | String |
エラー Response メッセージの例
Request 送信時にエラーが発生した場合、HTTP エラーの Response を受信します。 Delivery Tracker API により発生するエラーコードは下記の通りです:
Status | Error code | message |
---|---|---|
400 | InvalidInputFormat |
The input provided is not in the required format. (入力値のフォーマットが間違っています。) |
400 | InvalidParameterValue |
The [parameterName] parameter is required. ([parameterName]は必須です。) |
400 | InvalidParameterValue |
The amazonOrderReferenceId that you submitted in this request is invalid. (amazonOrderReferenceIdが不正です。) |
400 | InvalidParameterValue |
The trackingNumber or carrierCode that you submitted in this request is invalid. (trackingNumber or carrierCodeが不正です。) |
401 | UnauthorizedAccess |
The specified merchant account is not authorized to execute this request. (指定されたセラーアカウントにはこのRequestを実行する権限がありません。) |
429 | TooManyRequests |
The request is throttled, due to too many requests in a given amount of time. Refer to the throttling limits. (一定期間に大量のリクエストがなされたため、リクエストがスロットリングされました。詳細はスロットリングの制限をご確認ください。) |
500 | InternalServerError |
There was an unknown error in the service. (サービス内でエラーが発生しました。) |
スロットリングの制限
APIを呼び出すとき、Amazon Payは一定期間のリクエスト数に制限をかけます。この制限のことを、スロットリングと呼び、Webサービスを大量のリクエストから保護し、認証されたアクセスが正常に動作することを保証します。
スロットリングの用語の定義と、スロットリングの詳細な説明は、Amazon MWS 開発者ガイド の スロットリング: リクエストを送信できる頻度を制限する を参照ください。
本番 最大クオータ |
本番 回復レート |
Sandbox クオータ |
Sandbox 回復レート |
---|---|---|---|
10 | 1 | 1 | 1 |
テストについて
Amazon Pay の Delivery Tracker API をテストするには、下記が必要です。
-
通知を受け取ることができる、これから配送される もしくは配送中の有効な Order の OrderReference ID
-
本 API サポート対象の配送会社による tracking number と配送会社コード。
-
通知を受けとる顧客と紐づけられた有効なアレクサデバイス。
既に配送ずみの Order の tracking number を使うと配達済み通知を、これから配送されるものを使うと配達中通知を受信できます。
Note: 顧客のアレクサデバイスで実際に通知を受信するには、該当のアカウントの Alexa アプリで下記の設定を有効にする必要があります。
- 「設定」→「通知」→「Amazon でお買い物」→「配送中」
- 「設定」→「通知」→「Amazon でお買い物」→「配達済み」
なお、US 以外の顧客の場合には、少なくとも一つ以上は Amazon 発送の商品を購入しないと、通知を受け取ることも、こちらの設定を見ることもできません。