Otomatisasi verifikasi SMS: panduan API lengkap

Website sudah cukup kalau cuma sesekali daftar akun: klik beberapa kali, tunggu satu SMS. Begitu kamu mulai menulis automated test, script pendaftaran massal, CI pipeline, atau bot yang harus mengambil kode verifikasi tanpa pengawasan manusia, website jadi tidak cukup lagi. Website tidak bisa melakukan itu. API bisa. Ini semua yang kamu butuhkan untuk membangun flow yang benar-benar jalan, dari nol.

Langkah 1: dapatkan API key

Masuk lalu buka /account/api-keys untuk membuat satu. Bentuk key-nya seperti jm_ diikuti string acak. Teks aslinya hanya ditampilkan sekali — yang tersimpan di database kami adalah hash-nya, bukan key itu sendiri, jadi tidak ada opsi "kembalikan key saya" kalau sampai hilang. Hapus saja key lamanya dan buat yang baru.

Setiap request menggunakan autentikasi Bearer standar:

Authorization: Bearer jm_your_key

Perlakukan key ini seperti password — jangan commit ke repo publik, jangan tempel di chat cuma supaya orang lain bisa bantu debug. Kalau kamu curiga key-nya bocor, balik lagi ke /account/api-keys, hapus, dan buat yang baru; key lama langsung berhenti berfungsi.

Langkah 2: pilih service dan negara

Membuat order butuh dua hal: service (kode service) dan country (id negara). Mulai dengan melihat daftar katalognya:

curl https://jiema.my/api/v1/services \
  -H "Authorization: Bearer jm_your_key"

Setiap item punya field code (Telegram itu tg) — pakai langsung nilai itu ke endpoint order, lebih aman daripada menyusun slug sendiri. Untuk melihat harga dan stok real-time suatu service di berbagai negara, tambahkan parameter service:

curl "https://jiema.my/api/v1/prices?service=tg" \
  -H "Authorization: Bearer jm_your_key"

Setiap entri di items punya countryId / priceCents / count (jumlah nomor yang tersedia saat ini). Cek count dulu sebelum order — kalau nol, order pasti gagal, jadi jangan buang satu request cuma untuk mengetahui itu dengan cara yang mahal.

Langkah 3: buat order

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":"6"}'

Order yang berhasil mengembalikan nomor telepon dan waktu kedaluwarsa:

{
  "ok": true,
  "data": {
    "id": "cm...",
    "status": "WAITING",
    "phone": "62812xxxxxxx",
    "expiresAt": "2026-08-01T12:15:00.000Z",
    "chargedCents": "40"
  }
}

Saldo langsung terpotong di langkah ini — chargedCents adalah nominal yang benar-benar terpotong (dalam sen). Serahkan nomor ini ke app tujuan untuk menerima kode verifikasi, lalu lanjut ke langkah berikutnya.

Langkah 4: polling untuk kode

Tidak ada WebSocket atau webhook push — cara mendapatkan isi SMS-nya adalah dengan polling GET /api/v1/orders/:id sampai smsBody tidak lagi null:

while true; do
  RESP=$(curl -s https://jiema.my/api/v1/orders/$ORDER_ID \
    -H "Authorization: Bearer jm_your_key")
  BODY=$(echo "$RESP" | jq -r '.data.smsBody')
  if [ "$BODY" != "null" ]; then
    echo "Code received: $BODY"
    break
  fi
  sleep 5
done

Lima detik adalah titik awal yang wajar — nomornya berlaku 15 menit, dan limit 60 request/menit untuk query masih menyisakan banyak ruang. Tiga detik juga masih aman kalau kamu tidak sabaran; polling tiap detik tidak akan membuat kode datang lebih cepat, cuma menghabiskan kuota rate limit-mu.

Jebakan umum

• Rate limit dihitung per user, bukan per key. Endpoint tulis (order / cancel / next-sms) dibatasi 10 per menit per user; endpoint baca 60 per menit. Membuat key tambahan tidak menaikkan limit-mu — semua key berbagi kuota yang sama.
• Nomor kedaluwarsa setelah 15 menit. Nomor yang tidak dipakai dan kedaluwarsa tanpa menerima kode akan di-refund otomatis — tidak perlu minta. Tapi kalau pipeline-mu sendiri menahan nomor itu terlalu lama sebelum benar-benar dipakai (misalnya nyangkut di queue), nomornya sudah mati begitu giliranmu tiba.
• Satu nomor bisa menerima lebih dari satu kode. Kalau app tujuan mengirim SMS dalam dua tahap (konfirmasi pendaftaran, lalu kode login terpisah), panggil POST /api/v1/orders/:id/next-sms setelah yang pertama datang untuk memberitahu kami "yang ini sudah selesai, lanjut dengarkan" — tidak perlu bikin order baru untuk nomor baru.
• Setelah kode diterima, cancel tidak berfungsi lagi. POST /api/v1/orders/:id/cancel langsung memberi refund selama nomornya masih menunggu kode. Begitu smsBody pernah terisi (bukan null), panggilan yang sama malah mengembalikan error CODE_RECEIVED — kamu sudah menerima apa yang dibayar, jadi tidak bisa dibatalkan lagi.
• Jangan cuma cek status sekali lalu menyerah. status berpindah dari WAITING ke RECEIVED. Kalau tetap di WAITING sampai kedaluwarsa, biasanya itu soal rate pengiriman SMS yang lagi rendah untuk kombinasi negara/service tersebut — bikin order baru di negara lain biasanya lebih cepat selesai daripada menunggu terus.

Langkah selanjutnya

Itu sudah mencakup flow utama dari order sampai kode. Daftar field lengkap, kode error, dan kasus-kasus khusus untuk setiap endpoint ada di /api-docs. Kalau kamu menjalankan ini dalam skala besar — misalnya menjaga proses verifikasi puluhan akun berjalan bersamaan — atur waktu polling tiap order secara independen. Jangan antre semuanya dalam satu loop serial, atau nomor-nomor yang lebih awal bakal kedaluwarsa selagi kamu masih menunggu yang pertama.