メッセージングAPI v1ユースケースガイド

注文について購入者にメッセージを送る

メッセージAPIとは

The Selling Partner API for Messaging (Messaging API) allows you to create applications that enable sellers to send messages to buyers after they place an order. Sellers can send a variety of message types. These include asking order related questions, arranging a delivery, and more. The Messaging API can send messages to a buyer, even if the buyer has not contacted the seller first. However, you cannot use this API to respond to messages from buyers.

Refer to the Messaging API reference for a list of operations that correspond to the available message types.

用語

Amazon S3 の署名済み URL: AWS セキュリティ認証情報やアクセス権限がなくてもオブジェクトをアップロードできる Amazon S3 バケットの URL。Amazon S3 の署名付き URL はで取得できます。 ステップ 7。アップロード先を作成する。

メッセージの可用性

すべてのメッセージタイプがすべての状況で使用できるわけではありません。注文が発送されたかどうか、出品者のタイプ、注文に対してすでに送信されたメッセージの数など、メッセージの送信可否に影響する要因は多数あります。

メッセージを送信するためのワークフロー

以下は、アプリケーションのユーザー向けです。メッセージの送信は、Messaging API と Uploads API の両方のオペレーションの呼び出しを含む複数のステップからなるプロセスです。メッセージ送信の基本的なワークフローは次のとおりです。

  1. アプリケーションが出品者の最近の注文を表示し、購入者にメッセージを送信したい注文を出品者が
    選択します。

  2. アプリケーションには、販売者が選択した注文に使用できるメッセージタイプが表示されます。を呼び出して、使用可能なメッセージタイプを確認してください。 getMessagingActionsForOrder メッセージング API の操作。

  3. 出品者が注文のメッセージタイプを選択します。

  4. メッセージタイプでカスタムメッセージがサポートされている場合、出品者がカスタムメッセージを入力します。

  5. メッセージタイプで添付ファイルがサポートされている場合、出品者がアプリケーションに添付ファイルをアップロードします。出品者は添付ファイルの名前も入力します。

  6. 出品者がアプリケーションに添付ファイルをアップロードした場合、アプリケーションは次の操作を実行して添付ファイルをAmazon S3バケットにアップロードします。

    • 添付ファイルについて、アップロード先の作成に必要なContent-MD5ハッシュを計算します。

    • アップロードAPIのcreateUploadDestinationオペレーションを呼び出してアップロード先を作成します。

    • 添付ファイルを宛先にアップロードします。

  7. アプリケーションは、出品者がステップ #3 で選択したメッセージタイプに対応するオペレーションを呼び出して、販売者から購入者にメッセージを送信するように要求します。たとえば、アプリケーションが以下を呼び出したとします。 createConfirmOrderDetails 出品者が「注文の詳細を確認」というメッセージタイプを選択した場合の操作。

  8. Amazonが出品者からのメッセージを購入者にEメールで送信します。

    詳細なワークフローについてはチュートリアル:メッセージを送信するを参照してください。

チュートリアル:メッセージを送信する

このチュートリアルでは、出品者から購入者にメッセージを送信できるようにするアプリケーションの作成方法を説明します。

前提条件

このチュートリアルを完了するには、以下が必要です。

ステップ1. 出品者がメッセージを送信したい注文を取得する

  1. 出品者が選択できるように、出品者の最近の注文のリストを表示します。

  2. 出品者が、購入者にメッセージを送信したい注文を選択します。

  3. 出品者が選択した注文にAmazonの注文識別子を関連付けます。

  4. ステップ2. 使用できるメッセージタイプのリストを取得するで参照するために、Amazon注文識別子を保存します。

ステップ2. 使用できるメッセージタイプのリストを取得する

ステップ1. 出品者がメッセージを送信したい注文を取得するのAmazon注文IDを指定して
メッセージAPIのgetMessagingActionsForOrderオペレーションを呼び出し、その注文で使用できるメッセージタイプのリストを取得します。

  1. 以下のパラメーターを渡して、メッセージAPIのgetMessagingActionsForOrderオペレーションを呼び出します。

