Menyiapkan Kirim pesanan

Setelah panggilan checkout, pengguna akan meninjau keranjang yang diperbarui dengan pajak, biaya pengiriman, diskon, dan tagihan lainnya yang Anda tampilkan. Pengguna mengonfirmasi dan mengirimkan pesanan, lalu Google mengirimkan permintaan JSON yang berisi informasi untuk pesanan tersebut ke endpoint fulfillment Anda. Layanan web Anda harus menerima pesanan ini, memprosesnya, dan merespons kembali ke Google dengan status pesanan.

Bagian ini menjelaskan format pesan permintaan pesanan yang dikirim oleh Google, yang disebut SubmitOrderRequestMessage, dan format pesan respons yang harus Anda berikan, yang disebut SubmitOrderResponseMessage. Untuk mengetahui informasi selengkapnya tentang siklus proses fulfillment pesanan, lihat Ringkasan fulfillment.

Penerapan fulfillment pesanan

Layanan web Pemesanan Menyeluruh yang Anda buat agar berfungsi dengan Pemesanan Menyeluruh harus menyertakan endpoint URL untuk menerima pesan pesanan dari Google. Untuk pemrosesan pesanan, layanan web Anda menerima SubmitOrderRequestMessage dalam format JSON sebagai permintaan POST dari Google. Permintaan ini berisi pesanan pelanggan, termasuk pajak, biaya, dan informasi pembayaran. Setelah menerima permintaan kirim pesanan, layanan web Anda harus melakukan hal berikut:

  • Memeriksa kelayakan transaksi, seperti verifikasi kartu atau deteksi penipuan.
  • Buat pesanan di sistem Anda.
  • Otorisasi metode pembayaran dan panggil API tagihan pemroses pembayaran Anda jika berlaku.
  • Respons dengan status pesanan yang sesuai: CREATED, CONFIRMED, atau REJECTED.

Setelah memproses pesanan, kode fulfillment Anda harus memberikan respons dalam bentuk pesan JSON SubmitOrderResponseMessage kembali ke Google.

Untuk mengetahui informasi selengkapnya tentang persyaratan penerapan layanan web fulfillment Pesanan menyeluruh, lihat Ringkasan fulfillment.

Pesan permintaan pesanan

Saat pelanggan memilih untuk melakukan pemesanan selama alur Pemesanan Lengkap, Google akan mengirimkan permintaan ke layanan web Anda dengan pesan JSON yang disebut SubmitOrderRequestMessage yang berisi data berikut:

  1. Intent: Kolom inputs[0].intent dari setiap isi permintaan kirim pesan berisi nilai string actions.intent.TRANSACTION_DECISION.
  2. Pesanan: Kolom inputs[0].arguments[0].transactionDecisionValue dari permintaan kirim pesanan berisi objek Order yang mewakili pesanan pelanggan yang akan dilakukan, beserta detail pembayaran.
  3. Flag sandbox: Kolom isInSandbox dari permintaan kirim pesanan menunjukkan apakah transaksi menggunakan pembayaran sandbox.

Contoh permintaan pesanan

Berikut adalah contoh 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
}

Pesan respons pesanan

Setelah menerima permintaan, layanan web Ordering End-to-End Anda akan memproses permintaan dan mengirimkan kembali SubmitOrderResponseMessage yang menyertakan data berikut:

  • OrderUpdate: Objek yang berisi status pesanan, dan tindakan pasca-pesanan apa pun yang tersedia bagi pengguna, seperti menghubungi dukungan dan melihat detail pesanan, yang Anda tentukan di kolom finalResponse.richResponse.items[0].structuredResponse.orderUpdate respons.

Kolom pembaruan pesanan

Saat layanan web Anda mengirim SubmitOrderResponseMessage, layanan tersebut berisi kolom OrderUpdate yang menyertakan kolom berikut:

  • actionOrderId: ID unik pesanan, yang digunakan untuk mengidentifikasi pesanan secara unik di sistem Anda dan merujuknya saat mengirim pembaruan pesanan berikutnya.
  • orderState: Objek OrderState yang mewakili status pesanan.
  • orderManagementActions: Tindakan pasca-pesanan yang tersedia bagi pengguna, seperti menghubungi dukungan pelanggan dan melihat detail pesanan.
  • totalPrice: Harga total pesanan. Langkah ini bersifat opsional. Hanya kirim jika total harga pesanan telah berubah setelah pesanan dikirim.

