SMS Doğrulamayı Otomatikleştirin: Eksiksiz API Rehberi

Web sitesi ara sıra yapılan kayıtlar için gayet yeterli: birkaç tıklama, bir SMS için bekleme. İş otomatik testler yazmaya, toplu kayıt script'ine, bir CI pipeline'ına ya da doğrulama kodunu insan müdahalesi olmadan yakalaması gereken bir bota geldiğinde bu artık yetmiyor. Web sitesi bunu yapamaz. API yapabilir. Bu yazı, sıfırdan çalışan bir akışa geçmek için gereken her şeyi kapsıyor.

Adım 1: API Anahtarı Edinin

Giriş yapıp /account/api-keys sayfasına giderek bir anahtar oluşturun. Anahtarlar jm_ ön ekiyle başlayan rastgele bir dizeye benzer. Düz metin sadece bir kez gösterilir — biz anahtarın kendisini değil hash'ini saklarız, yani kaybederseniz "anahtarımı geri getir" diye bir seçenek yoktur. Silip yenisini oluşturmanız gerekir.

Her istek standart Bearer kimlik doğrulamasını kullanır:

Authorization: Bearer jm_your_key

Anahtarı bir şifre gibi düşünün — herkese açık bir repoya commit etmeyin, birine debug yaptırmak için sohbete yapıştırmayın. Sızdığından şüpheleniyorsanız /account/api-keys sayfasına dönüp onu silin ve yenisini oluşturun; eskisi anında çalışmayı keser.

Adım 2: Servis ve Ülke Seçin

Sipariş vermek için iki şey gerekir: service (servis kodu) ve country (ülke id'si). Önce kataloğu listeleyerek başlayın:

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

Her öğede bir code alanı bulunur (Telegram için tg) — bunu doğrudan sipariş endpoint'ine geçirin, kendiniz bir slug oluşturmaya çalışmaktan daha güvenilirdir. Belirli bir servisin tüm ülkelerdeki canlı fiyat ve stok bilgisini görmek için bir service parametresi ekleyin:

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

items içindeki her kayıtta countryId / priceCents / count (şu anki kullanılabilir numara sayısı) bulunur. Sipariş vermeden önce count değerine bakın — sıfırsa sipariş başarısız olur, bunu bir çağrı harcayarak öğrenmenize gerek yok.

Adım 3: Siparişi Verin

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"}'

Başarılı bir sipariş bir telefon numarası ve son kullanma zamanı döner:

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

Ücretlendirme bu adımda gerçekleşir — chargedCents gerçekten kesilen tutardır (cent olarak). Bu numarayı doğrulama kodunu almak için hedef uygulamaya verin, sonra sıradaki adıma geçin.

Adım 4: Kodu Almak İçin Polling Yapın

WebSocket veya webhook push yoktur — SMS içeriğini almanın yolu, smsBody artık null olmayana kadar GET /api/v1/orders/:id'yi polling yapmaktır:

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

Beş saniye makul bir başlangıç noktası — numara 15 dakika geçerli ve dakikada 60 sorgu limiti bolca alan bırakıyor. Sabırsızsanız üç saniye de işe yarar; saniyede bir polling yapmak kodu daha hızlı getirmez, sadece rate limit'inizi tüketir.

Tuzaklar

• Rate limit'ler kullanıcı bazında uygulanır, anahtar bazında değil. Yazma endpoint'leri (order / cancel / next-sms) kullanıcı başına dakikada 10 istekle sınırlıdır; sorgular dakikada 60. Ekstra anahtar oluşturmak size daha yüksek bir tavan sağlamaz — hepsi aynı limiti paylaşır.
• Numaralar 15 dakika sonra süresi dolar. Kod almadan süresi dolan kullanılmamış bir numara otomatik olarak iade edilir — talep etmenize gerek yok. Ama kendi pipeline'ınız numarayı gerçekten kullanmadan önce fazla oyalanırsa (örneğin bir kuyrukta sıkışıp kalırsa), siz sıraya geldiğinizde numara artık ölü olur.
• Bir numara birden fazla kod alabilir. Hedef uygulama SMS'i iki adımda gönderiyorsa (bir kayıt onayı, ardından ayrı bir giriş kodu), ilki geldikten sonra POST /api/v1/orders/:id/next-sms çağırarak bize "bu tamam, dinlemeye devam et" deyin — yeni bir numara için yeni sipariş vermenize gerek yok.
• Kod geldikten sonra cancel çalışmaz. POST /api/v1/orders/:id/cancel, numara henüz kod beklerken anında iade eder. smsBody bir kez bile null olmaktan çıktıysa, aynı çağrı bunun yerine bir CODE_RECEIVED hatası döner — ödediğiniz şeyi zaten aldınız, bu yüzden geri alınamaz.
• Durumu bir kez kontrol edip bırakmayın. status, WAITING'den RECEIVED'a geçer. Süresi dolana kadar WAITING'de kalıyorsa, bu genellikle o belirli ülke/servis kombinasyonundaki teslimat oranıyla ilgili bir sorundur — başka bir ülkede yeni bir sipariş vermek, beklemekten daha hızlı sonuç verir.

Buradan Sonrası

Bu, siparişten koda kadar olan ana akışı kapsıyor. Her endpoint için tam alan listesi, hata kodları ve uç durumlar /api-docs'ta bulunur. Bunu büyük ölçekte çalıştırıyorsanız — mesela düzinelerce hesabın doğrulama akışını aynı anda canlı tutuyorsanız — her siparişin polling döngüsünü bağımsız olarak zamanlayın. Tek bir seri döngü üzerinden kuyruğa almayın, yoksa siz hâlâ ilkini beklerken önceki numaraların süresi dolar.