API Tambah Stempel (v2)

API Tambah Stempel menambahkan satu stempel ke data stempel yang sudah ada.

Ketika pengguna menyelesaikan pembelian, kunjungan, atau aksi tertentu, API ini secara otomatis menambahkan satu stempel.
Jika jumlah maksimum pada kartu telah tercapai, stempel tidak akan ditambahkan lagi.

API ini tersedia mulai dari paket Personal ke atas.

API Version

PUT

/api/stamp/v2/add

Request
Response

{
    "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.

Mengapa API ini inti sistem

Jika API Create menerbitkan kartu, API Add mencatat aksi nyata pengguna.

Setiap pembelian atau kunjungan akan dicatat, memungkinkan sistem reward berbasis perilaku tanpa sistem poin tambahan.

Satu panggilan API dapat langsung menghubungkan aksi seperti pembayaran, pembelian, atau partisipasi ke akumulasi stempel.

Penanganan saat maksimum tercapai

Jika jumlah maksimum tercapai, stempel tidak akan ditambahkan lagi.
Alur yang disarankan:

Periksa stamps dan maxStamps
Jika sama, berarti sudah penuh
Gunakan Update API dan set useYn ke Y
Panggil Stamp Create API untuk memulai siklus baru
Lanjutkan dengan proses akumulasi berikutnya

Syarat dan batasan akumulasi

Akumulasi stempel tidak selalu diterapkan secara otomatis.

Harus memenuhi kondisi berikut:

Stempel dalam status aktif (activeYn = Y)
Dalam periode berlaku (strtYmd ~ endYmd)
Belum mencapai jumlah maksimum (stamps < maxStamps)
Belum digunakan

Kondisi ini memastikan akumulasi sesuai dengan aturan kampanye.

Contoh penggunaan

Event kunjungan: Tambahkan satu stempel saat pengguna berkunjung
Reward pembelian: Tambahkan stempel otomatis setelah pembayaran
Event berbasis misi: Berikan stempel saat aksi tertentu selesai
Check-in harian: Tambahkan satu stempel setiap login harian

Poin penting dalam operasional

API akumulasi stempel adalah komponen penting yang memengaruhi kualitas event secara langsung.

Akumulasi yang tidak tepat dapat menurunkan kepercayaan pengguna
Pemanggilan API ganda dapat menyebabkan akumulasi berlebih
Berpengaruh langsung pada pengalaman pengguna

Gunakan selalu bersama validasi dan kontrol logika di sisi server.