Menambahkan ketersediaan untuk integrasi Pemesanan Retail v1

Tujuan: Pelajari cara menentukan ketersediaan untuk link tindakan pengambilan dan pengiriman, serta cara memperbarui ketersediaan tersebut saat berubah.

Catatan: Panduan ini hanya berlaku untuk partner yang saat ini inventaris aktivasi melalui Integrasi Reservasi dengan Google Starter kami dengan tindakan Pemesanan Retail.

Tutorial ini membahas:

1. Deskripsi tingkat tinggi tentang cara ketersediaan ditampilkan kepada pengguna, dan jenis data yang diperlukan
2. Petunjuk khusus tentang cara mengenkode data ketersediaan ke dalam action_link di feed Anda
3. Petunjuk tentang cara memperbarui ketersediaan tersebut jika terjadi perubahan sepanjang hari
4. Ekspektasi akurasi ketersediaan

Bersama dengan metadata ketersediaan, Anda juga diharapkan untuk memberikan metadata tentang biaya yang terkait dengan pengiriman atau pengambilan, serta jumlah pesanan minimum. Untuk sampel feed lengkap yang menunjukkan penggunaan Ketersediaan serta biaya dan pesanan minimum, lihat Contoh Feed Retail v1.

Informasi ketersediaan yang diperlukan

Ketersediaan Pemesanan Retail untuk pengalaman ini dikumpulkan pada tingkat perincian hari. Data ketersediaan ini ditampilkan kepada pengguna beserta biaya & jumlah pesanan minimum dengan pesan seperti “Tersedia hari ini”, “Tersedia besok” atau “Tersedia DD/MM” berdasarkan tanggal paling awal yang tersedia.

Ketika mengirimkan data ini di feed, Anda akan mengirimkan tanggal mendatang yang memiliki ketersediaan serta waktu terakhir saat pengguna dapat memesan dan menjadwalkan pengambilan atau pengirimannya untuk setiap tanggal. Kedua informasi ini berturut-turut adalah tanggal pemenuhan dan waktu pemesanan terakhir.

Misalnya: Jika tanggal hari ini adalah 23 Maret 2021 dan ada ketersediaan untuk pengiriman besok selama pengguna memesan paling lambat hari ini pukul 16.00, maka data yang akan Anda berikan untuk mewakili ketersediaan ini adalah:

• Tanggal pemenuhan: 2021/03/24
• Waktu pemesanan terakhir: 23/03/2021 16:00

Karena waktu pemesanan terakhir disertakan, setelah waktu tersebut berlalu, frontend Google akan otomatis diperbarui ke tanggal berikutnya yang tersedia, setelah waktu pemesanan terakhir berlalu.

Setiap hari, saat mengupload feed penjual baru, data ketersediaan baru harus disertakan. Karena frontend hanya menampilkan ketersediaan saat ini, Anda hanya perlu memberikan 3-5 tanggal ketersediaan berikutnya untuk lokasi tertentu. Hal ini memungkinkan frontend menampilkan ketersediaan saat ini serta memiliki ketersediaan berikutnya untuk ditampilkan setelah waktu pemesanan terakhir berlalu.

Menentukan ketersediaan melalui feed

Ketersediaan untuk link tindakan disertakan dalam pesan action_link feed Merchant, sebagai bagian dari kolom order_online_metadata. Untuk setiap penjual dan setiap opsi pemenuhan, terdapat daftar pesan AvailableDay pada jalurnya

Merchant.action_link.order_online_metadata.fulfillment_option.available_day

Pesan ini harus dalam format berikut ini:

{
  "fulfillment_date": {
    "year": "2020",
    "month": "10",
    "day": "1"
  },
  "last_ordering_time":  {
    "seconds": "1601614800"  // 2020/10/1, 10pm
  }
}

Dalam format ini, fulfillment_date adalah tahun, bulan, dan hari yang memiliki ketersediaan. Tanggal ini harus merujuk ke lokasi yang ditentukan oleh penjual ini.

