Instal aplikasi Vivoldi dari Google Play untuk membuatnya lebih nyaman.

API Kurangi Stempel (v2)

API Kurangi Stempel mengurangi jumlah stempel pada data yang ada sebanyak satu.

API ini tidak digunakan dalam alur normal, melainkan untuk koreksi seperti perbaikan akumulasi yang salah, perubahan aturan kampanye, atau penanganan klaim pengguna.
Jumlah stempel tidak akan pernah turun di bawah nol.

API ini tersedia mulai dari paket Personal ke atas.

PUT

/api/stamp/v2/remove 

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required
Stamp IDX.
stamps integer
Jumlah stempel yang ditambahkan (atau dikurangi). Default 1 dan harus lebih besar dari 0.
Jumlah yang melebihi batas kartu atau kurang dari nol akan disesuaikan server. Jika perubahan sebenarnya 0, riwayat dan webhook tidak dibuat.
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.

Kapan perlu pengurangan stempel

API ini tidak digunakan secara rutin, melainkan sebagai alat untuk menangani masalah data.
Digunakan dalam kondisi berikut:

  • Event diproses dua kali sehingga stempel bertambah ganda
  • Kesalahan sistem menyebabkan penambahan stempel tidak valid
  • Perubahan aturan kampanye memerlukan penyesuaian data
  • Pembatalan akumulasi yang salah

Data yang salah dapat meningkatkan biaya dan menurunkan kepercayaan.
API ini memungkinkan perbaikan secara langsung.

Hubungan dengan Add Stamp API

Kedua API bekerja berlawanan arah, namun memiliki peran yang jelas.

  1. Add Stamp → Mencatat aksi pengguna dalam alur normal
  2. Remove Stamp → Mengoreksi atau melakukan rollback data

Setiap penggunaan Add Stamp API harus mempertimbangkan skenario gagal dan pembatalan,
dan mengintegrasikan Remove Stamp untuk memastikan sistem tetap stabil.

Poin penting dalam operasional

API Pengurangan Stempel tidak digunakan secara rutin, tetapi merupakan API penting untuk menangani masalah data.

  • Data yang tidak diperbaiki dapat menurunkan kepercayaan pengguna
  • Akumulasi berlebih meningkatkan biaya reward
  • Dapat berdampak negatif pada pengalaman pengguna

Gunakan bersama audit log dan kontrol akses admin yang ketat.

Hal yang perlu diperhatikan

  • Jumlah stempel tidak akan kurang dari 0. Periksa stamps melalui API Validasi sebelum pengurangan
  • Pemanggilan berulang dapat menyebabkan pengurangan berlebih
  • Jangan dipanggil langsung dari client; lakukan kontrol di server
  • Simpan riwayat pengurangan dan lindungi dengan kontrol akses admin