Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Pembaruan Stempel (v2)

API Pembaruan Stempel memungkinkan Anda memperbarui data stempel yang sudah diterbitkan.

Selain perubahan dasar, Anda dapat menyesuaikan jumlah stempel, memproses penukaran reward, dan mereset PIN, sehingga kontrol penuh atas status pengguna dapat dilakukan.

API ini tersedia mulai dari paket Personal ke atas.

PUT

/api/stamp/v2/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

stampIdx integer required
Stamp IDX.
cardIdx integer
Card IDX.
Card IDX dapat ditemukan di halaman “Kartu Cap” pada dasbor.
stamps integer
Menentukan jumlah cap yang telah dikumpulkan.
Menunjukkan total jumlah cap yang telah diperoleh pelanggan. Mengubah nilai ini akan memperbarui status cap dan dapat ditambah atau dikurangi.
Jika semua cap sudah terkumpul (stamps = jumlah maksimum cap pada kartu), Anda harus mengatur useYn ke Y untuk menandai bahwa hadiah telah digunakan.
resetPinYn string
Default:N
Enum:
YN
Menentukan apakah PIN pelanggan untuk cap akan diatur ulang.
Y: Mengatur ulang PIN pelanggan yang sudah ada. Setelah diatur ulang, pelanggan harus membuat PIN baru saat mengakses halaman cap berikutnya.
N: Menjaga PIN yang ada tanpa perubahan.
useYn string
Default:N
Enum:
YN
Menentukan apakah hadiah dari cap telah digunakan.
Y: Pelanggan telah mengumpulkan semua cap dan menukarkan hadiah (misalnya minuman gratis, diskon, dll). Setelah penukaran, cap menjadi tidak aktif dan cap baru harus diterbitkan.
N: Hadiah belum digunakan.
Saat mengubah dari N ke Y, jumlah cap yang tersimpan harus sudah mencapai maksimum kartu, dan jika stempel memiliki kata sandi di lokasi, onsiteToken harus dikirim bersamaan.
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.
domain string
Default:https://vvd.bz
Domain cap.
Jika dikosongkan, domain default akan digunakan.
Tersedia untuk paket Premium ke atas — Anda dapat menentukan domain kustom yang terdaftar di bagian Manajemen Domain Tautan.
strtYmd date
Tanggal mulai berlaku cap. Contoh: 2025-01-01
endYmd date
Tanggal kedaluwarsa cap. Contoh: 2025-12-31
Tanggal kedaluwarsa dapat diatur hingga maksimal 5 tahun dari hari ini.
activeYn string
Default:Y
Enum:
YN
Menunjukkan apakah cap aktif. Jika dinonaktifkan, pelanggan tidak dapat menggunakan cap tersebut.
memo string
Catatan internal untuk referensi.
userId string
ID pengguna. Digunakan untuk mengelola penerima cap.
Biasanya diisi dengan ID login anggota situs web.
Jika tidak ditentukan, sistem akan secara otomatis membuat ID pengguna.
userNm string
Nama pengguna. Hanya untuk penggunaan internal.
userPhnno string
Nomor kontak pengguna. Hanya untuk penggunaan internal.
userEml string
Alamat email pengguna. Hanya untuk penggunaan internal.
userEtc1 string
Bidang tambahan untuk pengelolaan internal.
userEtc2 string
Bidang tambahan untuk pengelolaan internal.
branchIdx integer
IDX cabang penerbit. Jika tidak dikirim, diterbitkan oleh kantor pusat; kirim 0 untuk mengosongkannya.
Tersedia pada paket Business atau lebih tinggi.
storeIdx integer
IDX toko penerbit. Jika ditentukan, cabang tempat toko berada menjadi cabang penerbit. Mengirim cabang yang berbeda akan menghasilkan kesalahan.
useScope string
Cakupan penggunaan. Hanya ALL (semua toko) atau BRANCH (cabang tertentu) yang diizinkan. Jika tidak dikirim, nilainya ALL.
useBranchIdx integer
IDX cabang tempat penggunaan. Hanya diperlukan saat useScope = BRANCH; selalu kosong jika ALL. 
{
    "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.

Cabang penerbit, toko penerbit, dan cakupan penggunaan

Nilai yang ditentukan di sini adalah kebijakan yang disimpan saat penerbitan. "Di mana diterbitkan" (cabang penerbit, toko penerbit) dan "di mana pelanggan dapat menggunakannya" (cakupan penggunaan, cabang penggunaan) adalah konsep yang berbeda, sehingga parameternya terpisah.

Parameter Arti Deskripsi
branchIdx Cabang penerbit Jika tidak dikirim, diterbitkan kantor pusat. Kirim 0 untuk mengosongkannya ke kantor pusat.
storeIdx Toko penerbit Jika ditentukan, cabang tempat toko berada menjadi cabang penerbit. Mengirim cabang lain akan ditolak.
useScope Cakupan penggunaan ALL (semua toko) atau BRANCH (cabang tertentu). Default ALL.
useBranchIdx Cabang penggunaan Hanya diperlukan saat useScope=BRANCH. Selalu kosong jika ALL.

Parameter yang tidak dapat digunakan — processStoreIdx (toko pemroses) menunjuk toko tempat verifikasi, penggunaan, penambahan, atau pengurangan benar-benar terjadi, sehingga tidak dapat dipakai pada API ini. Jika dikirim, akan ditolak dengan 400 (kode kesalahan 1227).

Fitur cabang dan toko hanya tersedia pada paket Business atau lebih tinggi.

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.

Mengapa perlu mengontrol jumlah stempel secara langsung

Dalam pengelolaan sistem stempel, ada situasi di mana jumlah stempel perlu disesuaikan secara manual, bukan hanya otomatis.

Contohnya termasuk koreksi kesalahan, pemberian bonus kampanye, dan penyesuaian manual oleh admin.

Dengan mengatur parameter stamps, Anda dapat menambah atau mengurangi nilai tanpa menimpa data yang ada.
Jika jumlah maksimum tercapai, Anda harus mengatur useYn menjadi Y untuk memproses penggunaan reward.

Alur penggunaan reward dan penerbitan ulang stempel

Mengatur useYn ke Y menandai stempel sebagai telah digunakan.

Setelah digunakan, stempel baru harus diterbitkan melalui API pembuatan untuk memulai kembali akumulasi.
Alur ini merupakan siklus inti dari program reward berbasis stempel.
Otomatisasi Penggunaan → Penerbitan baru → Akumulasi ulang membantu mendorong keterlibatan berulang.

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.

API ini hanya menggunakan token ketika benar-benar terjadi perubahan status penukaran hadiah (N → Y). Mengirim token pada pembaruan biasa yang hanya mengubah catatan, periode, atau status aktif akan ditolak dengan 400 (kode kesalahan 1227). Meskipun permintaan berisi useYn = Y, token tidak digunakan jika perubahan N → Y tidak benar-benar terjadi (misalnya hadiah sudah pernah ditukarkan).

API ini tidak menerima parameter toko pemroses (processStoreIdx). Saat hadiah ditukarkan, lokasi pemrosesan diambil dari toko yang terikat pada token saat validasi, bukan dari nilai dalam permintaan, lalu dicatat dalam event dan Webhook. Lokasi pemrosesan ini tidak diterapkan pada pembaruan biasa.

Token yang sama juga dapat digunakan dengan API Penukaran Hadiah (Redeem), tetapi hanya dapat digunakan satu kali pada salah satu dari kedua API. Setelah digunakan oleh salah satu API, token akan ditolak oleh API lainnya.

Kapan perlu reset PIN

Atur resetPinYn ke Y untuk mereset PIN pengguna.

Digunakan saat pengguna lupa PIN, mengganti perangkat, atau untuk alasan keamanan.

Setelah reset, pengguna akan diminta membuat PIN baru saat mengakses halaman stempel. Jika diatur ke N atau tidak dikirim, PIN lama tetap digunakan.

Contoh penggunaan

  • Koreksi kesalahan: Memperbaiki jumlah stempel yang salah
  • Pembaruan kampanye: Menyesuaikan perubahan aturan selama kampanye berjalan
  • Verifikasi ulang pengguna: Reset PIN untuk autentikasi ulang offline
  • Penonaktifan: Menonaktifkan stempel saat kampanye berakhir

Hal yang perlu diperhatikan

  • Pastikan perubahan pada stamps tetap konsisten dengan riwayat yang ada
  • Setelah ditandai digunakan (useYn), sebaiknya dianggap sebagai operasi yang tidak dapat dibatalkan
  • Kelola log operasional dan riwayat perubahan secara detail untuk kebutuhan audit