last_ordering_time adalah stempel waktu unix dalam detik. Jenis ini tidak bergantung pada zona waktu, dan menandai momen terakhir saat penjual dapat menerima pesanan untuk tanggal yang diberikan di fulfillment_date. Waktu pemesanan terakhir dapat ditetapkan kapan saja lebih awal, atau selama tanggal pemenuhan. Setelah waktu pemesanan terakhir berlalu, Google akan otomatis berhenti menampilkan ketersediaan untuk tanggal pemenuhan tertentu, dan akan mulai menampilkan ketersediaan berdasarkan tanggal pemenuhan berikutnya yang tersedia.

Catatan: Jika satu penjual memiliki beberapa opsi pemenuhan pesanan (pengambilan dan pengiriman), ketersediaan harus ditentukan secara terpisah untuk setiap opsi pemenuhan pesanan.

Untuk definisi referensi order_online_metadata, lihat Referensi Feed Penjual. Untuk mengetahui contoh feed yang menyertakan ketersediaan dalam format JSON, lihat Pemesanan Retail + Metadata.

Memperbarui ketersediaan dengan pembaruan real-time

Jika ketersediaan lokasi untuk pengiriman atau pengambilan berubah antara waktu Anda mengirimkan feed harian, REST API update real-time dapat digunakan untuk memperbarui ketersediaan yang ditampilkan kepada pengguna.

Catatan: Untuk mengetahui petunjuk mendetail tentang cara menyiapkan integrasi untuk menggunakan pembaruan real-time, lihat tutorial kami: Mengautentikasi dengan Maps Booking API.

Pembaruan dilakukan pada satu penjual dalam satu waktu. Saat melakukan update, Anda harus menentukan penjual yang akan diupdate, dan kolom yang akan diupdate sebagai bagian dari endpoint API. Kemudian, pada bagian isi permintaan, Anda akan menyertakan data baru untuk kolom tersebut. Setiap kolom yang sedang diperbarui akan diganti dengan informasi yang diberikan.

Untuk mengupdate ketersediaan, Anda akan membuat permintaan patch ke endpoint berikut:

PATCH https://mapsbooking.googleapis.com/v1alpha/inventory/partners/{partnerId}/merchants/{merchantId}?updateMask=action_link

Isi permintaan kemudian akan menjadi objek Merchant dengan hanya action_link yang disertakan (karena kita telah menetapkan updateMask untuk hanya menyertakan action_link):

{
  "action_link": [
    ..., // all required action_link fields here
    "order_online_metadata": {
      "fulfillment_option": [
        "fulfillment_type": "FULFILLMENT_TYPE_DELIVERY",
        "available_day": [ // Include the updated availability here
          {
            "fulfillment_date": {
              "year": "2020",
              "month": "10",
              "day": "1"
            }
            "last_ordering_time": {
              "seconds": "1601614800"  // 2020/10/1, 10pm
            }
          },
          ... // Other updated availability_days
        ]
      ]
    }
  ]
}

Jika permintaan API berhasil, respons akan mencakup objek Penjual dengan data yang baru diperbarui.

Untuk spesifikasi lengkap metode pembaruan Merchant, lihat: Metode: inventory.partners.merchants.patch.

Akurasi ketersediaan

Pesan dengan Google memahami bahwa detail ketersediaan berubah berdasarkan berbagai faktor. Faktor ini mencakup:

• Perubahan pada ketersediaan berdasarkan ukuran pesanan
• Perubahan ketersediaan berdasarkan waktu untuk menyelesaikan pemesanan dan checkout
• Latensi antara saat perubahan ketersediaan diperbarui, baik melalui feed atau melalui update real-time

Salah satu faktor tersebut dapat mengakibatkan situasi ketika ketersediaan yang awalnya ditampilkan kepada pengguna bukan ketersediaan akhir yang akan mereka lihat saat checkout. Tujuan implementasi ketersediaan bukan untuk menghilangkan sepenuhnya, tetapi memberikan informasi yang jelas kepada pengguna sesering mungkin.

Partner diharapkan memberikan implementasi yang menghasilkan ketersediaan akurat yang ditampilkan kepada pengguna sesering mungkin, sesuai upaya terbaik. Selain itu, jika ketersediaan berubah karena detail pesanan, hal ini harus ditunjukkan dengan jelas kepada pengguna. Jika Anda tidak yakin secara spesifik tentang hal yang diperlukan dalam kasus Anda, hubungi kontak Pesan dengan Google Anda.