Pesanan dapat berada dalam salah satu status berikut:

  • CREATED: Endpoint fulfillment Anda berhasil memproses pesanan, tetapi penyedia belum mengonfirmasi pesanan.
  • CONFIRMED: Endpoint fulfillment Anda berhasil memproses pesanan, dan penyedia telah mengonfirmasi pesanan.
  • REJECTED: Terjadi masalah dan endpoint fulfillment Anda tidak dapat membuat atau mengonfirmasi pesanan, yang dapat mencakup masalah pembayaran.

Jika Anda menetapkan urutan ke status REJECTED, tentukan alasannya di kolom rejectionInfo dari OrderUpdate. Gunakan nilai FoodOrderUpdateExtension.FoodOrderErrors bersama dengan rejectionInfo dari jenis UNKNOWN dan berikan deskripsi.

Contoh respons pesanan

Berikut adalah contoh 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"
              }
            }
          }
        }
      ]
    }
  }
}

Permintaan gagal

Jika permintaan pengiriman gagal, SubmitOrderResponseMessage harus menetapkan OrderState.state ke REJECTED. Respons juga harus menyertakan RejectionInfo, yang berisi objek RejectionType untuk mendeskripsikan jenis error.

Contoh respons yang gagal

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"
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Mengirim penerapan pesanan

Langkah-langkah berikut harus dilakukan saat menerapkan API kirim pesanan.

Validasi

  1. Lakukan validasi layanan, keranjang, dan promosi seperti yang dilakukan di Menyiapkan Checkout.
  2. Tampilkan RejectionInfo dengan salah satu jenis berikut jika diperlukan:
RejectionInfoType Kasus penggunaan
UNAVAILABLE_SLOT Waktu fulfillment tidak lagi valid.
PROMO_USER_INELIGIBLE Gunakan Email di objek Kontak dalam permintaan untuk memvalidasi kelayakan promosi bagi pengguna. Lihat contohnya di menerapkan kirim pesanan dengan promosi.
INELIGIBLE
  • Informasi pengguna seperti nomor telepon atau Email tidak valid.
  • Mesin risiko Anda mendeteksi penipuan.
PAYMENT_DECLINED Pembayaran tidak dapat diproses. Misalnya, hal ini dapat disebabkan oleh dana yang tidak mencukupi.
UNKNOWN Untuk error validasi lainnya.

Tetapkan OrderState.state ke REJECTED jika ada error validasi yang terjadi. Secara opsional, Anda dapat memberikan alasan penolakan tertentu menggunakan FoodOrderUpdateExtension.foodOrderErrors. Lihat contoh di Validasi Kirim Pesanan.

Memproses pembayaran

  1. Hitung totalPrice dengan menambahkan harga keranjang, biaya, diskon, pajak, dan tip. totalPrice harus sama dengan totalPrice yang ditampilkan dalam CheckoutResponseMessage ditambah perubahan jumlah tip jika tip dapat diubah oleh pengguna. Lihat Perubahan harga selama pengiriman pesanan untuk mengetahui detail selengkapnya.
  2. Proses pesanan dan pembayaran jika Anda menampilkan respons dengan status pesanan CREATED atau CONFIRMED.
  3. Pastikan format respons yang valid ditampilkan menggunakan jenis yang dihasilkan yang dibuat dari skema seperti yang dijelaskan dalam membuat library klien.
  4. Gunakan GoogleProvidedPaymentInstrument.instrumentToken untuk memproses pembayaran. Tampilkan RejectionInfo dengan jenis PAYMENT_DECLINED jika pembayaran tidak dapat diproses. Lihat Memproses pembayaran untuk mengetahui detail selengkapnya.
  5. Beri tahu pengguna segera setelah pesanan diproses melalui Email dan atau SMS.

Menampilkan respons

  1. Tetapkan OrderState.state ke CREATED atau CONFIRMED jika tidak ada error.
  2. Tetapkan OrderState.state ke REJECTED jika ada error yang terjadi dan sertakan objek RejectionInfo dengan RejectionInfoType yang sesuai.
  3. Tetapkan OrderUpdate.orderManagementActions.
Sebelumnya
Menyiapkan Checkout
Berikutnya
Menguji Fulfillment API