Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

Sistem Voucher & Manajemen Promosi Diskon

Program promosi diskon merupakan fondasi pendorong konversi penjualan e-commerce yang paling kuat. Namun, penerapan diskon dalam perdagangan konversasional dan multi-kanal kerap diwarnai risiko teknis seperti over-redemption (klaim melebihi batas kuota), persaingan serentak (race condition) pada saat puncak kampanye (seperti Harbolnas 12.12), dan kerugian margin karena kesalahan kalkulasi matematika pemotongan harga.

Modul Voucher DagangBot menghadirkan sebuah mesin promosi otomatis yang tangguh (robust) dengan perlindungan sistem reservasi kuota berbasis siklus state-machine. Sistem ini menjamin integritas kuota hingga level presisi baris transaksi, mencegah pembeli mengeksploitasi celah waktu pembayaran, dan memaksa berlakunya aturan minimum nilai pembelanjaan (minimum order value) di tingkat mesin backend.

Stable

1. Ikhtisar & Nilai Bisnis

Pendekatan Concurrency Lock kami meredam fenomena kelebihan klaim pada sesi checkout pelanggan berkat pencatatan log transaksi yang mengikat secara atomik. Arsitektur ini membawakan deretan nilai bisnis yang kokoh bagi para pemilik jenama:

  • Mekanisme Reservasi Draft (Concurrency Lock): Ketika ratusan pelanggan serentak memasukkan kode promo yang sama (contoh BERKAHRAMADHAN) di chat WhatsApp, setiap pesanan draf otomatis memicu penguncian satu kuota sementara (reserved). Secara default, reservasi ini menahan kuota selama 30 menit (dapat diubah via konfigurasi global order_draft_expiry_minutes dalam rentang 5-120 menit). Jika pelanggan tidak melunasi pembayaran dalam jendela waktu tersebut, sistem garbage collector kami otomatis akan melepaskan kuota kembali ke dalam peredaran bebas (reversed).
  • Pembersihan Otomatis Reservasi Yatim (Orphaned GC): Sistem asinkron juga mendeteksi "reservasi yatim" (orphaned reservations) di mana baris draf terhapus sebelum webhook pengembalian dipanggil. Hal ini menggaransi bahwa promosi merchant tidak akan mengalami kebocoran kuota (quota leak) sekecil apapun di basis data.
  • Fleksibilitas Skema Diskon Terbatas: Merchant diizinkan merumuskan potongan harga dengan dua variabel matematis—Percentage (diskon berbasis rasio dengan pagu perlindungan batas atas atau max_discount) dan Fixed Nominal (potongan nilai statis rupiah bulat).
  • Pembatasan Pemakaian Individual: Fitur Max Usage per Customer menutup celah pelanggan jahil yang mencoba menggunakan akun atau nomor yang sama berkali-kali pada hari kampanye yang sama, mengamankan kelancaran distribusi insentif kepada pembeli-pembeli organik.
  • Atribusi Penjualan & ROI Kampanye: Modul promosi menyambungkan setiap serapan pemakaian kode secara langsung ke laporan Campaign Attribution, di mana merchant dapat mengevaluasi imbal hasil (Return on Investment) sebuah broadcast berbayar diukur terhadap jumlah completed order.
Pencegahan Over-Claim dan Stacking

DagangBot tidak memberlakukan penumpukan diskon (stacking) antar-kode voucher. Sebuah draft_id pesanan hanya dapat mengikat secara sah dengan maksimum 1 ID voucher dari tabel voucher_usages. Aturan batas non-negatif memastikan pengurangan tidak menyebabkan nilai invoice final berada di bawah angka wajar pembayaran operasional bank.

2. Alur Visual & Antarmuka

Antarmuka panel kendali voucher memudahkan merchant memantau seluruh kode promo yang aktif, kuota tersisa, serta parameter batas klaim. Merchant mengatur siklus hidup tiap kode dengan pilar waktu: starts_at dan expires_at:

Tabel daftar voucher promosi dan kode promo aktif di dasbor DagangBot
Tabel daftar voucher promosi dengan rincian tipe diskon, kuota pemakaian, dan status keaktifan.
Formulir modal pembuatan voucher baru dengan konfigurasi kuota dan syarat minimal belanja
Formulir modal pembuatan voucher promo dengan pengaturan limitasi klaim, batas diskon maksimal, dan masa berlaku.

Alur ini tidak membingungkan pengguna; kalkulasi terjadi real-time dan membatalkan pesanan secara otomatis (reverting) tanpa mengorbankan pengalaman percakapan.

3. Panduan Langkah-demi-Langkah

