OTP & Notifikasi WA
Layanan One-Time Password (OTP) dan notifikasi transaksi DagangBot dirancang sebagai jembatan komunikasi dua arah yang sangat andal antara merchant dan pelanggan. Sistem ini tidak hanya memfasilitasi pembuatan kode keamanan acak dan kedaluwarsa singkat untuk autentikasi, tetapi juga menyajikan infrastruktur pengiriman melalui kanal primer WhatsApp dengan cadangan SMS (fallback). Semua dikendalikan melalui sistem antrean yang dapat diandalkan dan dikawal oleh pembatas lalu lintas jaringan (rate limiter) yang ketat.
Modul ini menjawab masalah umum dalam pengiriman OTP: keterlambatan pesan, eksploitasi oleh bot (OTP pumping), dan biaya pengiriman yang melonjak akibat percobaan palsu. Dengan menyatukan logika pembuatan CSPRNG (Cryptographically Secure Pseudo-Random Number Generator), pengiriman adaptif, dan verifikasi hash-based (HMAC-SHA256) di tingkat server, modul OTP menjaga keseimbangan antara keamanan, pengalaman pengguna, dan margin operasional.
1. Ikhtisar & Nilai Bisnis
Infrastruktur OTP platform memberikan perlindungan menyeluruh melalui manajemen percobaan pengiriman (rate limiting) dan arsitektur pengiriman tangguh. Berikut adalah pilar utama nilai bisnis yang dihasilkan:
- Pengiriman Kanal Ganda (Multi-Channel Routing): Sistem memprioritaskan WhatsApp sebagai kanal utama yang bebas biaya tambahan di luar tagihan Meta, namun secara mulus beralih ke penyedia SMS pihak ketiga (seperti Zenziva) dalam milidetik apabila koneksi ke Meta mengalami gangguan. Hal ini memastikan OTP tetap terkirim saat kritis.
- Pencegahan Penyedotan Biaya (Anti-OTP Pumping): Lapisan pembatas rate limit berbasis Redis mengunci percobaan berdasarkan kombinasi nomor telepon, identitas penyewa (merchant), dan batasan harian global. Ini melindungi sistem dari bot yang mencoba menghabiskan anggaran SMS dengan meminta kode secara massal.
- Personalisasi Template Pesan: Menyediakan templat dinamis di mana penyewa dapat memasukkan variabel seperti nama jenama, kode OTP, dan batas waktu kedaluwarsa (misalnya:
{{brand_name}}). Ini menjaga profesionalisme serta kewaspadaan pengguna. - Verifikasi Kriptografis Tanpa Bocor: Semua kode OTP tidak pernah disimpan dalam format teks polos. Basis data
otp_requestshanya menyimpan hash dari kode yang dibentuk bersama salt spesifik (merchant, nomor telepon, dan secret kunci), mencegah penyalahgunaan internal.
Meskipun pengiriman OTP dialihkan ke SMS saat WhatsApp mengalami interupsi, biaya SMS akan memotong saldo kredit (token) penyewa secara proporsional. Selalu anjurkan pelanggan Anda memakai nomor WhatsApp yang aktif untuk meminimalisasi pengurangan saldo.
Penerapan standar ini membantu penyewa mempertahankan operasional bisnis tanpa kekhawatiran terhadap lonjakan tagihan komunikasi yang tidak wajar.
2. Alur Visual & Antarmuka
Layar antarmuka dasbor OTP memberi penyewa visibilitas penuh terhadap performa kanal komunikasi WhatsApp, sisa kuota, serta riwayat pengiriman kode verifikasi. Melalui konsol OTP (/app/otp), admin dapat langsung menguji coba pengiriman OTP ke nomor ponsel tertentu, memeriksa log pengiriman real-time, dan mengaudit status verifikasi:

