Kartu Voucher (alias Voucher)

Catatan: Ini adalah versi uji coba.

Peringatan: Dokumen ini adalah dokumen yang Masih Dalam Proses. Informasi dapat sering berubah.

Panduan ini menguraikan persyaratan, rekomendasi pemodelan data, dan praktik terbaik untuk menerapkan kartu voucher (juga dikenal sebagai voucher) di feed penawaran Anda. Rekomendasi ini melengkapi dokumentasi Pusat Tindakan standar dan membahas aspek integrasi khusus kartu voucher.

Mode dan Kategorisasi Penawaran

Saat mengirimkan inventaris kartu voucher, pastikan atribut inti berikut dikonfigurasi dengan benar:

• Mode Penawaran: offer_modes harus selalu ditetapkan sebagai array singleton yang berisi "OFFER_MODE_GIFT_CARD_PURCHASE":

  "offer_modes": ["OFFER_MODE_GIFT_CARD_PURCHASE"]
  

• Voucher Nilai Tersimpan vs. Diskon Langsung di Tempat:

  • gift_card_info secara ketat dikhususkan untuk voucher nilai tersimpan dan kartu voucher yang dibeli di muka (OFFER_MODE_GIFT_CARD_PURCHASE).
  • Jika pelanggan membayar langsung di konter toko fisik di tempat untuk mendapatkan diskon langsung tanpa membeli kode voucher untuk diklaim atau ditukarkan nanti, modelkan penawaran sebagai diskon langsung di tempat standar (OFFER_MODE_WALK_IN) dan hapus pesan gift_card_info sepenuhnya.

• Pemodelan Denominasi: Denominasi kartu voucher harus mewakili nilai voucher (nilai yang dapat ditukarkan), bukan nilai yang dibayar pengguna (pengguna membayar harga diskon).

• Menggabungkan Beberapa Denominasi: Beberapa voucher yang memiliki persentase dan persyaratan diskon yang sama persis, tetapi memiliki nilai nominal yang berbeda, harus dikelompokkan ke dalam satu entri penawaran. Karena denomination_type beroperasi sebagai oneof, partner harus memilih antara menetapkan fixed_denominations atau custom_range:

  • Denominasi Tetap: Gunakan saat jumlah kartu voucher diskret dan preset ditawarkan (misalnya, Rp500.000, Rp1.000.000, dan Rp2.000.000, semuanya dengan diskon tetap 10%). Pastikan denominasi tetap yang terjual habis atau tidak tersedia di halaman landing dikecualikan secara eksplisit dari pengiriman feed.
  • Rentang Kustom: Gunakan secara ketat saat pengguna dapat dengan bebas memasukkan nilai nominal arbitrer apa pun dalam batas yang ditentukan di halaman pembelian (misalnya, nilai apa pun antara Rp100.000 dan Rp5.000.000 dengan diskon 5%). Jika halaman landing tujuan menawarkan jumlah diskret dan preset, modelkan inventaris secara ketat di bagian fixed_denominations. Selain itu, jika denominasi tetap dan denominasi kustom tersedia untuk penawaran, partner harus menetapkan rentang kustom yang fleksibel.

Menangani Rantai Multi-Lokasi

Untuk voucher hadiah yang berlaku di seluruh rantai ritel atau restoran besar dengan persyaratan yang sama di beberapa tempat menarik (POI), jangan berikan objek Penawaran terpisah untuk setiap lokasi toko. Sebagai gantinya, gunakan pendekatan pemberian feed gabungan dengan memberikan satu objek Penawaran yang berisi daftar semua ID entity toko yang berpartisipasi (entity_ids).

Catatan: Pengecualian berlaku jika URL halaman landing tujuan (offer_url) unik untuk setiap outlet toko. Dalam kasus tersebut, partner harus mengirimkan satu objek Penawaran terpisah per outlet.

Branding Portal (brand_id)

Beberapa voucher ditawarkan melalui portal bank atau loyalitas tertentu (misalnya, program loyalitas bank atau platform partner), bukan situs penjual utama. Untuk memastikan branding yang akurat untuk portal ini, partner harus mengisi kolom brand_id pada objek Penawaran tingkat atas.

Meskipun penghapusan brand_id akan ditetapkan secara default ke merek utama akun (dan brand_id tidak diperlukan saat menggunakan merek default akun), mengisi brand_id secara eksplisit akan mengaitkan inventaris dengan portal bermerek yang sesuai secara akurat, sehingga memastikan logo dan nama khusus partner yang benar ditampilkan kepada pengguna. Petunjuk lebih lanjut tentang cara mengonfigurasi merek dapat ditemukan di Konfigurasi Merek.

Struktur Validitas (ValidityScope)

