API Administrative Console v1.0.0

Autentikasi email & password. Mengembalikan JWT Token dan daftar permission codes (Mendukung `application/json` & `multipart/form-data`).

Mengambil data detail profil user terautentikasi (termasuk Full Avatar URL & list permissions).

Mengedit nama dan email user (Mendukung `application/json` & `multipart/form-data`).

Mengubah password user setelah verifikasi password lama (`old_password` & `new_password`).

Upload file foto profil (`multipart/form-data` key: `file`). Mengembalikan **Full Avatar URL**.

Daftar master toko, urut code menaik. Filter: search/q, is_jabodetabek, is_active, city, region, page, limit. Filter boolean menerima true/1/ya dan false/0/tidak; nilai tak dikenal diabaikan (bukan dianggap false).

Unduh file contoh berisi header yang dikenali importer, atau export master toko saat ini. Query ?format=xlsx (default) atau ?format=csv.

Import daftar toko dari file .xlsx atau .csv (multipart, field file). Jalankan dry_run=true lebih dulu untuk melihat rencana perubahan tanpa menyentuh database.

Aktivasi, non-aktifkan, atau hapus banyak toko sekaligus berdasarkan daftar ids.

Tambah satu gerai baru ke master toko.

Detail satu toko beserta jumlah voucher terkait.

Perbarui data satu toko.

Hapus (soft delete) satu toko.

Daftar master gedung NFC TapOn dengan filter search, area, building_type, nearest_store, is_active, page, limit.

Import file building list dari vendor (.xlsx atau .csv). Header dicari otomatis walau file diawali blok judul & statistik. Baris dicocokkan berdasarkan Building ID: sudah ada = update, belum ada = create.

Unduh master gedung sebagai .xlsx atau .csv (memakai filter pada panel daftar gedung di atas). Tombol kedua mengunduh file template berisi header yang dikenali importer.

Tambah satu gedung TapOn secara manual.

Ubah data satu gedung. Perubahan Building ID otomatis tersalin ke seluruh link UTM milik gedung tersebut.

Hapus gedung. Ditolak bila masih dipakai link UTM, kecuali ditambahkan query ?force=true.

Aksi massal gedung: activate, deactivate, atau delete.

Menampilkan daftar event kampanye dengan **filter query**: `search`/`q`, `code`, `building_category`, `is_active`, `page`, & `limit`.

Menampilkan detail spesifik 1 Event Kampanye berdasarkan ID.

Membuat Event Kampanye promo baru. Aturan: 1 email per periode, batasan kota (allowed_cities), valid_days / live_minutes, dan daftar gedung UTM default (utm_building_ids) yang dipakai saat generate link.

Wajib: code (unik, otomatis di-uppercase) & name. Default bila kosong: valid_days_type = PLUS_DAYS, valid_days = 7, one_email_per_period = true, is_active = true, stock_limit = 0 (unlimited). Ditolak 400: end_date ≤ start_date, atau FIXED_DATE tanpa/melebihi expire_fixed_date di luar end_date. 409: kode event sudah dipakai.

landing_url mendukung placeholder {event_code} / {event_id}. Isi hanya bila kampanye diarahkan ke halaman di luar aplikasi klaim (microsite). Kosong = normal: tap berhenti di short link /t/{slug} dan halaman klaim menukar slug itu ke atribusinya lewat GET /api/v1/t/:slug.

Mengubah tanggal atau aturan event kampanye. Full replace: field yang tidak dikirim direset ke nilai kosong/default — untuk ubah sebagian saja pakai PATCH /api/v1/events/:id/settings.

Pengecualian: allowed_cities dan utm_building_ids hanya berubah bila field-nya benar-benar dikirim. Bila diabaikan, daftar lama dipertahankan — supaya form edit yang tidak menyertakan keduanya tidak diam-diam mengosongkan daftar gedung dan bikin POST /utm/links/generate gagal. Kirim [] secara eksplisit bila memang ingin mengosongkan.

Validasi sama dengan POST (end_date > start_date, FIXED_DATE tidak melewati end_date, kode unik). Mengubah aturan tidak mengubah voucher yang sudah terlanjur diklaim — claim_expires_at dikunci saat klaim.

