Automasikan pengesahan SMS: panduan API lengkap

Laman web sudah memadai untuk pendaftaran sekali-sekala: klik beberapa kali, tunggu satu SMS. Ia tidak lagi memadai apabila anda menulis automated test, skrip pendaftaran pukal, CI pipeline, atau bot yang perlu mengambil kod pengesahan tanpa pengawasan. Laman web tidak boleh buat itu. API boleh. Ini semua yang anda perlukan untuk membina aliran kerja yang benar-benar berfungsi, dari kosong.

Langkah 1: dapatkan API key

Log masuk dan pergi ke /account/api-keys untuk mencipta satu. Key kelihatan seperti jm_ diikuti rentetan rawak. Teks penuhnya hanya dipaparkan sekali — kami simpan hash-nya, bukan key itu sendiri, jadi tiada pilihan "kembalikan key saya" jika anda hilangkan. Padam saja dan cipta yang baharu.

Setiap permintaan menggunakan pengesahan Bearer standard:

Authorization: Bearer jm_your_key

Layan key ini seperti kata laluan — jangan commit ke repo awam, jangan tampal dalam chat semata-mata untuk orang lain bantu debug. Jika anda syak ia terdedah, kembali ke /account/api-keys, padam, dan cipta yang baharu; key lama terus berhenti berfungsi.

Langkah 2: pilih service dan negara

Membuat order memerlukan dua perkara: service (kod service) dan country (id negara). Mulakan dengan menyenaraikan katalog:

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

Setiap item mempunyai field code (Telegram ialah tg) — hantar terus nilai itu ke endpoint order, lebih boleh dipercayai daripada membina semula slug sendiri. Untuk melihat harga dan stok masa nyata bagi sesuatu service merentas negara, tambah parameter service:

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

Setiap entri dalam items mempunyai countryId / priceCents / count (jumlah nombor tersedia sekarang). Semak count sebelum membuat order — sifar bermakna order akan gagal, jadi jangan bazirkan satu permintaan untuk mengetahuinya dengan cara yang sukar.

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 berjaya mengembalikan nombor telefon dan masa tamat tempoh:

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

Caj berlaku pada langkah ini — chargedCents adalah jumlah sebenar yang ditolak (dalam sen). Berikan nombor ini kepada aplikasi sasaran untuk menerima kod pengesahan, kemudian teruskan ke langkah seterusnya.

Langkah 4: polling untuk kod

Tiada WebSocket atau webhook push — anda dapatkan kandungan SMS dengan polling GET /api/v1/orders/:id sehingga 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 saat adalah titik permulaan yang munasabah — nombor sah selama 15 minit, dan had 60 permintaan/minit untuk query masih memberi banyak ruang. Tiga saat pun masih boleh jika anda tidak sabar; polling setiap saat tidak menjadikan kod tiba lebih pantas, ia cuma membazirkan had kadar anda.

Yang perlu diwaspadai

• Had kadar dikira per pengguna, bukan per key. Endpoint tulis (order / cancel / next-sms) dihadkan pada 10 seminit setiap pengguna; endpoint baca 60 seminit. Mencipta key tambahan tidak menaikkan had anda — semua key berkongsi kuota yang sama.
• Nombor tamat tempoh selepas 15 minit. Nombor yang tidak digunakan dan tamat tempoh tanpa menerima kod akan dibayar balik secara automatik — tidak perlu minta. Tetapi jika pipeline anda sendiri menahan nombor itu terlalu lama sebelum benar-benar menggunakannya (contohnya tersekat dalam queue), ia sudah mati apabila tiba giliran anda.
• Satu nombor boleh menerima lebih daripada satu kod. Jika aplikasi sasaran menghantar SMS dalam dua peringkat (pengesahan pendaftaran, kemudian kod log masuk berasingan), panggil POST /api/v1/orders/:id/next-sms selepas yang pertama tiba untuk memberitahu kami "yang ini sudah selesai, teruskan mendengar" — tidak perlu membuat order baharu untuk nombor baharu.
• Selepas kod tiba, cancel tidak lagi berfungsi. POST /api/v1/orders/:id/cancel memberikan bayaran balik serta-merta selagi nombor masih menunggu kod. Sebaik smsBody pernah tidak null, panggilan yang sama sebaliknya mengembalikan ralat CODE_RECEIVED — anda sudah mendapat apa yang dibayar, jadi tidak boleh diundur lagi.
• Jangan hanya semak status sekali lalu berhenti. status berpindah daripada WAITING ke RECEIVED. Jika ia kekal pada WAITING sehingga tamat tempoh, ini biasanya isu kadar penghantaran SMS yang rendah untuk kombinasi negara/service tersebut — membuat order baharu di negara lain biasanya lebih cepat selesai daripada terus menunggu.

Langkah seterusnya

Itu sudah merangkumi aliran utama dari order hingga kod. Senarai field lengkap, kod ralat, dan kes tepi untuk setiap endpoint ada di /api-docs. Jika anda menjalankan ini dalam skala besar — contohnya mengekalkan aliran pengesahan berpuluh-puluh akaun serentak — jadualkan gelung polling setiap order secara berasingan. Jangan baris gilirkan semuanya dalam satu gelung bersiri, atau nombor-nombor lebih awal akan tamat tempoh sementara anda masih menunggu yang pertama.