Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Penggunaan Reward Stempel (v2)

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.

PUT

/api/stamp/v2/redeem 

{
    "stampIdx": 394,
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
onsiteToken string
Token pertukaran berjangka pendek. v2 tidak menerima kata sandi teks biasa (onsitePwd).
Jika sumber daya memiliki onsiteYn = Y, kirim onsiteToken dari respons API validasi apa adanya.
Idempotency-Key wajib untuk permintaan yang memakai token. Percobaan ulang dengan kunci yang sama memutar ulang hasil pertama; memakai token yang sama dengan kunci berbeda ditolak dengan 400 (kode kesalahan 1228).
Jika toko pemroses ditentukan saat validasi, permintaan ini harus memakai toko yang sama.
processStoreIdx integer
IDX toko tempat permintaan ini benar-benar diproses. Jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.
Cabang pemrosesan tidak diambil dari permintaan; server menentukannya dari toko ini. Nilai ini berbeda dari toko penerbit (storeIdx). 
{
    "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.

Menentukan toko pemroses

Parameter Arti Deskripsi
processStoreIdx Toko pemroses Toko tempat permintaan ini benar-benar diproses. Opsional; jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.

Cabang pemroses tidak diterima dari permintaan. Server menentukannya dari toko yang Anda tentukan dan mencatatnya.

Jika cakupan penggunaan adalah BRANCH, permintaan hanya diproses bila cabang toko pemroses yang terverifikasi sama dengan cabang penggunaan, atau bila Anda melakukan autentikasi dengan kata sandi di tempat cabang tersebut. Tanpa keduanya, permintaan ditolak.

Parameter yang tidak dapat digunakan — branchIdx (cabang penerbit), storeIdx (toko penerbit), useScope (cakupan penggunaan), dan useBranchIdx (cabang penggunaan) adalah kebijakan penerbitan yang sudah tersimpan dan tidak dapat diubah melalui API ini. Jika dikirim, akan ditolak dengan 400 (kode kesalahan 1227).

Idempotency-Key

Untuk mencoba ulang dengan aman saat respons hilang karena kesalahan jaringan, kirim nilai unik per permintaan pada header Idempotency-Key. Anda juga dapat mengirimnya sebagai requestId di body; jika keduanya dikirim dengan nilai berbeda, permintaan ditolak. Format yang diizinkan adalah 8–64 karakter berupa huruf, angka, dan . _ : -.

Jika Anda mengirim ulang permintaan yang sama dengan key yang sama, hasil pertama dikembalikan tanpa diproses ulang. Tidak ada yang diproses dua kali dan webhook tidak dikirim ulang.

Gunakan key yang sama hanya untuk percobaan ulang operasi logis yang sama. Selalu gunakan key baru untuk operasi yang berbeda. Menggunakan key yang sama dengan isi permintaan lain atau untuk operasi lain dapat ditolak dengan 409.

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

Token verifikasi di toko (onsiteToken)

v2 tidak menerima kata sandi toko dalam bentuk teks biasa (onsitePwd). Kirim onsiteToken yang dikembalikan oleh API Validasi tanpa perubahan. Mengirim onsitePwd saja atau bersama onsiteToken akan ditolak dengan 400 (kode kesalahan 1227).

Idempotency-Key wajib untuk permintaan yang menggunakan token. Percobaan ulang dengan Idempotency-Key yang sama akan mengembalikan hasil pemrosesan awal. Menggunakan kembali token yang sama dengan Idempotency-Key berbeda akan ditolak dengan 400 (kode kesalahan 1228).

Toko yang digunakan saat validasi harus sama dengan toko tempat pemrosesan dilakukan. Jika processStoreIdx ditentukan saat validasi, permintaan ini harus menggunakan toko yang sama. Token yang divalidasi tanpa toko tidak dapat dikaitkan dengan toko setelahnya.

Token yang kedaluwarsa, dimanipulasi, sudah digunakan, atau tidak cocok dengan pengikatannya semuanya mengembalikan 1228. Penyebab tersebut sengaja tidak dibedakan agar pihak lain tidak dapat menebak status internal menggunakan token lain.

Token tidak diperlukan untuk sumber daya yang tidak menggunakan verifikasi di toko (onsiteYn = N). v1 tetap menerima onsitePwd dalam bentuk teks biasa.

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.