Menghapus Event Kampanye (Soft Delete).

Menampilkan semua voucher yang terkait dengan event tertentu (filter: status, search, page, limit) + statistik agregat (UNUSED / LIVE / USED / EXPIRED).

Menampilkan detail pengaturan kampanye event (toggle aktif, aturan expiry, Jabodetabek only, 1 email per periode) beserta statistik voucher per status.

Setting yang ditandai is_public = true, dipakai halaman klaim yang tidak punya JWT. Kegunaan utamanya: membaca allowed_email_domains agar form bisa memberi tahu domain yang diterima sebelum pengunjung menekan kirim.

Hanya key, value, dan group yang dikirim — description bisa memuat catatan internal, jadi sengaja tidak ikut.

Customer klaim voucher dengan memasukkan data nama, email, hp, dan parameter UTM (Mendukung JSON / Form-Data).

Wajib: event_id, client_name, client_email. Semua aturan (periode aktif, 1 email 1x, stok, masa berlaku) dibaca dari event tersebut.

Atribusi UTM: cukup teruskan utm_id (ID link hasil generate) yang sudah ada di query string landing page. Server menyalin utm_source, utm_medium, utm_campaign, utm_term, utm_content, dan kode gedung dari baris link tersebut — parameter utm_* di URL tidak dibaca sama sekali, jadi atribusi tidak bisa dikarang pengunjung yang mengedit address bar.

slug tetap diterima sebagai cadangan untuk stiker lama yang dicetak sebelum utm_id ada. Tanpa keduanya (mis. pengunjung membuka landing page langsung), klaim tetap diterima dan dicatat sebagai direct / web / kode event.

Error: 409 email sudah klaim di periode ini · 400 event non-aktif / belum mulai / sudah berakhir / stok habis · 404 event tidak ada.

Response: data.link (URL voucher digital /v/:token) + data.voucher. Field code masih null di tahap ini. Email voucher dikirim async lewat rotasi SMTP; kegagalan kirim tidak menggagalkan klaim (tercatat di /api/v1/smtp/failed-logs dan bisa dikirim ulang).

Menampilkan status voucher & sisa waktu timer (jika status LIVE). Dipakai halaman voucher digital /v/:token.

Response hanya berisi field publik (tanpa PII lengkap / internal event). code = null selama status UNUSED. Pakai live_expires_at untuk hitung mundur dan claim_expires_at untuk masa berlaku voucher. Setiap request ikut menyapu voucher yang sudah lewat masa berlakunya, jadi status yang dikembalikan selalu terkini.

Aktivasi slider voucher oleh Kasir di toko. Memulai timer expiry realtime sepanjang live_minutes event (default 10 menit).

Validasi store_code (berurutan): (1) harus ada di master toko — kode salah = 400 dan kasir bisa mengetik ulang, voucher tetap UNUSED; (2) toko harus is_active = true; (3) bila event punya allowed_cities, kota toko wajib termasuk. Pengecekan ini jalan walau allowed_cities kosong.

Idempoten: voucher yang sudah LIVE mengembalikan 200 tanpa mereset timer. Status VOID / EXPIRED / USED ditolak 400.

Di sinilah kode voucher muncul: setelah sukses, response memuat code, live_expires_at, dan store_code yang tercatat.

Menandai voucher sebagai USED (Telah Terpakai) oleh Kasir di POS. Voucher wajib berstatus LIVE — status lain ditolak 400.

Payload opsional untuk analytics: event_id dicek silang dengan event pemilik voucher (tidak cocok = 400), dan utm_id memperbarui atribusi voucher dengan data link tersebut (source, medium, campaign, term, content, kode gedung) sehingga jejak sumber tercatat di titik redeem. Kirim body kosong bila tidak diperlukan.

Menampilkan laporan seluruh klaim voucher terdaftar dengan **filter query**: `event_id`, `status`, `search`/`q`, `page`, & `limit`.

Menambahkan single voucher baru secara manual terikat ke ID Event / Kampanye Promo.

Export seluruh data voucher (atau terfilter per Event ID & status) langsung ke format file Excel (.xlsx, default) atau CSV.