パスパラメーター:

パラメーター 説明 必須
amazonOrderId Amazonの注文識別子。メッセージを送信する注文を指定します。この値は、ステップ1. 出品者がメッセージを送信したい注文を取得するで取得します。

タイプ:文字列

はい

クエリーパラメーター:

パラメーター 説明 必須
marketplaceIds マーケットプレイス識別子。注文が確定されたマーケットプレイスを指定します。指定できるマーケットプレイスは1つのみです。

タイプ:配列[文字列]

はい

リクエストの例

GET https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805?marketplaceIds=ATVPDKIKX0DER

レスポンス

getMessagingActionsForOrderオペレーションのレスポンススキーマ。

名前説明Schema
_links
optional
プロパティ名がリンク関係タイプで、値がリンクオブジェクトまたはリンクオブジェクトの配列であるオブジェクト。これらのリンクの対象リソースはリソースオブジェクトで、その中に含まれる「_links」オブジェクトはプロパティです。_links
_embedded
optional
プロパティ名がリンク関係タイプで、値がリソースオブジェクトまたはリソースオブジェクトの配列であるオブジェクト。埋め込みリソースは、対象URIから提供される表現の完全な、部分的な、または一貫性のないバージョンである場合があります。_embedded
errors
optional
リクエストが失敗した場合に返されるエラーレスポンスのリスト。ErrorList

_links

名前説明Schema
self
required
IANAに登録された「自己」関係に対応し、リソースのURIを対象とします。LinkObject
actions
required
指定されたamazonOrderIdで実行できるアクション。< LinkObject > array


_embedded

名前Schema
actions
required
< GetMessagingActionResponse >配列

レスポンスの例

