完成结账调用后,用户会看到更新后的购物车,其中包含税费、运费、折扣和您返回的其他费用。用户确认并提交订单,然后 Google 向您的执行方式端点发送包含订单信息的 JSON 请求。您的网络服务必须接收此订单、对其进行处理,并响应 Google 该订单的状态。
本部分介绍了 Google 发送的订单请求消息格式(称为 SubmitOrderRequestMessage
),以及您必须提供的响应消息的格式(称为 SubmitOrderResponseMessage
)。如需详细了解订单执行方式生命周期,请参阅执行方式概览。
履单实现
您为与端到端订购而构建的端到端订购网络服务必须包含用于接收来自 Google 的订单消息的网址端点。为了处理订单,您的网络服务会收到 JSON 格式的 SubmitOrderRequestMessage
作为来自 Google 的 POST 请求。此请求包含客户订单,包括税费、费用和付款信息。收到提交订单请求后,您的网络服务必须执行以下操作:
- 检查交易资格,例如卡验证或欺诈检测。
- 在您的系统中创建一个订单。
- 授权付款方式,并调用付款处理方的扣款 API(如适用)。
- 使用适当的订单状态进行响应:
CREATED
、CONFIRMED
或REJECTED
。
处理订单后,您的履单代码必须以 SubmitOrderResponseMessage
JSON 消息的形式向 Google 提供响应。
如需详细了解订购端到端执行方式网络服务实现要求,请参阅执行方式概览。
订单请求消息
当客户在端到端订购流程中选择下单时,Google 会通过名为 SubmitOrderRequestMessage
的 JSON 消息向您的网络服务发送请求,其中包含以下数据:
- Intent:每个提交订单请求正文的
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
:订单的总价。您可以选择是否创建 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
。响应还必须包含 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。如需了解详情,请参阅处理付款。 - 通过电子邮件和/或短信处理订单后,立即通知用户。
返回响应
- 如果没有错误,请将 OrderState.
state
设置为CREATED
或CONFIRMED
。 - 如果遇到错误,请将 OrderState.
state
设置为REJECTED
,并添加带有相应 RejectionInfoType 的 RejectionInfo 对象。 - 设置 OrderUpdate.
orderManagementActions
。