Technical FAQ untuk developer

Pricing & billing

Apakah API NomorOTP.id gratis?

Register API key gratis. Bayar hanya per SMS OTP yang berhasil masuk — mulai Rp 150 untuk Telegram, Rp 250 WhatsApp, Rp 500 Gojek. Kalau kode gagal masuk, refund otomatis 100% saldo. Tidak ada langganan atau minimum monthly. Lihat pricing lengkap.

Berapa minimum top-up saldo?

Rp 10.000 via QRIS (DANA, GoPay, OVO, ShopeePay, m-banking BCA/Mandiri/BRI/BNI). Saldo masuk otomatis dalam ~15 detik setelah payment sukses.

Apakah ada bulk discount untuk volume tinggi?

Ya. Kalau volume >500 verifikasi/bulan, chat @nomorotpid untuk custom pricing. Reseller enterprise dapat diskon 10-25% + priority support.

Rate limits & performance

Berapa rate limit API per endpoint?

• getNumber: 60 request/menit per API key
• getStatus: 300 request/menit (aman untuk poll setiap 3 detik per activation)
• getBalance: 120 request/menit
• getPrices: 60 request/menit

Bagaimana handle rate limit exceeded?

Response: {"status":"ERROR_SQL","message":"Rate limit exceeded"}. Implement backoff exponential — 3 detik, 9 detik, 27 detik. Kalau tetap fail setelah 3 retry, log dan skip request.

Berapa lama biasanya kode SMS masuk?

Rata-rata per aplikasi:

• Telegram: 5-10 detik (paling cepat)
• WhatsApp: 8-15 detik
• Shopee: 10-20 detik
• Gojek: 15-25 detik
• TikTok: 20-30 detik
• Instagram/Facebook: 15-25 detik

Kalau lewat 20 menit tanpa kode, activation auto-expire + refund otomatis.

Poll interval optimal untuk getStatus?

3 detik. Lebih pendek waste rate limit tanpa benefit (SMS gateway upstream tidak faster than 5-10 detik). Lebih panjang delay UX terasa lambat ke user.

Error handling

Apa artinya STATUS_WAIT_CODE?

Nomor sudah aktif, sistem lagi tunggu SMS masuk dari aplikasi tujuan. Poll ulang setiap 3 detik sampai STATUS_OK (kode masuk) atau STATUS_CANCEL (timeout 20 menit).

Kapan pakai setStatus vs biarkan expire?

• setStatus dengan status=8 (cancel): kalau user cancel di UI atau proses batal — refund immediate.
• Biarkan expire (20 menit): kalau user tidak respond atau bot tidak bisa deteksi failure — refund otomatis di menit ke-20.
• setStatus dengan status=6 (complete): setelah kode berhasil dipakai — mark activation final, cegah retry.

Bagaimana handle NO_NUMBERS response?

Supply nomor habis untuk kombinasi service+country tersebut. Options:

1. Retry setelah 30-60 detik (supply biasanya replenish cepat)
2. Fallback ke country lain (misal +62 habis → coba +1 USA)
3. Kalau user-facing, tampilkan "sedang penuh, coba beberapa menit lagi"

Apa yang harus dilakukan kalau dapat BAD_KEY?

API key invalid atau di-rotate. Login dashboard → API Access → regenerate → update environment variable di production.

Integrasi

Bagaimana cara integrate API ke website reseller?

Pakai PHP, Node.js, atau Python SDK di halaman examples. Setup API key sebagai env var, panggil getNumber saat user request, poll getStatus untuk terima kode.

Apa protokol yang dipakai API?

REST-style API sederhana. Endpoint https://api.nomorotp.id/?action=X dengan query string params. Auth via HTTP header X-API-Key. Response JSON dengan format {"success": true/false, ...}. Tidak butuh library khusus — cukup HTTP client bawaan bahasa (cURL, fetch, requests, dll).

Bisa integrate ke bot Telegram?

Bisa. Baca panduan setup bot Telegram untuk step-by-step. SDK Node.js/Python di halaman examples bisa langsung di-plug ke bot handler.

Ada webhook untuk push notification saat SMS masuk?

Sementara belum. Sekarang pakai poll getStatus. Webhook feature planned Q4 2026 — subscribe @nomorotpid_bot untuk update announcement.

Security

Bagaimana cara amankan API key di production?

1. Environment variable — jangan hardcode di source code
2. Server-side only — jangan expose ke frontend/mobile app. Proxy request via backend
3. Rotate berkala — regenerate key tiap 3-6 bulan
4. IP whitelist — set di dashboard kalau API cuma di-call dari server tertentu
5. Monitor usage — cek dashboard API Access → Usage untuk anomali

Apakah data OTP disimpan permanen?

Tidak. Kode SMS otomatis di-purge dari database setelah activation ditutup (max 24 jam). Riwayat pesan tidak retained. Kami cuma simpan metadata (timestamp, cost, activation_id) untuk billing audit.

Apakah nomor yang dipakai user lain bisa lihat SMS saya?

Tidak. Setiap activation dikunci per session untuk API key kamu. Selama activation aktif (max 20 menit), tidak ada user lain yang bisa akses SMS di nomor tersebut. Setelah activation ditutup, nomor kembali ke pool tapi riwayat SMS sudah di-purge.

Troubleshooting umum

Kode masuk tapi aplikasi tolak "invalid code"

Cek:

1. Kode di-copy komplit (5-8 digit tergantung app)
2. Input dalam waktu ≤5 menit setelah SMS masuk (beberapa app expire fast)
3. Format nomor sudah benar saat request (dengan country code, tanpa spasi/dash)
4. Aplikasi tujuan tidak lagi accept nomor virtual (rare — coba nomor country lain)

Aplikasi tolak nomor sebelum kirim SMS

Beberapa aplikasi (terutama TikTok, Instagram) punya blacklist prefix nomor virtual. Baca panduan lengkap TikTok tolak nomor virtual untuk solusi.

Cara test integration di dev environment

Sementara belum ada sandbox — semua request live + charge saldo. Rekomendasi: top up Rp 10.000 sebagai budget dev testing, cukup untuk ~40 test dengan Telegram (Rp 150 per verify). Mode dry-run planned Q1 2027.

Support

Kemana kalau butuh bantuan technical?

• Chat admin: Telegram @nomorotpid (respond <2 jam jam kerja WIB)
• Email: admin@nomorotp.id (respond <4 jam jam kerja)
• API status page: cek uptime + incidents di dashboard

Bagaimana report bug atau request feature?

Buka issue di github.com/nomorotp/docs untuk bug docs, atau chat @nomorotpid untuk bug API. Feature request via Telegram — kami tinjau tiap bulan.