apskel-pos-backend/docs/backoffice-enakpoint.md

Backoffice EnakPoint & EnakCoin

30 Sep 2026

Backoffice perlu tujuh layar untuk mengelola program loyalitas: setting per outlet, setting per organisasi (termasuk kedaluwarsa), wallet customer, telusuri mutasi, PIN customer, riwayat setting, dan biaya main game.

Layar yang perlu dibuat

Semua endpoint di bawah base URL /api/v1, butuh login user dengan role Admin atau Manager, dan otomatis dibatasi ke organisasi user tersebut. Data customer atau outlet organisasi lain dijawab 404.

Layar	Endpoint	Tempat di menu
Setting loyalitas outlet	GET / PUT /outlets/:outlet_id/loyalty-settings	Outlet → detail outlet → tab Loyalitas
Setting loyalitas organisasi	GET / PUT /marketing/loyalty-settings (+ ?dry_run=true)	Marketing → Loyalitas → Pengaturan
Riwayat perubahan setting	GET /marketing/loyalty-settings/history	Marketing → Loyalitas → Riwayat
Wallet customer	GET /marketing/customers/:id/wallet, POST …/wallet/adjust	Customer → detail customer → tab Wallet
Telusuri mutasi	GET /marketing/wallet-transactions/:id/trace	Dibuka dari baris riwayat wallet
PIN & keamanan customer	DELETE /marketing/customers/:id/pin, GET …/security-events	Customer → detail customer → tab Keamanan
Biaya main game	PUT game yang sudah ada, metadata.coin_cost	Marketing → Game → edit game

Penempatan menu di atas adalah usulan; sesuaikan dengan struktur backoffice yang ada.

Istilah di layar. EnakPoint (POINT) adalah saldo yang bisa membayar order; EnakCoin (COIN) untuk main game dan bisa ditukar ke EnakPoint. Nilai rupiah EnakPoint selalu ditulis "setara potongan Rp …", tidak pernah "saldo Rp …", karena saldo tidak bisa dicairkan.

Format response. Sukses { "success": true, "data": … }; gagal { "success": false, "errors": [{ "code", "entity", "cause" }] }. Tampilkan cause sebagai pesan (lihat bagian Pesan error).

Setting loyalitas outlet

Tiap outlet mengatur sendiri berapa EnakPoint dan EnakCoin yang didapat dari order, dan apakah outlet menerima pembayaran EnakPoint. Semua nilai default mati sampai owner menyalakannya.

GET /outlets/:outlet_id/loyalty-settings → isi form. PUT ke path yang sama dengan objek yang sama untuk menyimpan; field yang tidak dikirim tetap, field tak dikenal ditolak.

{
  "point": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 100, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "coin": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 25000, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "point_payment": { "accept_payment": true, "min_payment_points": 1, "max_payment_percent": 100 }
}

Field	Label usulan	Tipe	Default	Validasi
point.enabled / coin.enabled	Beri EnakPoint / EnakCoin	toggle	mati	–
earn_mode	Cara hitung: per nominal / persentase	pilihan PER_AMOUNT / PERCENTAGE	PER_AMOUNT	salah satu dari keduanya
earn_per_amount	Setiap belanja Rp … (mode PER_AMOUNT)	Rp	100 (point), 25.000 (coin)	> 0
earn_value	… mendapat (mode PER_AMOUNT)	angka	1	≥ 0
earn_percent	… % dari belanja (mode PERCENTAGE)	%, boleh desimal	1	0–100, maks. 2 angka desimal
min_order_amount	Minimal belanja	Rp	0	≥ 0
max_per_order	Maksimal per order	angka, boleh kosong	kosong = tanpa batas	≥ 0
point_payment.accept_payment	Terima pembayaran EnakPoint	toggle	mati	–
min_payment_points	Minimal EnakPoint per pembayaran	angka	1	≥ 1
max_payment_percent	Maksimal porsi order dibayar EnakPoint	%	100	0–100

Cashback efektif. Response membawa point_cashback_percent dan point_value. Tampilkan persentase di samping field earning EnakPoint, mis. "setara cashback 1%", dan hitung ulang di sisi klien saat owner mengetik: earn_value × point_value ÷ earn_per_amount × 100, atau pada mode PERCENTAGE: earn_percent × point_value. Tujuannya agar owner tidak salah membaca skala (1 per Rp 100 bukan 1 per Rp 1).