Kartu voucher memiliki struktur validitas unik yang membedakan jangka waktu untuk membeli penawaran dari durasi untuk menukarkan kartu. Partner harus selalu menggunakan nilai enum ValidityScope yang relevan:

• VALIDITY_SCOPE_CLAIM: Menentukan jangka waktu penawaran kartu voucher tersedia untuk dibeli di platform partner. Entri ini harus selalu ada. Saat mengirimkan feed, isi periode validitas klaim mulai dari tanggal pengiriman feed yang tepat. Selain itu, jangan pernah membiarkan periode klaim terbuka jika halaman landing secara eksplisit mengiklankan tanggal akhir kampanye; cocokkan valid_through_time dengan tanggal habis masa berlaku yang diiklankan.
• VALIDITY_SCOPE_REDEEM: Menentukan durasi penukaran pasca-pembelian (jangka waktu yang dimiliki pengguna untuk menukarkan voucher di toko setelah membelinya, yang dapat ditentukan sebagai durasi atau jangka waktu).

Pemetaan Jenis Tindakan

Partner sering mengategorikan voucher menggunakan konstruksi seperti "dapat ditukarkan secara online/offline", "online/outlet", atau "di toko". Dalam pengiriman feed, hal ini harus dipetakan ke enum ActionType untuk menentukan secara akurat cara produk digunakan:

• Vertical Restoran / Makanan: Petakan kartu voucher "Makan di tempat" ke ACTION_TYPE_DINING. Petakan kartu voucher "Pengiriman" ke ACTION_TYPE_FOOD_DELIVERY. Petakan kartu voucher "Bawa pulang" ke ACTION_TYPE_FOOD_TAKEOUT.
• Vertical Ritel Belanja: Petakan kartu voucher "Di toko" ke ACTION_TYPE_SHOPPING_IN_STORE. (Catatan: Voucher ritel khusus online tidak didukung).
• Pemetaan Satu Channel: Setiap offer_id hanya dapat dimiliki oleh satu ActionType. Jika item inventaris mendukung beberapa channel pemenuhan (misalnya, pengiriman makanan dan bawa pulang), buat objek Penawaran terpisah dengan ID unik untuk setiap mode.

Diskon Bertingkat dan Penawaran Add-On

• Diskon Bertingkat di Seluruh Metode Pembayaran: Jika persentase diskon yang berbeda ditawarkan berdasarkan instrumen pembayaran tertentu yang digunakan (misalnya, diskon yang lebih tinggi untuk e-wallet dibandingkan Kartu Kredit), diskon tersebut harus dimodelkan sebagai objek Penawaran terpisah. Partner harus memberikan cakupan promosi yang lengkap di semua instrumen pembayaran yang didukung (misalnya, e-wallet, Kartu Kredit, Kartu Debit, Net Banking) untuk memastikan pengalaman penghematan yang andal. Jika penawaran berlaku secara universal untuk semua metode pembayaran yang diterima di platform, kolom instrumen pembayaran tidak boleh ditetapkan.
• Konstruksi Penawaran Add-On: Untuk merepresentasikan manfaat bertumpuk, seperti poin reward khusus bank atau cashback tambahan yang berlaku untuk pembelian kartu voucher, kirimkan sebagai penawaran Add-On yang sepenuhnya terpisah menggunakan enum OfferCategory yang sesuai - OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER. Jelaskan reward di dalam OfferDetails.other_offer_details_text (misalnya, "Poin Reward hingga 5X"), dan tautkan ke penawaran kartu voucher dasar dengan mengisi OfferRestrictions.combinable_offer_ids dengan kartu voucher dasar offer_id.

Persyaratan dan Kondisi Khusus

Partner harus mengandalkan terms.terms_and_conditions untuk memberikan Persyaratan &Ketentuan hukum lengkap dari kartu voucher atau voucher. Gabungkan semua petunjuk dan panduan penggunaan yang ditujukan kepada pengguna ke dalam kolom ini.

Jika batasan penting memerlukan penonjolan UI khusus (seperti masa berlaku saldo sekali pakai, tidak dapat dikembalikan, atau batas penggabungan transaksi seperti "Maksimum 2 voucher dapat digabungkan per tagihan"), tandai batasan tersebut di offer_restrictions.special_conditions.

Penting: Kondisi penting apa pun yang diisi di special_conditions juga harus disertakan secara lengkap dalam string terms.terms_and_conditions utama.

Rekomendasi Judul Penawaran

Panjang judul penawaran harus tetap kurang dari 40 karakter. Hapus nama merek penjual dari offer_display_text, karena penawaran ditampilkan langsung di halaman tempat khusus penjual. Sebaiknya gunakan format judul berikut:

Kasus penggunaan	Judul yang Direkomendasikan
Diskon tetap untuk voucher	X% off on Gift Cards
Diskon variabel berdasarkan metode pembayaran	X% off on Gift Cards using {e-wallet}
Diskon variabel untuk denominasi yang berbeda	X% off on Gift Cards (Kirim diskon yang berbeda sebagai penawaran terpisah)
Kartu voucher B2B2C	X% off on Gift Cards (Branding ditampilkan melalui thumbnail menggunakan brand_id)
Penawaran add-on	Flat/Up to 5X reward points/ <Platform> coins

Persyaratan halaman landing

Setiap offer_url yang diiklankan harus menampilkan HTTP 200 OK secara langsung tanpa pengalihan perantara dan mengarah ke halaman tujuan aktif yang membuktikan penawaran.

Feed tidak boleh menyertakan denominasi yang terjual habis atau tidak tersedia. Pertahankan sinkronisasi inventaris yang ketat antara kolom denominasi feed dan opsi pembelian langsung di halaman landing tujuan.

Halaman landing tujuan harus menyebutkan dengan jelas bahwa penawaran berlaku khusus untuk kartu voucher atau voucher.

Misalnya, jika halaman landing partner hanya menampilkan ajakan (CTA) pembayaran umum seperti "Bayar tagihan" tanpa menyatakan secara eksplisit di awal bahwa penyelesaian transaksi akan menerbitkan voucher kartu voucher nilai tersimpan, pengguna yang dialihkan dari Google dan berharap untuk membeli kartu voucher dapat mengalami kebingungan atau berhenti. Meskipun pemberitahuan voucher muncul pada langkah checkout berikutnya, kejelasan di awal pada halaman landing awal diperlukan.

Penawaran dengan kode kupon

Penawaran tertentu mengharuskan pengguna memasukkan kode kupon, seperti "Terapkan kode HEMAT20 untuk mendapatkan diskon 20% dari total tagihan". Perlu diperhatikan bahwa Google tidak menampilkan kode kupon dari definisi kupon. Partner dapat menyertakan informasi ini dalam OfferDetails.offer_display_text untuk ditampilkan kepada pengguna. Penawaran berbasis kupon umumnya dibagi menjadi dua kategori:

• Penawaran yang kuponnya otomatis ditampilkan saat checkout kepada pengguna yang datang dari Google. Penawaran ini diizinkan.
• Penawaran yang mengharuskan pengguna memasukkan kode kupon saat checkout, tetapi tidak memberikan petunjuk tentang cara menerapkan kode kupon di halaman landing URL penawaran, atau tidak otomatis menerapkan kupon saat mengikuti URL penawaran, tidak diizinkan.

Contoh JSON Penawaran Kartu Voucher

{
  "data": [
    {
      "offer_id": "example-dining-gift-card-10off",
      "entity_ids": [
        "dining-1",
        "dining-2"
      ],
      "offer_modes": [
        "OFFER_MODE_GIFT_CARD_PURCHASE"
      ],
      "action_type": "ACTION_TYPE_DINING",
      "offer_source": "OFFER_SOURCE_AGGREGATOR",
      "offer_category": "OFFER_CATEGORY_BASE_OFFER",
      "offer_details": {
        "offer_display_text": "10% off on Gift Cards",
        "discount_percent": 10.0,
        "gift_card_info": {
          "fixed_denominations": {
            "amounts": [
              {
                "units": 500,
                "currency_code": "INR"
              },
              {
                "units": 1000,
                "currency_code": "INR"
              },
              {
                "units": 2000,
                "currency_code": "INR"
              }
            ]
          }
        }
      },
      "offer_restrictions": {
        "combinable_with_other_offers": false,
        "special_conditions": [
          "Single-use balance expiration applies",
          "Maximum 2 gift card vouchers can be combined per bill",
          "No cash refund will be provided against this voucher"
        ]
      },
      "terms": {
        "restricted_to_certain_users": false,
        "terms_and_conditions": "1. Redeemable exclusively at participating dining outlets.\n2. Single-use balance expiration applies.\n3. Maximum 2 gift card vouchers can be combined per bill.\n4. No cash refund will be provided against this voucher."
      },
      "validity_periods": [
        {
          "valid_period": {
            "valid_from_time": {
              "seconds": "1774934350"
            },
            "valid_through_time": {
              "seconds": "1806470350"
            }
          },
          "validity_scope": "VALIDITY_SCOPE_CLAIM"
        },
        {
          "validity_duration_in_days": 365,
          "validity_scope": "VALIDITY_SCOPE_REDEEM"
        }
      ],
      "offer_url": "https://www.example-portal.com/dining-gift-cards/buy"
    }
  ]
}