Tampilan laporan metrik juga memisahkan persentase antara pesan terkirim, gagal dalam rute utama, dan terkirim pada rute cadangan, yang memudahkan penyewa mengevaluasi keandalan nomor pelanggan mereka.
3. Panduan Langkah-demi-Langkah
Untuk menerapkan sistem OTP yang dilindungi sepenuhnya pada proses pendaftaran aplikasi pihak ketiga (seperti headless merchant app), ikuti urutan berikut:
- 1
Langkah 1: Registrasi dan Konfigurasi Template
Buka modul konfigurasi di dasbor dan navigasi ke menu Komunikasi → Template OTP. Buat templat baru menggunakan bahasa yang ramah pelanggan namun formal. Pastikan variabel wajib, yaitu
{{otp_code}}, disertakan dalam rancangan pesan Anda. Pilih apakah SMS akan diizinkan sebagai kanal cadangan (fallback) apabila gagal ke WhatsApp. - 2
Langkah 2: Permintaan Kode (Send)
Ketika pelanggan memasukkan nomor ponsel di aplikasi klien Anda, klien memanggil endpoint
POST /api/v1/otp/send. Pastikan untuk meneruskan nomor telepon tanpa kode negara+(disarankan memakai kanonik62...). Sistem kemudian menghasilkan kode acak dengan durasi kedaluwarsa bawaan. - 3
Langkah 3: Penanganan Respons Rate Limit
Pada klien aplikasi Anda, antisipasi status
429 Too Many Requests. Sistem mengenakan masa tunggu (cooldown) antara permintaan dari nomor yang sama. Berikan indikator visual (timer mundur) selama 60 detik kepada pelanggan, agar mereka tidak secara panik menekan tombol kirim ulang. - 4
Langkah 4: Pengumpulan dan Verifikasi (Verify)
Sediakan kolom 6 angka bagi pelanggan untuk memasukkan OTP. Kirim nilai yang dimasukkan ke
POST /api/v1/otp/verify. Sistem akan membandingkan masukan dengan rekam jejak (hash) di basis data. - 5
Langkah 5: Penanganan Penguncian Sementara
Apabila pelanggan salah memasukkan kode melebihi batas (secara default, 3 kali berturut-turut), respons API akan berisi alasan
locked. Aplikasi harus memblokir percobaan selama 10 menit. Tampilkan pesan peringatan demi keamanan akun dan minta pelanggan mencoba beberapa saat lagi.
4. Parameter & Spesifikasi Teknis
Sistem menggunakan kontrol granular pada pengiriman, memvalidasi rentang waktu secara ketat melalui implementasi Redis Rate Limiter dan memonitor status pengiriman di tabel otp_requests.
Siklus hidup status dalam otp_requests (kolom status):
pending: Menunggu diverifikasi.verified: Berhasil diverifikasi. Hanya dapat dikonsumsi satu kali.expired: Melewati batas waktu.locked: Disalahgunakan (terlalu banyakattempts).
5. Relasi & Integrasi
Detail Mekanisme Rate Limiting (Pemblokiran Bertingkat)
Guna memberikan pelindungan maksimal terhadap upaya serangan pengurasan kuota, implementasi rate limiter dibagi ke dalam tiga lapis pelindung yang dievaluasi secara berurutan. Setiap kali ada permintaan POST /api/v1/otp/send, peladen memvalidasi metrik pada peladen in-memory (Redis) dengan urutan:
- Lapisan Cooldown (Jeda Waktu Sesaat)
Ketika OTP diterbitkan, Redis langsung menulis key
ratelimit:otp:cooldown:<merchant_id>:<phone>dengan parameter TTL (Time-to-Live) absolut 60 detik. Sebelum TTL ini habis, semua permintaan dari entitas ponsel tersebut akan secara instan ditolak di level pangkalan memori sehingga tidak membebani komputasi peladen aplikasi. - Lapisan Batas Per Tenant-Ponsel (Hourly Limit)
Setelah lolos pengecekan cooldown, sistem memeriksa akumulasi hitungan pada key
ratelimit:otp:<merchant>:<phone>. Ambang batas diatur 5 kali per jam. Jika seorang pengguna asli sekalipun secara impulsif mencoba meminta pesan ulang, langkah ini mencegah penggunaan saluran melebihi 5 kali. - Lapisan Anti-Pumping Universal (Global Hit)
Sistem merekam setiap ponsel yang meminta OTP tanpa memedulikan merchant yang dihubungi lewat key
ratelimit:otp:global:<phone>. Batas ketat ini disetel maksimal 15 permintaan per 24 jam. Hal ini merupakan pertahanan utama melawan gerombolan bot yang melakukan percobaan lintas tenant pada platform yang sama.
Kebijakan Fallback Pengiriman Cadangan (SMS)
Pada dasbor Komunikasi → Pengaturan Pengiriman, terdapat fitur Graceful Degradation yang memastikan tingkat keberhasilan verifikasi tetap konsisten meskipun layanan pesan instan Meta (WhatsApp) mengalami gangguan.
- Deteksi Gangguan (Timeout & Bounce): Ketika API pengiriman Meta Cloud memberikan respons galat (HTTP 5xx) atau koneksi timeout (melebihi 5.000 milidetik), peladen secara otomatis menghentikan blokir aliran thread dan beralih ke saluran sekunder.
- Rute Pengganti (SMS Provider Route): Sistem membangkitkan integrasi Zenziva atau penyedia SMS tepercaya lainnya untuk menyuntikkan payload pesan. Karena karakter pada SMS lebih terbatas, template yang dipakai akan direduksi untuk sekadar menampilkan nama jenama, kode 6 digit, dan peringatan durasi (contoh: DagangBot: Kode OTP Anda 849201. Jangan beri tahu siapa pun. Berlaku 5 menit.).
- Proporsi Saldo (Credit Deductions): Meskipun proses fallback ini sepenuhnya nirkabel di level pengguna akhir, ia membawa dampak penagihan. Pengiriman rute WhatsApp dinilai jauh lebih ekonomis ketimbang SMS. Setiap keberhasilan fallback akan langsung mencatatkan transaksi pengeluaran (ledger deduction) sebesar nilai harga satuan pengiriman pesan singkat, yang langsung dipotong dari keseimbangan kredit akun merchant bersangkutan. Bila kredit menyentuh ambang nol, pengiriman SMS tidak dieksekusi.
Infrastruktur pengiriman pesan ini tidak hanya melayani verifikasi pendaftaran akun, melainkan juga dimanfaatkan secara lateral oleh layanan-layanan lain di dalam ekosistem platform.
- Modul Autentikasi (
/auth/register,/auth/verify-otp): Pada rute autentikasi publik, pendaftaran pengguna langsung memicu fungsi Send. Kegagalan verifikasi ditolak di lapisan handler dan tidak diizinkan mengeluarkan Token JWT. - Sistem Billing (Pembayaran Kredit): Biaya yang ditimbulkan saat mengirim OTP—terutama ketika melewati layanan SMS fallback dari Zenziva—akan mengurangi saldo kredit pada modul Billing. Logika ini melintas batas paket, merekam jumlah pesan (1 credit WA vs N credit SMS).
- Modul Komunikasi (Notifikasi): Engine templat yang memproses penggantian sintaks
{{key}}digunakan secara bersama (re-usable) oleh Notification Service untuk mengabarkan perubahan status keranjang belanja dan pembatalan draf invoice.
Kode yang merespons verifikasi akan menghitung kecocokan menggunakan HMAC-SHA256 di mana secret merupakan kombinasi antara serverSecret, identitas tenant, dan nomor pelanggan (subject). Karena hash tidak pernah bergerak melalui antarmuka publik, manipulasi permintaan (seperti mengubah payload HTTP) tidak akan menembus lapisan pelindung kriptografik ini.
6. Pemecahan Masalah (Troubleshooting)
Kendala pada sistem pengiriman pesan biasanya bersifat situasional—mulai dari ketersediaan sinyal telepon hingga batas harian. Analisis di bawah menguraikan akar masalah yang kerap terjadi beserta jalan keluarnya.
7. Referensi Terkait
Pelajari instrumen dan pengaturan terhubung lainnya yang merajut keamanan di dalam aplikasi dagang Anda.
Autentikasi & Otorisasi
Bagaimana sesi JWT dikonstruksi setelah persetujuan OTP selesai dilakukan.
Manajemen Kuota Tagihan
Aturan pemotongan token saldo yang disebabkan oleh konsumsi layanan SMS darurat.
Konfigurasi Kredensial API
Cara memakai X-API-Key untuk mengakses endpoint pengiriman notifikasi transaksional.
Webhooks (Penerima Laporan)
Mendengar sinyal kejadian dari platform ketika status notifikasi berubah.