Mode earning. Tampilkan hanya field mode yang dipilih (earn_per_amount + earn_value, atau earn_percent). Field mode lain tetap tersimpan di server, jadi tidak perlu dikosongkan saat owner berpindah mode. Pada mode PERCENTAGE jumlah yang didapat adalah floor(basis × earn_percent ÷ 100), mis. 2,5% dari Rp 87.500 = 2.187 EnakPoint.

Contoh di bawah form. "Belanja Rp 87.500 mendapat 875 EnakPoint dan 3 EnakCoin." Earning dihitung dari subtotal setelah diskon, sebelum pajak, dan bagian yang dibayar EnakPoint tidak ikut dihitung.

Setelah PUT, response membawa changes (key yang berubah); tampilkan toast singkat, mis. "2 pengaturan disimpan". Mematikan accept_payment langsung menyembunyikan method EnakPoint di kasir outlet itu.

Setting loyalitas organisasi

Nilai rupiah EnakPoint, kurs exchange, batas transfer, dan kedaluwarsa berlaku sama untuk semua outlet, jadi diatur sekali per organisasi. Mengubah nilai EnakPoint atau kurs langsung mengubah daya beli semua saldo customer, jadi layar ini wajib menampilkan dampaknya sebelum disimpan.

{
  "point_value": 1,
  "exchange": { "coin_amount": 1, "point_amount": 1 },
  "transfer": { "enabled": true, "min_amount": 1, "max_per_transaction": null, "daily_limit": null },
  "point_expiry": { "…": "lihat bagian kedaluwarsa" },
  "coin_expiry": { "…": "lihat bagian kedaluwarsa" }
}

Field	Label usulan	Default	Validasi
point_value	Nilai 1 EnakPoint (Rp)	1	≥ 1
exchange.coin_amount : exchange.point_amount	Kurs tukar: … EnakCoin = … EnakPoint	1 : 1	keduanya ≥ 1
transfer.enabled	Izinkan transfer antar customer	aktif	–
transfer.min_amount	Minimal per transfer	1	≥ 1
transfer.max_per_transaction	Maksimal per transfer	kosong = tanpa batas	≥ 1
transfer.daily_limit	Batas harian per customer	kosong = tanpa batas	≥ 1, dihitung per currency, reset tengah malam WIB

Alur simpan

1. Owner mengubah form.
2. Tombol Simpan memanggil PUT /marketing/loyalty-settings?dry_run=true dengan objek yang diubah. Tidak ada yang tersimpan.
3. Bila changes kosong, beri tahu "tidak ada perubahan" dan berhenti.
4. Tampilkan dialog konfirmasi berisi changes, impact (bila point_value atau kurs berubah), dan expiry_activations (bila ada, lihat bagian kedaluwarsa).
5. Konfirmasi memanggil PUT yang sama tanpa dry_run.

Dialog dampak

impact berisi saldo beredar organisasi dan nilainya sebelum/sesudah:

Field impact	Tampilkan sebagai
outstanding_points	EnakPoint beredar
point_rupiah_before → point_rupiah_after	Setara potongan Rp … → Rp …
outstanding_coins	EnakCoin beredar
coins_as_points_before → coins_as_points_after	Bila semua ditukar: … EnakPoint → … EnakPoint
coin_rupiah_before → coin_rupiah_after	Setara potongan Rp … → Rp …

Contoh kalimat: "Menaikkan nilai EnakPoint dari Rp 1 ke Rp 2 membuat 1.250.000 EnakPoint yang beredar setara potongan Rp 2.500.000 (sebelumnya Rp 1.250.000)." Perubahan hanya berlaku ke depan: pembayaran, refund, dan exchange yang sudah terjadi memakai nilai saat itu.

Pengaturan kedaluwarsa

Kedaluwarsa diatur terpisah untuk EnakPoint (point_expiry) dan EnakCoin (coin_expiry) dengan salah satu dari dua model; defaultnya mati, dan bila dinyalakan defaultnya hangus setiap 31 Desember.

"point_expiry": {
  "enabled": true,
  "mode": "FIXED_DATE",
  "fixed_dates": ["12-31"],
  "grace_months": 3,
  "period": 12,
  "unit": "MONTH",
  "end_of_month": false,
  "reminder_days": 7
}

