注文を送信する設定

購入手続きの呼び出しの後、ユーザーは、税金、送料、割引、返されたその他の料金を含む更新されたカートを確認します。ユーザーが注文を確認して送信すると、Google からフルフィルメント エンドポイントに注文情報を含む JSON リクエストが送信されます。ウェブサービスは、この注文を受け取って処理し、注文のステータスとともに Google にレスポンスを返す必要があります。

このセクションでは、Google から送信される注文リクエスト メッセージの形式(SubmitOrderRequestMessage)と、指定する必要があるレスポンス メッセージの形式(SubmitOrderResponseMessage)について説明します。注文フルフィルメントのライフサイクルの詳細については、フルフィルメントの概要をご覧ください。

注文フルフィルメントの実装

Ordering End-to-End と連携するように構築する Ordering End-to-End ウェブサービスには、Google から注文メッセージを受信するための URL エンドポイントを含める必要があります。注文処理では、ウェブサービスは Google から POST リクエストとして JSON 形式の SubmitOrderRequestMessage を受信します。このリクエストには、税金、手数料、お支払い情報など、お客様の注文が含まれます。注文送信リクエストを受け取ったウェブサービスは、次の処理を行う必要があります。

  • カードの確認や不正行為の検出など、取引の適格性を確認します。
  • システムで注文を作成します。
  • お支払い方法の承認を行い、必要に応じて決済処理業者の charge API を呼び出します。
  • 注文の適切なステータス(CREATEDCONFIRMEDREJECTED)で応答します。

注文を処理した後、フルフィルメント コードは SubmitOrderResponseMessage JSON メッセージの形式で Google にレスポンスを返す必要があります。

注文のフルフィルメント エンドツーエンド ウェブサービスの実装要件の詳細については、フルフィルメントの概要をご覧ください。

注文リクエスト メッセージ

注文のエンドツーエンド フロー中にお客様が注文を選択すると、Google は、次のデータを含む SubmitOrderRequestMessage という JSON メッセージとともに、ウェブサービスにリクエストを送信します。

  1. インテント: すべての注文送信リクエスト本文の inputs[0].intent フィールドには、actions.intent.TRANSACTION_DECISION 文字列値が含まれています。
  2. 注文: 注文送信リクエストの inputs[0].arguments[0].transactionDecisionValue フィールドには、注文するお客様の注文を表す Order オブジェクトと支払いの詳細が含まれます。
  3. サンドボックス フラグ: 注文送信リクエストの 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 状態に設定する場合は、OrderUpdaterejectionInfo フィールドに理由を指定します。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"
              }
            }
          }
        }
      ]
    }
  }
}

リクエストが失敗しました

送信リクエストが失敗した場合、SubmitOrderResponseMessageOrderState.stateREJECTED に設定する必要があります。レスポンスには、エラータイプを記述する 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 を実装する手順は次のとおりです。

検証

  1. 購入手続きを設定するで説明したように、サービス、カート、プロモーションの検証を行います。
  2. 必要に応じて、次のいずれかのタイプで RejectionInfo を返します。
RejectionInfoType ユースケース
UNAVAILABLE_SLOT フルフィルメント時間が無効になりました。
PROMO_USER_INELIGIBLE リクエストの Contact オブジェクトの Email を使用して、ユーザーがプロモーションの対象であることを確認します。プロモーション付き注文の送信を実装するの例をご覧ください。
INELIGIBLE
  • 電話番号やメールアドレスなどのユーザー情報が有効ではありません。
  • リスクエンジンが不正行為を検出します。
PAYMENT_DECLINED お支払いを処理できません。たとえば、残高不足が原因である可能性があります。
UNKNOWN その他の検証エラーの場合。

検証エラーが発生した場合は、OrderState.stateREJECTED に設定します。必要に応じて、FoodOrderUpdateExtension.foodOrderErrors を使用して、具体的な拒否理由を指定できます。注文の送信の検証の例をご覧ください。

お支払いを処理する

  1. カート内の価格、手数料、割引、税金、チップを合計して totalPrice を計算します。totalPrice は、CheckoutResponseMessage で返された totalPrice と同じである必要があります。また、ユーザーがチップを変更できる場合は、チップ金額の変更も加算する必要があります。詳しくは、注文送信時の価格変更をご覧ください。
  2. 注文ステータスが CREATED または CONFIRMED のレスポンスを返す場合は、注文と支払いを処理します。
  3. クライアント ライブラリの生成で説明されているように、スキーマから作成された生成された型を使用して、有効なレスポンス形式が返されることを確認します。
  4. GoogleProvidedPaymentInstrument.instrumentToken を使用して支払いを処理します。支払いを処理できない場合は、型 PAYMENT_DECLINEDRejectionInfo を返します。詳しくは、支払いを処理するをご覧ください。
  5. 注文の処理が完了したら、メールまたは SMS でお客様に直ちに通知します。

レスポンスを返す

  1. エラーがない場合、OrderState.stateCREATED または CONFIRMED に設定します。
  2. エラーが発生した場合は、OrderState.stateREJECTED に設定し、対応する RejectionInfoType を含む RejectionInfo オブジェクトを含めます。
  3. OrderUpdate を設定します。orderManagementActions