Ringkasan voucher dihitung dari SELURUH data yang cocok filter (opsional event_id), bukan cuma satu halaman list. Balasannya berisi hitungan per status (unused/live/used/used_pos/expired/void) plus status pengiriman email (not_sent/sent/pending/failed) dari smtp_failed_logs.

Menampilkan detail lengkap data voucher berdasarkan **ID** database.

Memperbarui data DASAR voucher (kode, judul, nilai, keterangan, status, kampanye) berdasarkan ID.

Menghapus data voucher dari sistem berdasarkan ID.

Kirim ulang email voucher ke client_email yang SUDAH tersimpan di voucher ini. Beda dari /vouchers/resend-failed: itu massal berdasar log gagal, ini satu voucher tertentu.

Gagal bila: voucher belum punya client_email (belum diklaim) atau sudah dihanguskan (voided_at terisi).

Menempelkan client_name + client_email ke SATU voucher tertentu (by ID) lalu langsung mengirim email klaimnya. Berbeda dari POST /claim (publik, ambil voucher random dari stok event): di sini vouchernya sudah ditentukan operator, dan menimpa penerima lama kalau voucher itu sebelumnya sudah punya penerima.

Gagal bila: voucher sudah dihanguskan, kampanyenya tidak aktif / belum mulai / sudah berakhir (jendela tanggal sama persis dengan POST /claim), atau client_name/client_email kosong/tidak valid.

Kenapa jendela tanggal dicek: tanpa itu, claim_expires_at yang dihitung bisa jatuh di masa lalu (di-clamp ke event.end_date yang sudah lewat) — voucher tersimpan UNUSED dengan expiry basi, lalu permintaan list berikutnya (yang menjalankan sweeper) langsung menghanguskannya sendiri.

Mengosongkan client_name/client_email/client_phone pada voucher. Status & timer voucher tidak diubah. Data penerima yang dihapus dipindah ke last_client_name/last_client_email sebagai jejak — masih terlihat di response, hanya tidak lagi jadi tujuan resend email.

Gagal bila: voucher ini memang belum punya penerima.

Menukar slug stiker dengan atribusinya. Dipanggil halaman klaim tepat setelah tap.

Response: utm_id, event_id, event_code, event_name, building_code, building_name, building_area, landing_url (opsional, bila kampanye diarahkan ke microsite di luar aplikasi klaim).

Endpoint ini MENCATAT tap. Panggil sekali per kunjungan dan lakukan di sisi server — memanggilnya dari effect komponen yang bisa jalan dua kali akan menggandakan angka tap.

Status: 200 aktif · 410 link ada tapi kampanye/link sudah nonaktif (tap tetap dicatat, berguna untuk memutuskan penarikan stiker) · 404 slug tidak dikenal.

Inti sistem: signing event ke kode gedung. Setiap gedung terpilih mendapat satu link unik.
Cara pilih gedung (salah satu):
• utm_building_ids sudah diset di event → cukup kirim { "event_id": 1 } — gedung diambil otomatis dari event
• building_ref_ids / building_codes — override eksplisit per request
• all_buildings: true + filter — seluruh gedung aktif (bisa dipersempit dengan area, building_type, dll)
Pakai dry_run: true untuk simulasi tanpa simpan. Pakai overwrite: true untuk memperbarui parameter link yang sudah ada (slug tidak berubah, stiker lama tetap hidup).

Bila tidak dikirim di body, nilai UTM diturunkan otomatis: utm_source = tmn, utm_medium = nfc, utm_campaign = kode event, utm_term = tipe gedung, dan utm_content = kode gedung dari master. Target stiker selalu short link /t/{slug}; landing_url event hanya dipakai bila kampanye diarahkan ke halaman luar. Event tidak menyimpan utm_source / utm_medium / utm_campaign sendiri — sumber UTM adalah master gedung + kode event, jadi tidak ada dua tempat yang mendefinisikan hal yang sama.

Response berisi baris per gedung dengan status: created / updated / skipped (link sudah ada & overwrite false), lengkap dengan slug, short_url, dan full_url. Serahkan hasilnya ke vendor stiker lewat GET /api/v1/utm/links/export. Tanpa pilihan gedung apa pun (event juga tidak punya utm_building_ids) request ditolak 400.