{ "_links": { "actions": [ { "href": "/messaging/v1/orders/902-6786204- 8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0 DER", "name": "confirmCustomizationDetails" }, { "href": "/messaging/v1/orders/902-6786204- 8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER" , "name": "negativeFeedbackRemoval" }, { "href": "/messaging/v1/orders/902-6786204- 8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER", "name": "confirmOrderDetails" }, ], "self": { "href": "/messaging/v1/orders/902-6786204- 8179805?marketplaceIds=ATVPDKIKX0DER" } }, "_embedded": { "actions": [ { "_links": { "schema": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema", "name": "confirmCustomizationDetails" }, "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER", "name": "confirmCustomizationDetails" } }, "_embedded": { "schema": { "_links": { "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails/schema", "name": "confirmCustomizationDetails" } }, "type": "object", "name": "confirmCustomizationDetails", "title": "Confirm customization details", "description": "Ask your customer to provide details or verify the customization input provided (name spelling, imagery, initials).", "properties": { "attachments": { "type": "array", "items": { "type": "object", "required": [], "properties": { "fileName": { "type": "string" }, "id": { "type": "string" } } }, "title": "Add attachment", "description": "You can upload text files, PDFs, Word documents, and these image file types: .jpg, .gif, and .png. The total size of attachments must be less than 10 MB.", "x-ui-field-type": "attachments", "maxItems": 5 }, "rawMessageBody": { "type": "string", "title": "Explain why you are contacting and any action you need your customer to take. ", "description": "800 character limit. Only links related to order completion are allowed, no HTML or email addresses.", "x-ui-field-type": "text", "minLength": 1, "maxLength": 800 } }, "required": [ "attachments", "rawMessageBody" ], "$schema": "http://json-schema.org/draft-04/schema#", "x-ui-hidden": null } }, "name": "confirmCustomizationDetails", "title": "Confirm customization details" }, { "_links": { "schema": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema", "name": "negativeFeedbackRemoval" }, "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval?marketplaceIds=ATVPDKIKX0DER", "name": "negativeFeedbackRemoval" } }, "_embedded": { "schema": { "_links": { "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/negativeFeedbackRemoval/schema", "name": "negativeFeedbackRemoval" } }, "type": "object", "name": "negativeFeedbackRemoval", "title": "Request to update negative feedback", "description": "Ask your customer to consider updating their seller feedback rating. You may only send this once per order.", "properties": {}, "required": [], "$schema": "http://json-schema.org/draft-04/schema#", "x-ui-hidden": true } }, "name": "negativeFeedbackRemoval", "title": "Request to update negative feedback" }, { "_links": { "schema": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema", "name": "confirmOrderDetails" }, "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails?marketplaceIds=ATVPDKIKX0DER", "name": "confirmOrderDetails" } }, "_embedded": { "schema": { "_links": { "self": { "href": "/messaging/v1/orders/902-6786204-8179805/messages/confirmOrderDetails/schema", "name": "confirmOrderDetails" } }, "type": "object", "name": "confirmOrderDetails", "title": "Confirm order details", "description": "Ask your customer a specific order-related question prior to shipping their order.", "properties": { "rawMessageBody": { "type": "string", "title": "Explain why you are contacting and any action you need your customer to take. ", "description": "2000 character limit. Only links related to order completion are allowed, no HTML or email addresses.", "x-ui-field-type": "text", "minLength": 1, "maxLength": 2000 } }, "required": [ "rawMessageBody" ], "$schema": "http://json-schema.org/draft-04/schema#", "x-ui-hidden": null } }, "name": "confirmOrderDetails", "title": "Confirm order details" }, ] } }
  1. レスポンスの_embedded.actions配列にスキーマのリストを保存します。各配列要素の_embedded.schemaセクションには、使用できる各メッセージタイプのスキーマがあります。各スキーマのtitle値を使用して、ステップ3. 出品者が選択したメッセージタイプを取得するで出品者が選択するメッセージタイプのリストを作成します。スキーマを使用して、各メッセージタイプに適用されるカスタムメッセージと添付ファイルの表示方法と制限の適用方法を理解してください。詳細については、ステップ4. 出品者からカスタムメッセージテキストを取得する(サポートされている場合)およびステップ5. 出品者から添付ファイルを取得する(サポートされている場合)を参照してください。

  2. パスのリストをレスポンスの_links.actions配列に保存します。各配列要素のhref値には、使用できる各メッセージタイプのパスが含まれます。これらのパスは、 ステップ9. 購入者にメッセージを送信するで、適切なオペレーションの呼び出しに使用できます。

ステップ3. 出品者が選択したメッセージタイプを取得する

  1. 出品者が選択できるように、使用できるメッセージタイプのリストを表示します。このリストは、ステップ2. 使用できるメッセージタイプのリストを取得するで保存したtitle値から取得します。

  2. 送信するメッセージタイプを出品者に選択させ、保存します。この選択は、以下を含め、後続のいくつかのステップに影響します。

ステップ4. 出品者からカスタムメッセージテキストを取得する(サポートされている場合)

一部のメッセージタイプでは、出品者が購入者へのEメールにカスタムメッセージを含めることができます。メッセージタイプがカスタムメッセージをサポートしているかどうかを確認するには、メッセージAPIリファレンスでメッセージタイプに対応するオペレーションを参照してください。たとえば、createConfirmServiceDetailsオペレーションは「ホームサービスのお客様への連絡」メッセージタイプに対応しています。オペレーションにテキスト本文パラメーターが含まれている場合、そのメッセージタイプはカスタムメッセージをサポートしています。

  1. 出品者がステップ3. 出品者が選択したメッセージタイプを取得するで選択したメッセージタイプがカスタムメッセージをサポートしているかどうかを判断します。カスタムメッセージがサポートされていない場合は、このままステップ5. 出品者から添付ファイルを取得する(サポートされている場合)に進みます。カスタムメッセージがサポートされている場合は、こちらの手順を続行してください。

  2. 出品者に、カスタムメッセージとして使用するテキストを入力させます。

  3. 出品者が入力するメッセージテキストに制限が設けられている場合はその内容を表示して、制限を適用します。テキスト制限は、出品者のメッセージタイプに対応する_embedded.actions配列要素の_embedded.schema.properties.rawMessageBodyセクションにあります。この配列は、ステップ2. 使用できるメッセージタイプのリストを取得するgetMessagingActionsForOrderオペレーションのレスポンスに含まれています。

  4. メッセージテキストを保存し、 ステップ9. 購入者にメッセージを送信するの入力として使用します。

ステップ5. 出品者から添付ファイルを取得する(サポートされている場合)

一部のメッセージタイプでは、出品者が購入者へのEメールに添付ファイルへのリンクを含めることができます。メッセージタイプが添付ファイルをサポートしているかどうかを確認するには、メッセージAPIリファレンスでメッセージタイプに対応するオペレーションを参照してください。たとえば、createWarrantyオペレーションは「保証情報の送信」メッセージタイプに対応しています。オペレーションに添付ファイル本文パラメーターが含まれている場合、そのメッセージタイプは添付ファイルをサポートしています。

  1. 出品者がステップ3. 出品者が選択したメッセージタイプを取得するで選択したメッセージタイプが添付ファイルをサポートしているかどうかを判断します。添付ファイルがサポートされていない場合は、このままステップ9. 購入者にメッセージを送信するに進みます。添付ファイルがサポートされている場合は、こちらの手順を続行してください。

  2. 出品者に添付ファイルをアプリケーションにアップロードさせます。

  3. 出品者がアップロードする添付ファイルに制限が設けられている場合はその内容を表示して、制限を適用します。添付ファイルの制限は、出品者のメッセージタイプに対応する_embedded.actions配列要素の_embedded.schema.properties.attachmentsセクションにあります。この配列は、ステップ2. 使用できるメッセージタイプのリストを取得するgetMessagingActionsForOrderオペレーションのレスポンスに含まれています。

  4. 添付ファイルを入力ストリームに変換して、ステップ8. 添付ファイルをアップロードするで使用するために保存します。

  5. 出品者に、ファイル拡張子を含む添付ファイルの名前を入力させます。

  6. ファイル名を保存し、ステップ9. 購入者にメッセージを送信するの入力として使用します。

ステップ6. Content-MD5ハッシュを計算する

ステップ5. 出品者から添付ファイルを取得する(サポートされている場合)の添付ファイルに対してContent-MD5ハッシュを計算します。これは、ステップ7. アップロード先を作成するでアップロード先を作成する際に必要になります。

このステップのJavaサンプルコードには、Content-MD5ハッシュを計算するためのロジックが含まれています。このサンプルコードではApache HTTPクライアントを使用しています。

  1. サンプルコードの入力に以下を使用します。

ステップ5. 出品者から添付ファイルを取得する(サポートされている場合)の添付ファイル入力ストリームは、CreateMD5クラスのcomputeContentMD5Valueメソッドのfisパラメーターに対する引数です。

  1. ステップ7. アップロード先を作成するContent-MD5パラメーターで渡すために、md5Content値を保存します。

サンプルJavaコード

package io.swagger.client.util; import java.io.FileInputStream; import java.io.IOException; import java.security.DigestInputStream; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; public class CreateMD5 { public static String computeContentMD5Value(FileInputStream fis) throws IOException, NoSuchAlgorithmException { DigestInputStream dis = new DigestInputStream(fis, MessageDigest.getInstance("MD5")); byte[]buffer = new byte[8192]; while (dis.read(buffer) > 0); String md5Content = new String(org.apache.commons.codec.binary.Base64 .encodeBase64(dis.getMessageDigest().digest())); // Effectively resets the stream to be beginning of the file // via a FileChannel. fis.getChannel().position(0); return md5Content; } }

ステップ7. アップロード先を作成する

アップロードAPIのcreateUploadDestinationオペレーションを呼び出し、Amazon S3署名済みURLの形式で添付ファイルのアップロード先を作成します。定義については、用語を参照してください。

  1. 以下のパラメーターを渡して、アップロードAPIのcreateUploadDestinationオペレーションを呼び出します。

クエリーパラメーター:

Type名前説明Schema
QuerymarketplaceIds
required
マーケットプレイス識別子のリスト。これにより、アップロードできるマーケットプレイスを指定できます。指定できるマーケットプレイスは1つだけです。
最大数 : 1
< 文字列 >配列
Queryコンテンツ MD5
required
計算に使用したコンテンツ MD5 ハッシュ ステップ 6。コンテンツ MD5 ハッシュを計算するstring
Path資源
required
作成しているアップロード先のリソース。たとえば、Messaging API の CreateLegalDisclosure オペレーション用のアップロード先を作成する場合、 {resource} だろう /messaging/v1/orders/{amazonOrderId}/messages/legalDisclosureそして、全体のパスは /uploads/2020-11-01/uploadDestinations/messaging/v1/orders/{amazonOrderId}/messages/legalDisclosure。Aplus コンテンツドキュメントのアップロード先を作成する場合、 {resource} だろう aplus/2020-11-01/contentDocuments そしてその道は /uploads/v1/uploadDestinations/aplus/2020-11-01/contentDocumentsstring
QuerycontentType
optional
アップロードするファイルのコンテンツタイプ。string

リクエストの例

POST https://sellingpartnerapi-na.amazon.com/uploads/2020-11-01/uploadDestinations/messaging/v1/orders/7XX-5XXXXX-8XXXXXX/messages/invoice?marketplaceIds=A2Q3Y263D00KWC&contentMD5=qCcR3o%2BU0FUR1%2BgXhApNfQ%3D%3D

レスポンス

createUploadDestinationオペレーションのレスポンススキーマ。

名前説明Schema
payload
optional
アップロード先に関する情報。UploadDestination
errors
optional
リクエストが失敗した場合に返されるエラーレスポンスのリスト。ErrorList

レスポンスの例

{ "payload": { "uploadDestinationId": "sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png", "url": "https://aplus-media.s3.amazonaws.com/?x-amz-date=20201116T184623Z&x-amz-signature=c5c8efd95d883b6787a2b1a93c7c066f01cb4e8d7be3ece4360aa800332e0cf9&x-amz-meta-owner=A2CZ04NGKYDXDV&acl=private&key=sc/7ae2d3b1-fdd3-42c4-98c4-9cc509fb95d8.png&x-amz-algorithm=AWS4-HMAC-SHA256&policy=eyJjb25kaXRpb25zIjpbeyJidWNrZXQiOiJhcGx1cy1tZWRpYS1iZXRhIn0seyJrZXkiOiJzb3RhLzdhZTJkM2IxLWZkZDMtNDJjNC05OGM0LTljYzUwOWZiOTVkOC5wbmcifSx7ImFjbCI6InByaXZhdGUifSx7IngtYW16LW1ldGEtb3duZXIiOiJBMkNaMDROR0tZRFhEViJ9LHsieC1hbXotYWxnb3JpdGhtIjoiQVdTNC1ITUFDLVNIQTI1NiJ9LHsieC1hbXotY3JlZGVudGlhbCI6IkFLSUE2TDZSN1FFNTZGNkdNRzVFLzIwMjAxMTE2L3VzLWVhc3QtMS9zMy9hd3M0X3JlcXVlc3QifSx7IngtYW16LWRhdGUiOiIyMDIwMTExNlQxODQ2MjNaIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMSwzMTQ1NzI4XV0sImV4cGlyYXRpb24iOiIyMDIwLTExLTE2VDIxOjQ2OjIzLjg2OFoifQ==&x-amz-credential=AKIA6L6R7QE56F6GMG5E/20201116/us-east-1/s3/aws4_request", "headers": { "Content-MD5": "1jnGuPv7xwPiat6NesKL/w==" } } }
  1. 次の値を保存します。

ステップ8. 添付ファイルをアップロードする

出品者がステップ5. 出品者から添付ファイルを取得する(サポートされている場合)でアプリケーションにアップロードした添付ファイルをAmazon S3バケットにアップロードします。

このステップのJavaサンプルコードには、添付ファイルをアップロードするためのロジックが含まれています。このサンプルコードではApache HTTPクライアントを使用しています。

サンプルコードの入力に以下を使用します。

サンプルJavaコード

package io.swagger.client.util; import java.io.IOException; import java.io.OutputStreamWriter; import java.net.HttpURLConnection; import java.net.URL; import java.util.Map; import io.swagger.client.model.CreateUploadDestinationResponse; public class UploadFileToDestination { private static String requestMethod = "PUT"; private static String contentType = "Content-Type"; private static String contentValue = "application/text"; private static URL url; private static Map < String, String > headers; /* Upload file to destination using the response returned in CreateUploadDestination. Reference https://docs.aws.amazon.com/AmazonS3/latest/dev/PresignedUrlUploadObjectJavaSDK.html) */ public static void uploadFileInDestination( CreateUploadDestinationResponse uploadDestinationPayload) throws IOException { url = new URL(uploadDestinationPayload.getPayload().getUrl()); headers = (Map < String, String > )uploadDestinationPayload.getPayload() .getHeaders(); // Create the connection and use it to upload the new object using the // pre-signed URL. HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setDoOutput(true); connection.setRequestMethod(requestMethod); connection.setRequestProperty(contentType, contentValue); // headers that are returned in createDestination call for (Map.Entry < String, String > headersEntry: headers.entrySet()) { connection.setRequestProperty(headersEntry.getKey(), headersEntry.getValue()); } OutputStreamWriter out = new OutputStreamWriter( connection.getOutputStream()); out.write("Text of the file"); out.close(); // Check the HTTP response code. To complete the upload and make the // object available, // you must interact with the connection object in some way. connection.getResponseCode(); System.out.println("HTTP response code: " + connection.getResponseCode() + connection.getResponseMessage()); connection.disconnect(); } }

添付ファイルがAmazon S3バケットにアップロードされます。

ステップ9. 購入者にメッセージを送信する

To send a message from the seller to the buyer you need to call the operation that corresponds to the message type that the seller chose in Step 2. Get a list of available message types. For example, if the seller chose the "Confirm customization details" message type, you would call the confirmCustomizationDetails operation. Refer to the Messaging API reference for the list of operations that are available. In this example, we will call the confirmCustomizationDetails operation.

  1. 以下のパラメーターを渡して、メッセージAPIのconfirmCustomizationDetailsオペレーションを呼び出します。

パスのパラメーター:

パラメーター 説明 必須
amazonOrderId Amazonの注文識別子。メッセージを送信する注文を指定します。ステップ1. 出品者がメッセージを送信したい注文を取得するで保存したAmazon注文識別子を使用します。

タイプ:文字列

はい

クエリーパラメーター:

パラメーター 説明 必須
marketplaceIds マーケットプレイス識別子。注文が確定されたマーケットプレイスを指定します。指定できるマーケットプレイスは1つのみです。

タイプ:配列[文字列]

はい

ボディのパラメーター:

パラメーター 説明 必須
text 購入者へのEメールに含めるカスタムメッセージ。ステップ4. 出品者からカスタムメッセージテキストを取得する(サポートされている場合)のメッセージテキストを使用します。

タイプ:文字列

はい
attachments 購入者へのメッセージに含める添付ファイル はい

リクエストの例

POST https://sellingpartnerapi-na.amazon.com/messaging/v1/orders/902-6786204-8179805/messages/confirmCustomizationDetails?marketplaceIds=ATVPDKIKX0DER { "text": "This is the message from the seller to the buyer that will appear in the email to the buyer.", "attachments": [ { "uploadDestinationId": "4370d51b-2954-445c-9f30-EXAMPLE6b9de", "fileName": "example.txt" } ] }

レスポンス

応答はありません。代わりに、Amazonは出品者のメッセージを購入者にEメールで送信します。


このページは役に立ちましたか?