Field	Tampil saat	Label usulan	Validasi
enabled	selalu	Saldo bisa kedaluwarsa	–
mode	aktif	Model: Tanggal tetap / Sejak didapat	FIXED_DATE atau ROLLING
fixed_dates	FIXED_DATE	Tanggal hangus setiap tahun	minimal satu, format MM-DD, 02-29 ditolak
grace_months	FIXED_DATE	Periode tanggung (bulan)	0–24, default 3
period + unit	ROLLING	Berlaku selama … hari/bulan	period ≥ 1, DAY atau MONTH
end_of_month	ROLLING	Bulatkan ke akhir bulan	–
reminder_days	aktif	Ingatkan customer … hari sebelumnya	≥ 0, 0 = tanpa pengingat

Tanggal tetap (FIXED_DATE). Semua saldo hangus di tanggal yang sama, mis. 31 Desember, atau 30 Juni dan 31 Desember untuk dua kali setahun. Saldo yang didapat kurang dari grace_months sebelum tanggal itu ikut ke tanggal berikutnya, jadi saldo yang didapat 1 Oktober dengan tanggung 3 bulan hangus 31 Desember tahun depan. Untuk input fixed_dates, pakai pemilih tanggal+bulan tanpa tahun.

Sejak didapat (ROLLING). Tiap saldo berlaku period hari atau bulan sejak masuk, mis. 12 bulan. Dengan end_of_month, saldo yang didapat 14 Maret 2026 hangus 31 Maret 2027.

Preview. Response GET, PUT, dan dry run membawa expiry_preview.point dan .coin: kapan saldo yang didapat sekarang akan kedaluwarsa (null = tidak). Tampilkan di bawah form: "EnakPoint yang didapat hari ini kedaluwarsa pada 31 Des 2026." Karena dihitung dari nilai yang dikirim, dry run bisa dipakai untuk memperbarui preview saat owner mengubah pilihan.

Menyalakan pertama kali. Saldo lama yang belum punya tanggal ikut diberi tanggal, dengan masa berlaku penuh: tanggal hangus kedua berikutnya (FIXED_DATE) atau satu periode sejak hari ini (ROLLING). Dry run mengembalikan expiry_activations; tampilkan di dialog konfirmasi dengan kalimat tegas, mis. "1.250.000 EnakPoint milik customer yang ada sekarang akan kedaluwarsa pada 31 Des 2027. Tindakan ini tidak bisa dibatalkan dengan mematikan kedaluwarsa."

Field expiry_activations[]	Arti
currency	POINT atau COIN
lots	Jumlah paket saldo yang diberi tanggal
amount	Total saldo yang diberi tanggal
expires_at	Tanggal kedaluwarsanya

Aturan lain yang perlu dijelaskan di layar:

• Mengubah model atau masa berlaku hanya berlaku untuk saldo yang masuk setelahnya.
• Mematikan kedaluwarsa tidak membatalkan tanggal yang sudah terjadwal.
• Saldo yang ditransfer atau ditukar membawa tanggal kedaluwarsa aslinya.
• Saldo hangus tanpa kompensasi apa pun. Customer mendapat pengingat push reminder_days hari sebelumnya dan notifikasi saat hangus.

Wallet customer

Tab Wallet di detail customer dipakai untuk menangani komplain: melihat saldo dan asal-usulnya, mengoreksi saldo, dan menelusuri satu mutasi sampai ke order asalnya.

Saldo, lot, dan riwayat

GET /marketing/customers/:id/wallet?page=1&limit=20&currency=POINT&type=PAYMENT,EARN&from=2026-09-01&to=2026-09-30 (semua query opsional, sama seperti riwayat di aplikasi customer)