{
  "event_id": 1,
  "building_ref_ids": [1, 2, 5],
  "utm_source": "tapon",
  "utm_medium": "nfc",
  "utm_campaign": "",
  "overwrite": false,
  "dry_run": true
}

Daftar link UTM beserta short_url — satu-satunya URL yang dipakai, dicetak di stiker. Field full_url sudah dihapus dari response.

Unduh file TMN Link Builder siap kirim ke pihak UTM: kolom asli vendor + kolom Link (short link), slug, parameter UTM, dan jumlah tap. Kolom Full URL sudah dihapus — vendor cukup memasang short link.

Buat satu link manual untuk pasangan event + gedung. Parameter UTM yang dikosongkan diisi otomatis dari pengaturan event dan data gedung.

Detail satu link berikut 20 tap terakhir.

Ubah parameter UTM, landing override, catatan, atau status aktif sebuah link. Field yang tidak dikirim tidak diubah.

Hapus link. Short link yang sudah tercetak di stiker akan mati (tap diarahkan ke 404).

Aksi massal link: activate, deactivate, delete, atau regenerate_slug (ganti slug bila stiker dicetak ulang).

Ringkasan performa per gedung: jumlah tap NFC versus jumlah voucher yang benar-benar diklaim, plus persentase konversi.

Log mentah setiap tap NFC: slug, kode gedung, IP, user agent, dan waktu tap.

Efektivitas kampanye diukur dari data yang benar-benar dimiliki sistem ini — tap stiker NFC, buka email, klaim, dan aktivasi kasir — bukan dari kanal iklan digital, karena trafiknya memang tidak datang dari sana.

Filter query: event_id, start_date, end_date (terima YYYY-MM-DD maupun RFC3339), dan limit (jumlah baris tiap pecahan, maks 200, default 20). Rentang waktu diterapkan pada peristiwa yang relevan tiap bagian: tap pakai waktu tap, klaim pakai claimed_at, toko pakai opened_at.

Baca angkanya dengan jujur: emails_opened adalah batas bawah — klien email yang memblokir gambar tidak akan memuat pixel dan tidak terhitung, jadi jangan pakai angka ini sebagai jumlah pasti orang yang membaca email. Sebaliknya, sebagian klien memuat gambar lewat proxy mereka sendiri (Gmail), sehingga ip_address yang tercatat adalah IP proxy dan perangkatnya masuk kategori EMAIL_PROXY — bukan perangkat penerima. Field notes pada response memuat peringatan yang sama agar konsumen API tidak salah tafsir.

Daftar log mentah atribusi klaim: satu baris per voucher yang diklaim, berisi link (link_id), slug, kode gedung, parameter UTM, IP, dan user agent.

Filter query: event_id, utm_id (alias link_id), building_code, slug, source, medium, campaign, search/q (cocok ke source, medium, campaign, kode gedung, slug, IP), page, limit.

Log tap NFC mentah — termasuk tap yang tidak berujung klaim — ada di GET /api/v1/utm/taps.

Riwayat buka email voucher, satu baris per pemuatan tracking pixel. Menjawab per penerima: sudah dibuka atau belum, kapan (sampai detik), dari perangkat / klien email apa, dan dari IP mana.

Tiap baris berisi voucher_id, event_id, client_email, created_at, device_type, email_client, ip_address, user_agent, dan is_first_open.

Filter query: event_id, voucher_id, email, device_type, email_client, ip_address, first_open_only, start_date, end_date, page, limit (maks 200).

Pakai first_open_only=true bila ingin menghitung orang, bukan berapa kali gambar dimuat ulang. Untuk mengecek satu penerima, saring dengan email atau voucher_id.

Daftar semua user terdaftar dengan **filter query**: `role_id`, `search`/`q`, `is_active`, `page`, & `limit`.

Menampilkan detail 1 user spesifik berdasarkan ID beserta role & permissions.

Admin membuat user baru (Admin/Manager/Staff) dengan menentukan `role_id` dan `is_active`.