Integrasi operasional pembuatan program kampanye diskon Anda disederhanakan dalam urutan penyusunan di bawah ini, yang merefleksikan model data di backend.

  1. 1

    Langkah 1: Merumuskan Identitas Kode Promo

    Melalui Dasbor Merchant, akses menu Pemasaran → Voucher & Promo. Tekan tombol + Buat Voucher Baru. Tentukan code (kode unik, wajib kapital tanpa spasi) beserta name sebagai referensi tajuk pelaporan.

  2. 2

    Langkah 2: Memilih Mode Tipe Diskon

    Putuskan arsitektur pengurangnya:

    • Nominal (Fixed): Pilih nilai Rp untuk diskon potong-lurus (contoh: discount_value 20.000). Sangat tepat pada harga pokok penjualan stabil.
    • Persentase (Percentage): Pilih persentase % (contoh: discount_value 15.000, direpresentasikan sebagai 15). Wajib lengkapi bidang max_discount (contoh: 50.000) untuk mencegah pengguna mengeksploitasi pembelian grosir massal dengan diskon tak terbatas.
  3. 3

    Langkah 3: Mengunci Limitasi Pembelian (Min. Order)

    Tentukan nilai min_purchase (ambang batas ukuran keranjang) sebelum kode diterima mesin validasi. Masukkan nilai Rp 150.000 untuk mencegah pembelian produk berharga murah yang disubsidi penuh oleh potongan harga kupon Anda.

  4. 4

    Langkah 4: Memasang Perimeter Kuota & Pemakaian Individual

    Deklarasikan plafon penerimaan di quota_total (misal 50 kupon) serta max_usage_per_customer (misal 1 per nomor telepon). Apabila Anda meluncurkan program harian tanpa batas individual, sistem tetap memperhitungkan ketersediaan total.

  5. 5

    Langkah 5: Penjadwalan Waktu Mengudara (Validity Window)

    Sematkan nilai starts_at dan expires_at. Sebuah voucher secara otomatis akan gugur setelah melewati milidetik terakhir dari expires_at walaupun status is_active masih tercentang aktif oleh kasir merchant.

  6. 6

    Langkah 6: Pemantauan Analitik Klaim

    Anda dapat memonitor pergerakan status setiap kode promosi melalui API GetVoucherUsageCounts di panel kontrol. Antarmuka menyajikan diagram riwayat penyerapan yang dipecah menjadi tiga filter kolom: jumlah kupon yang sedang tertahan (Reserved), yang berhasil ditukarkan menjadi uang muka pesanan (Completed), dan yang hangus terbuang (Reversed).

4. Parameter & Spesifikasi Teknis

Sistem basis data PostgreSQL merekam siklus ini di bawah dua entitas krusial: definisi induk pada tabel vouchers dan instansiasi klaim pada tabel voucher_usages. Parameter berikut merangkum batas operasional mesin:

Komponen Arsitektur Spesifikasi / Kolom Kode Deskripsi Logika & Aturan Bisnis Dasar
Enum Tipe Diskon percentage, fixed Enumerasi ketat untuk jenis matematika pemotongan pada kolom discount_type.
Relasi Penggunaan Tunggal 1 draft_id = 1 Voucher Tidak diizinkan menumpuk (stacking) kode. Klaim kode baru akan menggantikan kode lama di dalam draf.
Penjaga Diskon Maksimum max_discount DECIMAL Pencegah margin minus pada mode percentage. Jika pesanan 1.000.000 diskon 20%, pagu 50.000 akan memblokir diskon menjadi tetap 50.000.
Aturan Klaim Individual max_usage_per_customer Membandingkan riwayat jumlah sukses pesanan per customer_id melawan batas plafon yang diterapkan.
Durasi Retensi Draft 30 Menit Default Masa tenggang (timeout) bagi konsumen membayar tagihannya sebelum status reserved dibongkar otomatis oleh server.
Konfigurasi Retensi Global order_draft_expiry_minutes Parameter pengatur tingkat platform yang memiliki limit dinamis minimum 5 menit dan maksimum 120 menit.

Mekanisme Pengembalian Kuota (Garbage Collection)

Selain dari pembatalan manual oleh pembeli atau penambahan item yang menggugurkan kondisi promosi, CartWorker memiliki job terjadwal bertipe voucher:release_expired_reservations yang dilepas berkala oleh scheduler. Job ini menelisik reservasi yang masih reserved dan pemilik drafnya sudah melewati tenggat (cart.order_draft_expiry_minutes, default 30 menit), lalu mengembalikan kuota ke voucher.

Ketika waktu telah habis, baris-baris ini disapu bersih. Skema ini mengeliminasi kebocoran persediaan (inventory leak) akibat pelanggan hantu yang melempar kode promosi lalu beranjak pergi tanpa menyelesaikan transaksi, memastikan pelanggan lain yang antre dapat menikmati fasilitas diskon tersebut pada puncak trafik.

