Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Penggunaan Reward Stempel (v1)

API Penggunaan Reward Stempel menandai reward (minuman gratis, diskon, dll.) sebagai telah digunakan setelah semua stempel terkumpul.

Setelah digunakan, stempel tidak dapat digunakan kembali dan pengguna harus mendapatkan stempel baru untuk memulai siklus berikutnya.
API ini digunakan dalam sistem reward berbasis kunjungan atau pembelian.

API ini tersedia mulai dari paket Personal ke atas.

Dokumentasi v1 (Legacy).

Untuk integrasi baru, kami menyarankan penggunaan versi terbaru, v2.
v1 ditujukan untuk mempertahankan integrasi yang sudah ada dan tidak mendapatkan fitur baru atau peningkatan.

PUT

/api/stamp/v1/redeem 

{
    "stampIdx": 394,
    "onsitePwd": "12345"
}

Request Parameters

stampIdx integer required
Stamp IDX.
onsitePwd string
Kata sandi autentikasi karyawan untuk stempel di lokasi.
Wajib hanya jika stempel memiliki onsiteYn = Y, dan harus dimasukkan oleh staf saat menyetujui hadiah pelanggan.
Gunakan nilai onsitePwd dari Validate API sebagai referensi. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Kode respons: 0 = Berhasil, nilai lainnya = Error
message string
Pesan respons. Jika kode bukan 0, pesan error akan dikembalikan.
result null

Validasi parameter numerik

Jika parameter numerik menerima nilai bukan angka, atau angka di luar rentang yang dapat diproses server, permintaan langsung ditolak dengan 400 (kode kesalahan 653).

Dalam kasus itu data stempel dan riwayat perolehan sama sekali tidak berubah, dan tidak ada catatan event maupun pengiriman Webhook. Jika Anda menerima respons gagal, tidak ada yang tersimpan.

Perubahan perilaku. Sebelumnya v1 tetap melanjutkan permintaan meskipun validasi ini gagal. Akibatnya pesan kesalahan dapat tertimpa oleh pesan parameter lain, atau sebagian data stempel benar-benar tersimpan padahal respons berupa kesalahan. Sekarang permintaan dihentikan dengan 400 sebelum diproses, sama seperti versi terbaru.

Tahap penggunaan reward

Ini adalah tahap akhir dari sistem stempel.

  • Memastikan akumulasi telah selesai
  • Memproses pemberian reward
  • Menandai stempel sebagai sudah digunakan

Ini bukan sekadar perubahan status, tetapi tahap finalisasi hasil event.

Akhir siklus stempel

API ini merupakan tahap terakhir dalam siklus stempel.

Bagi pengguna, ini adalah momen menerima reward. Bagi developer, ini menandai akhir satu siklus dan awal siklus berikutnya.

Setelah memanggil Redeem, panggil Create untuk menjaga keterlibatan pengguna.

Siklus lengkap

  1. Create → Terbitkan stempel
  2. Add Stamp → Tambahkan stempel
  3. Validate → Periksa status
  4. Redeem → Gunakan reward
  5. Create → Mulai siklus baru

Penanganan stempel onsite

onsitePwd hanya diperlukan jika stempel memiliki password verifikasi onsite (onsiteYn = Y).

Staf toko memasukkan nilai ini saat menyetujui penggunaan reward untuk mencegah penyalahgunaan.

Gunakan nilai onsitePwd yang dikembalikan oleh API Validasi.
Jika tidak ada password, field ini dapat diabaikan.

Alur otomatis setelah penggunaan

Anda dapat mengotomatisasi proses lanjutan saat reward digunakan.

  • Panggil API pembuatan kupon untuk langsung menerbitkan reward
  • Buat stempel baru untuk memulai siklus berikutnya

Otomatisasi ini memungkinkan seluruh siklus reward berjalan tanpa intervensi manual.

Poin penting dalam operasional

API ini bukan sekadar fitur, tetapi titik di mana hasil bisnis ditentukan.

  • Kesalahan penanganan dapat menyebabkan reward ganda
  • Potensi klaim atau komplain dari pengguna

Pastikan alur validasi → penggunaan, kontrol transaksi di sisi server, dan pencatatan audit log diterapkan.