購入手続きの呼び出しの後、ユーザーは、税金、送料、割引、返されたその他の料金を含む更新されたカートを確認します。ユーザーが注文を確認して送信すると、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
)で応答します。
注文を処理した後、フルフィルメント コードは SubmitOrderResponseMessage
JSON メッセージの形式で Google にレスポンスを返す必要があります。
注文のフルフィルメント エンドツーエンド ウェブサービスの実装要件の詳細については、フルフィルメントの概要をご覧ください。
注文リクエスト メッセージ
注文のエンドツーエンド フロー中にお客様が注文を選択すると、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 }
注文レスポンス メッセージ
リクエストを受信すると、Ordering End-to-End ウェブサービスはリクエストを処理し、次のデータを含む SubmitOrderResponseMessage
を返します。
OrderUpdate
: 注文のステータスと、ユーザーが利用できる注文後のアクション(サポートへの問い合わせ、注文の詳細の表示など)を含むオブジェクト。これは、レスポンスのfinalResponse.richResponse.items[0].structuredResponse.orderUpdate
フィールドで定義します。
注文の更新フィールド
ウェブサービスが SubmitOrderResponseMessage
を送信すると、OrderUpdate
フィールドが含まれます。このフィールドには次のフィールドが含まれます。
actionOrderId
: 注文の一意の ID。システム内で注文を一意に識別し、後続の注文の更新を送信する際に参照するために使用されます。orderState
: 注文の状態を表すOrderState
オブジェクト。orderManagementActions
: ユーザーが注文後に利用できるアクション(カスタマー サポートへの問い合わせ、注文の詳細の表示など)。totalPrice
: 注文の合計金額。PIN の作成は省略することもできます。注文の送信後に注文の合計金額が変更された場合にのみ送信します。
注文のステータスは次のいずれかになります。
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
に設定する必要があります。レスポンスには、エラータイプを記述する RejectionType
オブジェクトを含む RejectionInfo も含める必要があります。
失敗したレスポンスの例
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" } } } ] } } } ] } } }
注文の送信の実装
submit order API を実装する手順は次のとおりです。
検証
- 購入手続きを設定するで説明したように、サービス、カート、プロモーションの検証を行います。
- 必要に応じて、次のいずれかのタイプで RejectionInfo を返します。
RejectionInfoType | ユースケース |
---|---|
UNAVAILABLE_SLOT |
フルフィルメント時間が無効になりました。 |
PROMO_USER_INELIGIBLE |
リクエストの Contact オブジェクトの Email を使用して、ユーザーがプロモーションの対象であることを確認します。プロモーション付き注文の送信を実装するの例をご覧ください。 |
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
。