Transisi State-Machine (Tabel voucher_usages)

Setiap insiden konsumen mengetik sebuah kode akan dicatat status pembukuannya:

  • reserved: Konsumen mengklaim kode di dalam Draft. Nilai kolom induk quota_used langsung merangkak (+1). Transaksi dikunci dari pelanggan lain.
  • completed: Pembeli melunasi pembayaran (via gerbang pembayaran Qris/Transfer). Transisi dari draf ke Confirmed Order dan menautkan order_id secara permanen. Kuota terpotong mutlak.
  • reversed: Draft dibatalkan, habis tenggang waktu (timeout), atau pengguna menghapus item sehingga tidak lagi memenuhi syarat min_purchase. quota_used dikembalikan (-1), dan status dipukul reversed. Kupon tersedia lagi bagi ranah publik.

Setiap fungsi state-machine mematuhi kontrol restriksi transaksi relasional (ACID compliant), menggunakan SELECT ... FOR UPDATE agar persaingan akses dari banyak proses goroutine (HTTP requests) pada detik yang bersamaan tidak akan membuat pencatatan ganda.

5. Relasi & Integrasi

Voucher bergantung pada jaringan logis modul lain untuk membuktikan kelayakannya sebelum dikonversi menjadi pengurangan rupiah kas riil.

  • Mesin Checkout & Pemesanan (Order Engine): Mengawasi perubahan saldo subtotal. Jika pelanggan menghapus item dari keranjang draft WhatsApp-nya sedemikian rupa sehingga subtotal < min_purchase, layanan pesanan akan mengeksekusi ReleaseVoucherUsageByDraft, memicu state menjadi reversed, dan merender ulang jumlah tagihan secara penuh.
  • Webhook Status Pembayaran: Saat status transaksi completed dilaporkan dari pihak agregator perbankan (Payment Gateway), handler pemesanan memanggil fungsi mutasi asinkronus ke layanan Voucher untuk mengangkat status reserved menjadi final.
  • Integrasi Pemasaran Terarah (Campaign Attribution): Kode voucher dikaitkan (melalui pilar foreign key voucher_id di entitas campaigns) dalam laporan atribusi. Merchant mengetahui secara langsung rasio antara jumlah pengguna yang membaca Broadcast WhatsApp melawan jumlah klaim kupon final di keranjang (Completed Orders). Keterikatan per-kanal (per-channel applicability) juga dapat ditelusuri dari asal transaksi.

6. Pemecahan Masalah (Troubleshooting)

| Simtom (Gejala) yang Dilaporkan | Analisis Akar Penyebab | Prosedur Solusi & Perbaikan | | Respons Bot: "voucher tidak ditemukan" | Kode yang dimasukkan salah, atau pelanggan memasukkan spasi tersembunyi. | Pastikan membagikan broadcast yang bebas typo huruf. | | Pesan Bot: "voucher sedang tidak aktif" / "belum dapat digunakan" | Atribut is_active = false atau waktu server belum melampaui parameter waktu starts_at. | Verifikasi zona waktu pada pengaturan promosi saat menekan tombol simpan jadwal. | | Pesan Bot: "minimum pembelian untuk voucher ini belum terpenuhi" | subtotal draf dari pengguna berada di bawah ambang variabel min_purchase (Error ErrVoucherMinPurchase). | Bot akan secara otomatis menyarankan pelanggan untuk mencomot beberapa item pelengkap ke dalam keranjang. | | Kuota voucher habis di layar, namun di laporan akhir penjualan sedikit | Konsumen dalam gelombang trafik masif sedang menduduki sesi reserved secara bersamaan dan menelantarkan tagihan. | Ini pertanda Conversion Rate produk buruk. Kuota status reversed akan kembali dalam 30 menit. | | Diskon tereduksi memotong biaya logistik secara keliru | Masalah klasik di luar DagangBot. Di sini, sistem mendedikasikan reduksi pada variabel subtotal, mengabaikan grand_total logistik. | Tidak diperlukan penambalan manual karena rumus arsitektur platform mengisolasi promosi dari ongkos kirim (shipping). | | Pesan Bot: "Anda telah mencapai batas pemakaian untuk voucher ini" | Pengguna yang sama (ID customer_id identik) mencoba menebus kupon lagi padahal limit max_usage_per_customer telah tercapai. | Blokir ini wajar terjadi (ErrVoucherLimitReached), memastikan peredaran subsidi merata. |

7. Referensi Terkait

Pelajari instrumen dan modul yang memanfaatkan fondasi infrastruktur voucher untuk melipatgandakan perolehan hasil Anda.

content/docs/features/voucher.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot