購入手続きの呼び出しの後、ユーザーは更新されたカートについて、税金、配送料、割引、その他の料金を確認します。ユーザーが注文を確認して送信すると、Google は注文の情報を含む JSON リクエストをフルフィルメント エンドポイントに送信します。ウェブサービスはこの注文を受け取って処理し、注文の状態を Google に返す必要があります。
このセクションでは、Google によって送信される注文リクエスト メッセージの形式(SubmitOrderRequestMessage
)と、提供する必要があるレスポンス メッセージ(SubmitOrderResponseMessage
)の形式について説明します。注文フルフィルメントのライフサイクルの詳細については、フルフィルメントの概要をご覧ください。
注文フルフィルメントの実装
Ordering End-to-End と連携するために構築する Ordering End-to-End ウェブサービスには、Google から注文メッセージを受信するための URL エンドポイントが含まれている必要があります。注文処理のために、ウェブサービスは Google から POST リクエストとして JSON 形式の SubmitOrderRequestMessage
を受け取ります。このリクエストには、税金、手数料、支払い情報などの顧客注文が含まれています。注文送信リクエストを受信すると、ウェブサービスは次のことを行う必要があります。
- カードの確認や不正行為の検出など、取引の適格性を確認する。
- システムで注文を作成します。
- お支払い方法を承認し、該当する場合は決済代行業者の charge API を呼び出します。
- 注文の適切な状態(
CREATED
、CONFIRMED
、またはREJECTED
)で応答します。
注文の処理後、フルフィルメント コードは、Google に SubmitOrderResponseMessage
JSON メッセージの形式でレスポンスを返す必要があります。
エンドツーエンドの注文フルフィルメント ウェブサービスの実装要件の詳細については、フルフィルメントの概要をご覧ください。
注文リクエスト メッセージ
エンドツーエンドの注文フローでお客様が注文を選択すると、Google はウェブサービスに SubmitOrderRequestMessage
という JSON メッセージでリクエストを送信します。これには次のデータが含まれます。
- インテント: すべての送信注文リクエストの本文の
inputs[0].intent
フィールドに、actions.intent.TRANSACTION_DECISION
文字列値が含まれます。 - 注文: 注文送信リクエストの
inputs[0].arguments[0].transactionDecisionValue
フィールドには、顧客の注文と支払いの詳細を表すOrder
オブジェクトが含まれます。 - サンドボックスのフラグ: 注文送信リクエストの
isInSandbox
フィールドは、取引でサンドボックス支払いを使用するかどうかを示します。
注文リクエストの例
次に SubmitOrderRequestMessage
の例を示します。
JSON
{ "user": {}, "conversation": { "conversationId": "CTKbKfUlHCyDEdcz_5PBJTtf" }, "inputs": [ { "intent": "actions.intent.TRANSACTION_DECISION", "arguments": [ { "transactionDecisionValue": { "order": { "finalOrder": { "cart": { "merchant": { "id": "restaurant/Restaurant/QWERTY", "name": "Tep Tep Chicken Club" }, "lineItems": [ { "name": "Spicy Fried Chicken", "type": "REGULAR", "id": "299977679", "quantity": 2, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "39", "nanos": 600000000 } }, "offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "delivery": { "deliveryTimeIso8601": "P0M" } } }, "location": { "coordinates": { "latitude": -33.8376441, "longitude": 151.0868736 }, "formattedAddress": "Killoola St, 1, Concord West NSW 2138", "zipCode": "2138", "city": "Concord West", "postalAddress": { "regionCode": "AU", "postalCode": "2138", "administrativeArea": "NSW", "locality": "Concord West", "addressLines": [ "Killoola St", "1" ] } }, "contact": { "displayName": "Hab Sy", "email": "hab9878.sy@gmail.com", "phoneNumber": "+61000000000", "firstName": "Hab", "lastName": "Sy" } } }, "otherItems": [ { "name": "Delivery fee", "type": "DELIVERY", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "3", "nanos": 500000000 } } }, { "name": "Subtotal", "type": "SUBTOTAL", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "39", "nanos": 600000000 } } } ], "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "AUD", "units": "43", "nanos": 100000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "googleOrderId": "01412971004192156198", "orderDate": "2020-10-22T09:02:06.173Z", "paymentInfo": { "displayName": "Pay when you get your food", "paymentType": "ON_FULFILLMENT" } } } } ] } ], "directActionOnly": true, "isInSandbox": true }
注文レスポンス メッセージ
注文エンドツーエンド ウェブサービスは、リクエストを受信するとリクエストを処理し、次のデータを含む SubmitOrderResponseMessage
を返します。
OrderUpdate
: 注文の状態と、ユーザーが利用できる注文後のアクション(サポートへの問い合わせや注文の詳細の表示など)を含むオブジェクト。これらはレスポンスのfinalResponse.richResponse.items[0].structuredResponse.orderUpdate
フィールドで定義します。
注文更新フィールド
ウェブサービスが SubmitOrderResponseMessage
を送信すると、次のフィールドを含む OrderUpdate
フィールドが含まれます。
actionOrderId
: 注文の一意の ID。システム内で注文を一意に識別し、後続の注文更新情報を送信するときにその注文を参照するために使用されます。orderState
: 注文の状態を表すOrderState
オブジェクト。orderManagementActions
: カスタマー サポートへの問い合わせや注文の詳細の表示など、ユーザーが行える注文後のアクション。totalPrice
: 注文の合計金額。これは省略可能です。注文の送信後に合計金額が変更された場合にのみ送信してください。
注文は次のいずれかの状態になります。
CREATED
: フルフィルメント エンドポイントが注文を正常に処理しましたが、プロバイダはまだ注文を確定していません。CONFIRMED
: フルフィルメント エンドポイントが注文を正常に処理し、プロバイダが注文を確定しました。REJECTED
: 問題が発生し、フルフィルメント エンドポイントで注文を作成または確認できませんでした。これには、支払いに関する問題が含まれることがあります。
注文を REJECTED
ステータスに設定する場合は、OrderUpdate
の rejectionInfo
フィールドに理由を指定します。FoodOrderUpdateExtension.FoodOrderErrors
値を UNKNOWN
型の rejectionInfo
と組み合わせて使用し、説明を指定します。
注文レスポンスの例
次に SubmitOrderResponseMessage
の例を示します。
JSON
{ "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "1603357328160", "orderState": { "state": "CONFIRMED", "label": "Pending" }, "updateTime": "2020-10-22T02:02:08-07:00", "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Call customer service", "openUrlAction": { "url": "tel:+61234561000" } } }, { "type": "VIEW_DETAILS", "button": { "title": "View order details", "openUrlAction": { "url": "https://partner.com/view/orderstatus" } } } ], "receipt": { "userVisibleOrderId": "BXZ-1603357328" } } } } ] } } }
リクエストの失敗
送信リクエストが失敗した場合、SubmitOrderResponseMessage
は OrderState.state
を REJECTED
に設定する必要があります。レスポンスには RejectionInfo も含める必要があります。これには、エラータイプを記述する RejectionType
オブジェクトが含まれます。
失敗レスポンスの例
JSON
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "REJECTED", "label": "Order rejected" }, "updateTime": "2017-05-10T02:30:00.000Z", "rejectionInfo": { "type": "PAYMENT_DECLINED", "reason": "Insufficient funds" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:person@example.com" } } }, { "type": "CALL", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+16505554679" } } }, { "type": "VIEW_DETAILS", "button": { "title": "View order", "openUrlAction": { "url": "https://orderview.partner.com?orderid=sample_action_order_id" } } } ] } } } ] } } }
注文の実装を送信する
注文送信 API を実装する際は、次の手順を行う必要があります。
検証
- 購入手続きを設定するで説明したように、サービス、カート、プロモーションの検証を行います。
- 必要に応じて、次のいずれかのタイプの RejectionInfo を返します。
RejectionInfoType | 使用例 |
---|---|
UNAVAILABLE_SLOT |
フルフィルメント時間が無効になりました。 |
PROMO_USER_INELIGIBLE |
リクエストの Contact オブジェクトのメールを使用して、ユーザーがプロモーションの対象かどうかを確認します。詳しくは、プロモーションを含む注文の送信を実装する方法の例をご覧ください。 |
INELIGIBLE |
|
PAYMENT_DECLINED |
お支払いを処理できません。(残高不足など)がこれに該当します。 |
UNKNOWN |
その他の検証エラーの場合。 |
検証エラーが発生した場合は、OrderState.state
を REJECTED
に設定します。必要に応じて、FoodOrderUpdateExtension.foodOrderErrors
を使用して、拒否の理由を指定できます。注文の検証を送信するの例をご覧ください。
支払いを処理する
- カート価格、手数料、割引、税金、チップを追加して、
totalPrice
を計算します。totalPrice
は、CheckoutResponseMessage で返されるtotalPrice
に、チップ金額の変更(ユーザーがチップを変更できる場合)を加えた値にする必要があります。詳しくは、注文送信中の価格変更をご覧ください。 - 注文ステータスが
CREATED
またはCONFIRMED
のレスポンスを返したら、注文と支払いを処理します。 - クライアント ライブラリを生成するで説明されているように、スキーマから作成された生成型を使用して、有効なレスポンス形式が返されるようにします。
- GoogleProvidedPaymentInstrument
instrumentToken
を使用して、支払いを処理します。支払いを処理できない場合は、タイプPAYMENT_DECLINED
の RejectionInfo を返します。詳しくは、お支払いの処理をご覧ください。 - メールまたは SMS で注文が処理されたらすぐにユーザーに通知します。
レスポンスを返す
- エラーがなければ、OrderState.
state
をCREATED
またはCONFIRMED
に設定します。 - エラーが発生した場合は OrderState.
state
をREJECTED
に設定し、対応する RejectionInfoType を含む RejectionInfo オブジェクトを含めます。 - OrderUpdate.
orderManagementActions
を設定します。