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 にアクセス可能です。

手順:

  1. Amazon Pay インテグレーションセントラル へアクセス
  2. インテグレーションチャネルで "Alexa" を選択
    1. "何をお探しですか?" ドロップダウンメニューより、"配送通知機能の設定"を選択
    2. "手順を見る"ボタンをクリック
  3. 公開鍵と秘密鍵のペア の作成
    1. APIアクセスの、"API キー"セクションまでスクロールダウン
    2. APIキーペアの作成から、"キーペアの作成"ボタンをクリック
    3. "何をしたいですか?"は、デフォルトの設定を使用
    4. APIキーペアに識別可能な名前を入力してください。この名前は、複数キーが登録された際に、インテグレーションセントラルで区別するために使用されますので、誰がそのキーを使うのか、何のために使われるのか識別可能な名前が推奨です。
    5. "キーの作成"ボタンをクリックし、公開鍵と秘密鍵のペア を生成
  4. 秘密鍵 と Public Key ID の保存
    1. キーペアを作成すると、秘密鍵 (.pem) ファイルがブラウザに自動的にダウンロードされます。公開鍵は必要ありません。秘密鍵ファイルをセキュアな場所に保存し、Amazon Pay API にアクセスする際にご使用ください。
    2. Public Key ID を保存してください。こちらも Amazon Pay API にアクセスする際に必要になります。秘密鍵ファイルとは異なり、インテグレーションセントラルでいつでもPublic Key ID にアクセス可能です。

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 seller 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 をテストするには、下記が必要です。

  1. 通知を受け取ることができる、これから配送される もしくは配送中の有効な Order の OrderReference ID

  2. 本 API サポート対象の配送会社による tracking number と配送会社コード

  3. 通知を受けとる顧客と紐づけられた有効なアレクサデバイス。

既に配送ずみの Order の tracking number を使うと配達済み通知を、これから配送されるものを使うと配達中通知を受信できます。

Note: 顧客のアレクサデバイスで実際に通知を受信するには、該当のアカウントの Alexa アプリで下記の設定を有効にする必要があります。

  • 「設定」→「通知」→「Amazon でお買い物」→「配送中」
  • 「設定」→「通知」→「Amazon でお買い物」→「配達済み」

なお、US 以外の顧客の場合には、少なくとも一つ以上は Amazon 発送の商品を購入しないと、通知を受け取ることも、こちらの設定を見ることもできません。