Thiết lập nút Gửi đơn đặt hàng

Sau lệnh gọi thanh toán, người dùng sẽ xem lại giỏ hàng đã cập nhật, bao gồm cả thuế, phí giao hàng, chiết khấu và các khoản phí khác mà bạn trả về. Người dùng xác nhận và gửi đơn đặt hàng, sau đó Google sẽ gửi một yêu cầu JSON chứa thông tin về đơn đặt hàng đến điểm cuối thực hiện đơn hàng của bạn. Dịch vụ web của bạn phải nhận được đơn đặt hàng này, 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 thông báo phản hồi mà bạn phải cung cấp, 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ề phương thức thực hiện.

Triển khai phương thức thực hiện đơn hàng

Dịch vụ web Đặt hàng hoàn chỉnh mà bạn xây dựng để hoạt động với tính năng Đặt hàng hoàn chỉnh phải bao gồm một điểm cuối URL để nhận thông báo đơ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ả 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ư sau:

  • Kiểm tra điều kiện 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 trình xử lý thanh toán (nếu có).
  • Phản hồi bằng trạng thái thích hợp của đơn đặt hàng: CREATED, CONFIRMED hoặc REJECTED.

Sau khi xử lý đơn đặt hàng, mã thực hiện đơn đặt hàng của bạn phải cung cấp phản hồi dướ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 thực hiện đơn đặt hàng toàn diện, hãy xem phần Tổng quan về phương thức thực hiện.

Thông báo yêu cầu đặt hàng

Khi khách hàng chọn đặt hàng trong quy trình Đặt hàng toàn diện, Google sẽ gửi một yêu cầu đến dịch vụ web của bạn bằng một thông báo JSON có tên là SubmitOrderRequestMessage chứa dữ liệu sau:

  1. Ý định: Trường inputs[0].intent của mọi nội dung yêu cầu gửi đơn đặt hàng chứa giá trị chuỗi actions.intent.TRANSACTION_DECISION.
  2. Đơn đặt hàng: Trường inputs[0].arguments[0].transactionDecisionValue của yêu cầu gửi đơn đặt hàng chứa đối tượng Order đại diện cho đơn đặt hàng mà khách hàng sẽ đặt, cùng với thông tin thanh toán.
  3. Cờ hộp cát: Trường isInSandbox củ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
}

Thông báo phản hồi đơn đặt hàng

Sau khi nhận được yêu cầu, dịch vụ web Toàn diện về đơn đặt hàng sẽ xử lý yêu cầu và gửi lại SubmitOrderResponseMessage chứa 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 mà người dùng có thể thực hiện, 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ường finalResponse.richResponse.items[0].structuredResponse.orderUpdate của phản hồi.

Trường cập nhật đơn đặt hàng

Khi dịch vụ web gửi SubmitOrderResponseMessage, dịch vụ đó sẽ chứa một 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 duy nhất đơn đặt hàng trong hệ thống của bạn 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ượng OrderState đạ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ể thực hiện, chẳng hạn như liên hệ với bộ phận hỗ trợ khách hàng và xem chi tiết đơ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 đơn đặt hàng được gửi.

Đơn đặt hàng có thể ở một trong các trạng thái sau:

  • CREATED: Điểm cuối thực hiện đơn hàng của bạn đã xử lý đơn đặt hàng thành công, nhưng nhà cung cấp chưa xác nhận đơn đặt hàng.
  • CONFIRMED: Điểm cuối thực hiện đơn hàng của bạ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ố và đ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, trong đó có thể có vấn đề về thanh toán.

Nếu bạn đặt trạng thái của một đơn đặt hàng thành REJECTED, hãy chỉ định lý do trong trường rejectionInfo của OrderUpdate. Sử dụng giá trị FoodOrderUpdateExtension.FoodOrderErrors kết hợp với rejectionInfo thuộc 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 không gửi được yêu cầu, SubmitOrderResponseMessage cần đặt OrderState.state thành REJECTED. Phản hồi cũng phải bao gồm RejectionInfo, 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 yêu cầu triển khai đơn đặt hàng

Bạn nên thực hiện các bước sau khi triển khai API gửi đơn đặt hàng.

Xác thực

  1. Thực hiện quy trình 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 quy trình thanh toán.
  2. Trả về RejectionInfo bằng một trong các loại sau đây nếu cần:
RejectionInfoType Trường hợp sử dụng
UNAVAILABLE_SLOT Thời gian thực hiện đơn hàng không còn hợp lệ.
PROMO_USER_INELIGIBLE Sử dụng Email trong đối tượng Contact (Người liên hệ) trong yêu cầu để xác thực điều kiện tham gia chương trình khuyến mãi của người dùng. Xem ví dụ trong phần triển khai tính năng gửi đơn đặt hàng kèm chương trình khuyến mãi.
INELIGIBLE
  • Thông tin người dùng như số điện thoại hoặc email không hợp lệ.
  • Công cụ đánh giá rủi ro phát hiện hành vi gian lận.
PAYMENT_DECLINED Không thể xử lý khoản thanh toán. Ví dụ: vấn đề 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 gặp lỗi xác thực. Bạn có thể cung cấp lý do từ chối cụ thể (không bắt buộc) bằng cách sử dụng FoodOrderUpdateExtension.foodOrderErrors. Xem ví dụ trong phần Xác thực Gửi đơn đặt hàng.

Xử lý khoản thanh toán

  1. Tính toán totalPrice bằng cách thêm giá giỏ hàng, phí, chiết khấu, thuế và tiền boa. totalPrice phải giống với totalPrice được trả về trong CheckoutResponseMessage cộng với thay đổi về số tiền boa nếu người dùng có thể sửa đổi số tiền boa. Hãy xem phần Thay đổi về giá trong quá trình gửi đơn đặt hàng để biết thêm thông tin chi tiết.
  2. Xử lý đơn đặt hàng và khoản thanh toán nếu bạn trả về một phản hồi có trạng thái đơn đặt hàng là CREATED hoặc CONFIRMED.
  3. Đả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 từ giản đồ như mô tả trong phần tạo thư viện ứng dụng.
  4. Sử dụng GoogleProvidedPaymentInstrument.instrumentToken để xử lý khoản thanh toán. Trả về RejectionInfo với loại PAYMENT_DECLINED nếu không thể xử lý khoản thanh toán. Hãy xem phần Xử lý thanh toán để biết thêm thông tin chi tiết.
  5. Thông báo cho người dùng ngay sau khi đơn đặt hàng được xử lý qua Email và/hoặc SMS.

Trả về phản hồi

  1. Đặt OrderState.state thành CREATED hoặc CONFIRMED nếu không có lỗi.
  2. Đặt OrderState.state thành REJECTED nếu gặp lỗi và đưa đối tượng RejectionInfo vào với RejectionInfoType tương ứng.
  3. Thiết lập OrderUpdate.orderManagementActions.
Trước
Thiết lập quy trình thanh toán
Tiếp
Kiểm thử API thực hiện đơn hàng