Menghapus user dari sistem (Soft Delete).

Menampilkan daftar role sistem dengan **filter query**: `search`/`q`, `code`, `page`, & `limit` beserta array `permissions` relasional.

Menampilkan detail spesifik 1 Role berdasarkan ID beserta relasi permissions.

Membuat Role baru dan mendaftarkan array `permission_ids` yang berhak diakses.

Mengubah nama, deskripsi, atau menyinkronkan ulang array `permission_ids` milik suatu Role.

Mengganti `role_id` user tertentu secara langsung.

Menghapus Role dari sistem (Soft Delete).

Menampilkan master permissions dengan **filter query**: `module`, `search`/`q`, `code`, `page`, & `limit`.

Katalog preset provider (Gmail, Outlook 365, Yahoo, Zoho, Brevo, SendGrid, Mailgun, SES, Postmark, Mailjet, Resend, SMTP2GO, Elastic Email, Mailtrap, MailHog, relay Postfix, custom) beserta opsi `encryption`, `auth_type`, dan daftar strategi rotasi.

Ringkasan pool: jumlah provider aktif/eligible/sandbox/failing, total kuota harian & sisa, total pengiriman lifetime, distribusi `health`, dan strategi rotasi aktif.

Daftar provider SMTP dengan **filter query**: `search`/`q`, `provider`, `provider_key`, `is_active`, `health`, `sort`, `order`, `page`, & `limit`. Response memuat kuota harian/bulanan, sisa kuota, status `health`, dan `failure_count`.

Menampilkan detail spesifik 1 Provider SMTP berdasarkan ID Path Param.

Menambahkan provider SMTP baru (vendor apa pun) ke pool rotasi. Wajib: `provider`, `host`, `from_email`. Kirim `provider_key` untuk auto-isi host/port/encryption dari preset, atau isi semuanya manual.

Mengedit konfigurasi SMTP. Semua field opsional — yang tidak dikirim tetap seperti semula (`PATCH` pada endpoint yang sama berperilaku identik). Password kosong = password lama dipertahankan.

Uji rotasi email ke alamat tujuan. Rotator memilih provider sesuai strategi aktif, dan bila gagal **otomatis failover ke provider berikutnya**. Counter `daily_usage` hanya bertambah pada provider yang benar-benar berhasil mengirim.

Dial + STARTTLS/SSL + autentikasi ke provider, lalu QUIT. Sukses otomatis mereset `failure_count`, gagal menaikkannya dan mengembalikan pesan error asli dari server SMTP (HTTP 502).

Mengirim email uji lewat **1 provider tertentu tanpa rotasi** — untuk memverifikasi konfigurasi baru sebelum diaktifkan. `subject` & `message` opsional (message boleh HTML).

Membalik `is_active` tanpa mengirim ulang seluruh payload — untuk menonaktifkan provider bermasalah dengan cepat.

Mengatur ulang urutan rotasi beberapa provider sekaligus. Nilai `priority` lebih kecil = lebih diprioritaskan (dipakai strategi `priority`).

Menghapus provider SMTP dari pool rotasi sistem.

Menampilkan jumlah akumulasi log error gagal kirim SMTP dari **seluruh akun SMTP**: `pending_failed_count` (belum terkirim), `sent_count` (sukses resend), `failed_count` (gagal permanen), dan `total_failed_records`.

Daftar log gagal kirim SMTP terpaginasi dengan **filter query**: `search` (email/voucher/error), `status` (`PENDING`, `SENT`, `FAILED`), `page`, dan `limit`.

Mencoba kirim ulang 1 log error gagal berdasarkan ID Path Param via rotator pool SMTP. Mencegah pengiriman ganda jika status sudah `SENT`.

Daftar seluruh setting aplikasi global dari database PostgreSQL. Opsi query filter: `group` (`general`, `voucher`, `smtp`) dan `search` (kata kunci key/value).

Menyimpan/mengatur nilai setting global (termasuk `app_url = https://voucher.mrdiy.co.id`). Jika key belum ada maka otomatis dibuat baru.

Memperbarui nilai `value` spesifik dari 1 setting key (contoh `app_url`).