Sau cuộc gọi thanh toán, người dùng xem lại giỏ hàng mới cập nhật, trong đó có các khoản thuế, phí giao hàng, chiết khấu và các khoản phí khác mà bạn trả lại. Người dùng xác nhận và gửi đơn đặt hàng, đồng thời Google sẽ gửi điểm cuối thực hiện đơn hàng của bạn một yêu cầu JSON chứa thông tin về đơn đặt hàng. Dịch vụ web của bạn phải nhận, xử lý đơn đặt hàng và phản hồi lại cho Google về trạng thái của đơn đặt hàng.
Phần này mô tả định dạng thông báo yêu cầu đặt hàng do Google gửi, gọi là SubmitOrderRequestMessage và định dạng của thông báo phản hồi bạn phải cung cấp, được gọi là SubmitOrderResponseMessage.
Để biết thêm thông tin về vòng đời thực hiện đơn đặt hàng, hãy xem bài viết Tổng quan về việc thực hiện đơn hàng.
Triển khai phương thức thực hiện đơn đặt hàng
Dịch vụ web Đặt hàng hai đầu mà bạn tạo để hoạt động với dịch vụ Đặt hàng hai đầu phải bao gồm điểm cuối URL để nhận thông báo về đơn đặt hàng từ Google. Để xử lý đơn đặt hàng, dịch vụ web của bạn sẽ nhận được SubmitOrderRequestMessage ở định dạng JSON dưới dạng yêu cầu POST từ Google. Yêu cầu này chứa đơn đặt hàng của khách hàng,
bao gồm các khoản thuế, phí và thông tin thanh toán. Khi nhận được yêu cầu gửi đơn đặt hàng, dịch vụ web của bạn phải làm những việc sau:
- Kiểm tra điều kiện của giao dịch, chẳng hạn như xác minh thẻ hoặc phát hiện gian lận.
- Tạo đơn đặt hàng trong hệ thống của bạn.
- Uỷ quyền phương thức thanh toán và gọi API tính phí của công ty xử lý thanh toán (nếu có).
- Phản hồi với trạng thái thích hợp của đơn đặt hàng:
CREATED,CONFIRMEDhoặcREJECTED.
Sau khi xử lý đơn đặt hàng, mã thực hiện đơn hàng của bạn phải cung cấp phản hồi ở dạng thông báo JSON SubmitOrderResponseMessage cho Google.
Để biết thêm thông tin về các yêu cầu triển khai dịch vụ web về phương thức thực hiện thứ tự hai đầu, hãy xem bài viết Tổng quan về việc thực hiện đơn hàng.
Tin nhắn yêu cầu đặt hàng
Khi khách hàng chọn đặt hàng trong quy trình Đặt hàng từ đầu đến cuối, Google sẽ gửi yêu cầu đến dịch vụ web của bạn bằng thông báo JSON có tên là SubmitOrderRequestMessage chứa dữ liệu sau:
- Ý định: Trường
inputs[0].intentcủa mỗi nội dung yêu cầu gửi đơn đặt hàng chứa giá trị chuỗiactions.intent.TRANSACTION_DECISION. - Đơn đặt hàng: Trường
inputs[0].arguments[0].transactionDecisionValuecủa yêu cầu gửi đơn đặt hàng chứa đối tượngOrderđại diện cho đơn đặt hàng của khách hàng cùng với thông tin thanh toán. - Cờ hộp cát: Trường
isInSandboxcủa yêu cầu gửi đơn đặt hàng cho biết giao dịch có sử dụng phương thức thanh toán trong hộp cát hay không.
Ví dụ về yêu cầu đặt hàng
Sau đây là ví dụ về 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
}
Tin nhắn phản hồi đơn đặt hàng
Sau khi nhận được yêu cầu, dịch vụ web Đặt hàng hai đầu của bạn sẽ xử lý yêu cầu và gửi lại SubmitOrderResponseMessage bao gồm các dữ liệu sau:
OrderUpdate: Một đối tượng chứa trạng thái của đơn đặt hàng và mọi thao tác sau khi đặt hàng có sẵn cho người dùng, chẳng hạn như liên hệ với nhóm hỗ trợ và xem thông tin chi tiết về đơn đặt hàng mà bạn xác định trong trườngfinalResponse.richResponse.items[0].structuredResponse.orderUpdatecủa phản hồi.
Trường cập nhật đơn đặt hàng
Khi dịch vụ web của bạn gửi một SubmitOrderResponseMessage, dịch vụ đó sẽ chứa trường OrderUpdate bao gồm các trường sau:
actionOrderId: Mã nhận dạng duy nhất của đơn đặt hàng, dùng để xác định riêng một đơn đặt hàng trong hệ thống và tham chiếu đến đơn đặt hàng đó khi gửi thông tin cập nhật đơn đặt hàng tiếp theo.orderState: Đối tượngOrderStateđại diện cho trạng thái của đơn đặt hàng.orderManagementActions: Các thao tác sau khi đặt hàng mà người dùng có thể sử dụng, chẳng hạn như liên hệ với nhóm hỗ trợ khách hàng và xem thông tin chi tiết về đơn đặt hàng.totalPrice: Tổng giá của đơn đặt hàng. Việc này là không bắt buộc. Chỉ gửi nếu tổng giá của đơn đặt hàng đã thay đổi sau khi gửi đơn đặt hàng.
Đơn đặt hàng có thể ở một trong các trạng thái sau:
CREATED: Điểm cuối của phương thức thực hiện đã xử lý thành công đơn đặt hàng nhưng trình cung cấp chưa xác nhận đơn đặt hàng.CONFIRMED: Điểm cuối của phương thức thực hiện đã xử lý đơn đặt hàng thành công và nhà cung cấp đã xác nhận đơn đặt hàng.REJECTED: Đã xảy ra sự cố nên điểm cuối thực hiện đơn hàng của bạn không thể tạo hoặc xác nhận đơn đặt hàng, có thể dẫn đến các vấn đề về việc thanh toán.
Nếu bạn đặt đơn đặt hàng ở trạng thái REJECTED, hãy chỉ định lý do trong trường rejectionInfo của OrderUpdate. Sử dụng các giá trị FoodOrderUpdateExtension.FoodOrderErrors kết hợp với rejectionInfo của loại UNKNOWN và cung cấp nội dung mô tả.
Ví dụ về phản hồi đơn đặt hàng
Sau đây là ví dụ về 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"
}
}
}
}
]
}
}
}
Yêu cầu không thành công
Nếu yêu cầu gửi không thành công, SubmitOrderResponseMessage cần đặt OrderState.state thành REJECTED. Phản hồi cũng phải bao gồm RejectionInfo, trong đó chứa đối tượng RejectionType để mô tả loại lỗi.
Ví dụ về phản hồi không thành công
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"
}
}
}
]
}
}
}
]
}
}
}
Gửi phương thức triển khai đơn đặt hàng
Bạn nên thực hiện các bước sau đây khi triển khai API đơn đặt hàng gửi đi.
Xác nhận kết quả
- Thực hiện xác thực dịch vụ, giỏ hàng và chương trình khuyến mãi như thực hiện trong phần Thiết lập thanh toán.
- Nếu cần, hãy trả về RejectionInfo (Thông tin từ chối) bằng một trong các loại sau:
| RejectionInfoType | Trường hợp sử dụng |
|---|---|
UNAVAILABLE_SLOT |
Thời gian thực hiện không còn hợp lệ. |
PROMO_USER_INELIGIBLE |
Sử dụng Email trong đối tượng Liên hệ trong yêu cầu để xác thực xem người dùng có đủ điều kiện hưởng chương trình khuyến mãi hay không. Hãy xem ví dụ trong nội dung triển khai đơn đặt hàng có chương trình khuyến mãi. |
INELIGIBLE |
|
PAYMENT_DECLINED |
Không xử lý được khoản thanh toán. Ví dụ: Điều này có thể là do không có đủ tiền. |
UNKNOWN |
Đối với mọi lỗi xác thực khác. |
Đặt OrderState.state thành REJECTED nếu xảy ra lỗi xác thực. Nếu muốn, bạn có thể đưa ra lý do từ chối cụ thể bằng cách sử dụng FoodOrderUpdateExtension.foodOrderErrors. Xem ví dụ trong bài viết Xác thực đơn đặt hàng.
Xử lý khoản thanh toán
- Tính
totalPricebằng cách thêm giá giỏ hàng, phí, chiết khấu, thuế và tiền thưởng.totalPricephải giống vớitotalPriceđược trả về trong CheckoutResponseMessage cộng với thay đổi về số tiền thưởng nếu người dùng có thể sửa đổi khoản tiền thưởng. Hãy xem bài viết Thay đổi về giá trong khi gửi đơn đặt hàng để biết thêm thông tin chi tiết. - Xử lý đơn đặt hàng và thanh toán nếu bạn trả về phản hồi có trạng thái đơn đặt hàng là
CREATEDhoặcCONFIRMED. - Đảm bảo rằng định dạng phản hồi hợp lệ được trả về bằng cách sử dụng các loại được tạo được tạo từ giản đồ như mô tả trong phần tạo thư viện ứng dụng.
- Sử dụng GoogleProvidedPaymentInstrument.
instrumentTokenđể xử lý khoản thanh toán. Trả về RejectionInfo với loạiPAYMENT_DECLINEDnếu không xử lý được khoản thanh toán. Hãy xem bài viết Quy trình thanh toán để biết thêm thông tin chi tiết. - Thông báo cho người dùng ngay sau khi đơn đặt hàng được xử lý qua email và SMS.
Trả lời
- Đặt OrderState.
statethànhCREATEDhoặcCONFIRMEDnếu không có lỗi. - Đặt OrderState.
statethànhREJECTEDnếu có lỗi, đồng thời thêm đối tượng RejectionInfo cùng với loại thông tin RejectionInfoType tương ứng. - Thiết lập OrderUpdate.
orderManagementActions.