{
  "customer": { "id": "…", "name": "Budi Santoso", "phone": "081234561234" },
  "point_balance": 12650,
  "coin_balance": 8,
  "spendable_point_balance": 12500,
  "spendable_coin_balance": 8,
  "lots": [
    { "id": "…", "currency": "POINT", "original_amount": 875, "remaining_amount": 875, "expires_at": "2026-12-31T23:59:59+07:00", "expired": false, "source_transaction_id": "…", "origin_lot_id": null, "created_at": "…" }
  ],
  "transactions": {
    "data": [
      {
        "id": "…", "currency": "POINT", "type": "TRANSFER_OUT", "amount": -120, "balance_after": 12650,
        "description": "Transfer ke An*** (08**-****-5678)",
        "destination": { "type": "WALLET_TX", "id": "…" },
        "counterparty": { "id": "…", "name": "Anita Rahma" },
        "created_by": null, "outlet": null, "reason": null, "metadata": {},
        "created_at": "…"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 }
  }
}

• Saldo: tampilkan spendable_* sebagai saldo utama. point_balance / coin_balance bisa sedikit lebih besar selama ada lot yang sudah lewat tanggal tapi belum diproses job kedaluwarsa (paling lama sekitar 15 menit).
• Lot: tabel paket saldo yang masih berisi, urut dari yang paling cepat kedaluwarsa. Beri tanda untuk expired: true.
• Riwayat: sama dengan riwayat customer, ditambah nama asli yang disamarkan untuk customer: counterparty (lawan transfer), created_by (admin pelaku adjustment atau kasir penerima pembayaran), outlet, reason, dan metadata (kurs, nilai EnakPoint yang dibekukan, shortfall).

Adjustment manual

POST /marketing/customers/:id/wallet/adjust

{ "currency": "POINT", "amount": -500, "reason": "Komplain #45", "idempotency_key": "adj-7f3c" }

Field	Aturan
currency	POINT atau COIN
amount	Bertanda, tidak boleh 0. Positif menambah, negatif mengurangi
reason	Wajib; tampil di riwayat customer sebagai "Koreksi oleh admin: …"
idempotency_key	Opsional tapi disarankan: buat satu nilai saat dialog dibuka, supaya klik ganda tidak mengoreksi dua kali

Pengurangan yang melebihi saldo yang bisa dipakai ditolak 304. Adjustment tambah mengikuti aturan kedaluwarsa organisasi. Response: { "transaction", "spendable_point_balance", "spendable_coin_balance", "replayed" }. Beri catatan di dialog bahwa adjustment tidak disertai pembayaran uang, sehingga alasan tidak boleh "pencairan".

Telusuri mutasi

Dari baris riwayat mana pun, tombol Telusuri memanggil GET /marketing/wallet-transactions/:id/trace.

{
  "transaction": { "id": "…", "customer": { "id": "…", "name": "Budi Santoso" }, "currency": "POINT", "type": "PAYMENT", "amount": -30, "description": "Bayar #ORD-0456 di Outlet Kemang (Rp 30)", "reference_type": "PAYMENT", "reference_id": "…", "created_at": "…" },
  "lots": [
    {
      "amount": 30,
      "chain": [
        { "lot": { "id": "…", "expires_at": "…", "origin_lot_id": "…" }, "source": { "type": "TRANSFER_IN", "customer": { "name": "Budi Santoso" }, "description": "Transfer dari An*** (08**-****-5678)" } },
        { "lot": { "id": "…", "origin_lot_id": null }, "source": { "type": "EARN", "customer": { "name": "Anita Rahma" }, "reference_type": "ORDER", "reference_id": "…", "description": "Belanja #ORD-1 di Outlet Kemang" } }
      ]
    }
  ]
}

Tampilkan tiap lots[] sebagai rantai dari atas ke bawah: jumlah yang lewat lot itu, lalu setiap langkah chain dengan pemilik, tipe, dan deskripsinya. Langkah terakhir selalu EARN, ADJUSTMENT, atau MIGRATION; bila reference_type = ORDER, jadikan tautan ke detail order. Mutasi keluar menampilkan lot yang dipakai; mutasi masuk menampilkan lot yang dibuatnya.

PIN, riwayat setting, game, dan method EnakPoint

PIN & keamanan customer

Admin tidak bisa membuat, mengganti, atau melihat PIN customer; satu-satunya aksi adalah menghapusnya, misalnya bila customer kehilangan akses, sehingga customer harus membuat PIN baru lewat OTP di aplikasi.

• DELETE /marketing/customers/:id/pin dengan body { "reason": "Customer ganti nomor HP" }. reason wajib. Tampilkan dialog konfirmasi dengan input alasan.
• GET /marketing/customers/:id/security-events?page=1&limit=20 untuk tab Keamanan:

{
  "data": [
    { "id": "…", "event": "PIN_LOCKED", "actor_user": null, "reason": null, "ip_address": "103.10.0.7", "user_agent": "EnakApp/2.4 (Android 14)", "created_at": "…" }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 5, "total_pages": 1 }
}

event	Label usulan
PIN_SET	PIN dibuat
PIN_CHANGED	PIN diganti
PIN_RESET	PIN direset lewat OTP (transfer ditahan 24 jam)
PIN_FAILED	PIN salah dimasukkan
PIN_LOCKED	PIN terkunci 30 menit
PIN_REMOVED_BY_ADMIN	PIN dihapus admin (actor_user, reason terisi)

Riwayat perubahan setting

GET /marketing/loyalty-settings/history?page=1&limit=20 untuk setting organisasi; tambah &outlet_id=… untuk riwayat satu outlet.

{ "id": "…", "organization_id": "…", "outlet_id": null, "key": "loyalty.point.value", "old_value": "1", "new_value": "2", "changed_by": "…", "created_at": "…" }

old_value null berarti sebelumnya masih nilai default. Tampilkan key dengan label yang sama seperti di form (mis. loyalty.point.value → "Nilai 1 EnakPoint"), dan changed_by sebagai nama user.

Biaya main game

Semua game (spin, raffle, minigame) memakai EnakCoin yang sama. Biaya per main diisi di metadata.coin_cost saat membuat atau mengedit game (/marketing/games): bilangan bulat ≥ 1, default 1 bila kosong. Nilai pecahan, 0, atau teks membuat game tidak bisa dimainkan. Karena metadata dikirim utuh, pertahankan key metadata lain saat menyimpan. Hadiah game juga bernilai rupiah secara tidak langsung, karena EnakCoin bisa ditukar ke EnakPoint.

Method pembayaran EnakPoint

Method "EnakPoint" (tipe point) dibuat otomatis untuk setiap organisasi. Di layar Payment Method (/payment-methods):

• Tampilkan sebagai method sistem: tombol hapus dan pilihan ubah tipe disembunyikan; backend menolaknya (304). Nama boleh diganti.
• Tipe point tidak ditawarkan saat membuat method baru.
• Kasir hanya melihatnya di outlet yang menyalakan "Terima pembayaran EnakPoint".

Di laporan per payment method, EnakPoint tampil terpisah dan tidak dihitung sebagai kas masuk.

Pesan error dan checklist

code	HTTP	Kapan terjadi di backoffice	Yang ditampilkan
303, 310	400	Body tidak valid, field tak dikenal di PUT setting, UUID salah	Pesan umum "Data tidak valid" + cause untuk developer
304	400	Nilai di luar batas, adjustment melebihi saldo, alasan kosong, hapus/ubah method EnakPoint	cause di dekat field atau di toast
404	404	Customer, outlet, atau mutasi bukan milik organisasi ini	"Data tidak ditemukan"
900	500	Kesalahan server	"Terjadi kesalahan, coba lagi"

Pesan cause saat ini berbahasa Inggris, mis. invalid loyalty settings: loyalty.point.earn_per_amount must be at least 1. Untuk validasi form, lebih baik cek batasnya di sisi klien (tabel di tiap bagian) dan tampilkan cause hanya sebagai cadangan.

Checklist rilis

• Form setting outlet menampilkan cashback efektif dan contoh earning.
• Setting organisasi selalu lewat dry run dan dialog konfirmasi sebelum disimpan.
• Dialog konfirmasi menampilkan impact saat nilai EnakPoint atau kurs berubah.
• Dialog konfirmasi menampilkan expiry_activations saat kedaluwarsa dinyalakan pertama kali.
• Preview "yang didapat hari ini kedaluwarsa pada …" tampil di bawah pengaturan kedaluwarsa.
• Wallet customer menampilkan saldo yang bisa dipakai, lot, dan riwayat dengan nama asli.
• Adjustment mewajibkan alasan dan mengirim idempotency_key.
• Tombol Telusuri ada di setiap baris riwayat.
• Hapus PIN mewajibkan alasan; tab Keamanan menampilkan log.
• Method EnakPoint tampil sebagai method sistem.
• Form game punya input coin_cost.
• Semua nilai rupiah EnakPoint ditulis "setara potongan Rp …".

Pembayaran EnakPoint belum boleh dirilis ke outlet sebelum tinjauan keuangan (N2) dan legal (N3) selesai, dan transfer menunggu tinjauan legal (N3). Layar backoffice boleh disiapkan lebih dulu.