SMS Doğrulama API'si: Eksiksiz Geliştirici Rehberi

SMS Doğrulama API'si Tam Olarak Ne Yapar?

SMS doğrulama API'si, uygulamanızın bir telefon numarası istemesini, o numaraya gönderilen tek kullanımlık kodu almasını ve fiziksel SIM kart sahibi olmadan kullanıcı kimliğini doğrulamasını sağlar. Bir uç noktayı çağırırsınız, size sanal bir numara atanır, hedef servis (WhatsApp, Google, Telegram vb.) kodunu gönderir ve uygulamanız bu kodu API üzerinden geri okur.

Bu, SMS gönderme API'sinden farklıdır. Gönderme API'si mesajları dışarı iter. Doğrulama API'si gelen kodları içeri çeker. Otomasyon, test altyapısı, çoklu hesap araçları veya kayıt akışları geliştiren geliştiriciler genelde ikinci türe ihtiyaç duyar.

Bu rehber boyunca, referans uygulama olarak bu blogun arkasındaki platform SMSBulk'u kullanıyoruz. REST tasarımı çoğu modern sağlayıcının sunduğuna benzer olduğu için kavramlar değerlendirdiğiniz her sağlayıcıya taşınabilir.

Temel İstek Yaşam Döngüsü

Her doğrulama API'si aynı dört adımlı yaşam döngüsünü izler. Kod yazmadan önce bunu anlamak saatlerce hata ayıklamadan kurtarır.

1. Numara iste. Belirli bir ülke ve belirli bir servis için numara istersiniz. API bir numara ve aktivasyon ID'si döner.
2. SMS'i tetikle. Otomasyonunuz (veya son kullanıcı) bu numarayı hedef servise girer. Servis doğrulama kodunu gönderir.
3. Kodu sorgula (poll). O aktivasyon ID'si için mesaj gelip gelmediğini tekrar tekrar sorarsınız.
4. Aktivasyonu sonlandır. Tamamlandı olarak işaretler, iptal eder veya yeniden gönderim istersiniz.

Aktivasyon ID'si dört adımı birbirine bağlayan iptir. Aldığınız anda saklayın.

Neden webhook değil de polling?

Birçok doğrulama sağlayıcısı polling'e dayanır çünkü gelen SMS zamanlaması tahmin edilemez. Bir kod üç saniyede de gelebilir doksan saniyede de. Bazı sağlayıcılar webhook'u ek özellik olarak sunar ama mantıklı backoff'lu iyi kurulmuş bir poller her yerde çalışır. Backoff stratejisini aşağıda ele alıyoruz.

Kimlik Doğrulama ve Kurulum

Neredeyse her sağlayıcı, sorgu parametresi veya bearer token olarak iletilen tek bir API anahtarı kullanır. O anahtarı sunucu tarafında tutun. Mobil bir derlemeye veya ön yüz paketine asla koymayın, çünkü onu çıkaran herkes cüzdanınızı boşaltabilir.

Tipik bir kurulum kontrol listesi:

• Hesap oluşturun ve ortak bir cüzdan bakiyesi yükleyin.
• Panelden bir API anahtarı üretin.
• Anahtarı kaynak kontrolünde değil, ortam değişkeninde saklayın.
• Sağlayıcı destekliyorsa sunucu IP'lerinizi beyaz listeye alın.

SMSBulk'ta aynı cüzdan SMS doğrulamayı, e-posta doğrulama API'sini ve seyahat eSIM'lerini fonlar, yani üç yerine tek bakiye yönetirsiniz. Tek satır kod yazmadan önce tüm uç nokta referansını geliştirici API dokümantasyonunda inceleyebilirsiniz.

Python ile Minimal Entegrasyon

Aşağıda numara isteyen, kodu sorgulayan ve sonlandıran kısa bir örnek var. Bunu üretim kodu değil, iskelet olarak görün.

import time
import requests

API = "https://api.smsbulk.net"
KEY = "api_anahtariniz"

def numara_al(servis, ulke):
    r = requests.get(f"{API}/number", params={
        "key": KEY, "service": servis, "country": ulke
    })
    data = r.json()
    return data["activation_id"], data["number"]

def kod_sorgula(activation_id, timeout=120):
    bitis = time.time() + timeout
    bekleme = 3
    while time.time() < bitis:
        r = requests.get(f"{API}/status", params={
            "key": KEY, "id": activation_id
        })
        durum = r.json()
        if durum.get("code"):
            return durum["code"]
        time.sleep(bekleme)
        bekleme = min(bekleme + 2, 15)  # yumuşak backoff
    raise TimeoutError("Zamaninda kod gelmedi")

aid, numara = numara_al("whatsapp", "us")
print("Bu numarayi girin:", numara)
kod = kod_sorgula(aid)
print("Gelen kod:", kod)

Backoff'a dikkat edin: üç saniyede başlar ve on beş saniye tavana kadar büyür. Bu, hızlı teslimatları yakalarken oran limitlerine saygı gösterir.

Profesyonel Gibi Hata Yönetimi

Bir demo ile üretim entegrasyonu arasındaki fark hata yönetimidir. Gerçek trafik eninde sonunda her uç durumu vurur.

Numara mevcut değil

Bir ülke veya servis havuzu boşsa API numara yok hatası döner. Sıkı bir döngüde anında yeniden denemeyin. Bekleyin, sonra yedek listenizden alternatif bir ülke deneyin. Birçok servis birden fazla bölgeden numara kabul eder.

Kod hiç gelmiyor

Bazen hedef servis basitçe göndermez. Sorgu pencerenizi sınırlayın (iki dakika makul), numarayı serbest bırakmak için aktivasyonu iptal edin, sonra ya yeniden deneyin ya da kullanıcıya net bir mesaj gösterin. Hemen iptal etmek önemlidir çünkü genelde yalnızca başarılı aktivasyonlar için ücretlendirilirsiniz.

Oran sınırlama

HTTP 429 alırsanız retry-after başlığına saygı gösterin. Uç noktayı zorlamayın. Worker'larınızın önündeki bir kuyruk ani trafiği yumuşatır ve sizi limitler içinde tutar.

Sağlayıcı Failover Kurmak

Tek sağlayıcılı kurulumlar utandırıcı şekillerde çöker: bir bölge kurur ve tüm kayıt akışınız durur. Ciddi dağıtımlar sağlayıcıyı bir arayüzün arkasına soyutlar ve kesintileri atlar.

Pratik bir kalıp:

• get_number, poll_code ve cancel içeren bir VerificationProvider arayüzü tanımlayın.
• Birincil sağlayıcınız için uygulayın.
• Kayan bir pencerede ülke ve sağlayıcı başına başarı oranını izleyin.
• Başarı bir eşiğin altına düştüğünde yeni istekleri yedeğe kaydırın.

Bu kalıbın daha derin bir anlatımını, failover'lı SMS doğrulama API'si kurma rehberimizde yazdık. Circuit breaker'ları ve sağlık skorlamayı ayrıntılı ele alır.

Failover olsa bile, yedeğe nadiren düşmek için geniş kapsamlı bir birincil sağlayıcı seçin. Geniş ülke katalogları kullanıcılarınızın yaşadığı manuel yeniden deneme sayısını azaltır.

Numara Seçimi: Ülke ve Servis Eşleştirme

Her numara her servis için çalışmaz. Bazı platformlar belirli operatör aralıklarını veya belirli ülkeleri engeller. İki kural sizi beladan uzak tutar.

İlk olarak, her zaman doğrulamak istediğiniz belirli servise özel numara isteyin. Sağlayıcılar havuzlarını servise göre böler çünkü bir platformda çalışan numara başka bir platformda işaretlenmiş olabilir.

İkinci olarak, sıralı bir ülke yedek listesi tutun. Birincil ülkeniz kullanılamıyorsa veya kod başarısız olursa listeyi otomatik olarak aşağı inin. Tek kullanımlık numaraların nasıl davrandığına yeniyseniz, sanal telefon numarası rehberimiz bazı numaraların neden başarılı olurken diğerlerinin reddedildiğini açıklar.

Yedek mantığınızda hangi bölgelere öncelik vereceğinizi planlamak için tüm ülke kapsam listesindeki canlı erişilebilirliğe göz atabilirsiniz.

Maliyet Kontrolü ve Cüzdan Yönetimi

Doğrulama başarılı aktivasyon başına fiyatlandırılır ve fiyatlar servise ve ülkeye göre değişir. Birkaç alışkanlık harcamayı öngörülebilir tutar:

• Ölü aktivasyonları hızlı iptal edin. Kullanılmayan numarayı serbest bırakmak israfı ve çoğu platformda ücreti önler.
• İş başına bütçe belirleyin. Tek bir doğrulamanın kaç yeniden deneme tüketebileceğini sınırlayın.
• Bakiyenizi programatik izleyin. Bakiye uç noktasını sorgulayın ve sıfıra ulaşmadan önce uyarı verin, böylece toplu işler ortada durmaz.
• Yoğun olmayan saatlerde toplu işleyin iş yükünüz izin veriyorsa, çünkü erişilebilirlik genelde daha iyidir.

Şeffaf eylem başına fiyatlandırma tahmini kolaylaştırır. Ölçeklenmeden önce fiyatlandırma genel bakışındaki güncel oranları inceleyin ve başarılı doğrulama başına maliyetinizi modelleyin.

Güvenlik En İyi Uygulamaları

Doğrulama hattı kimliğe dokunur, bu yüzden dikkatle ele alın.

• Tam kodları asla düz metin uygulama günlüklerine yazmayın. Maskeleyin.
• API anahtarlarını bir programa göre ve sızıntı olursa hemen döndürün.
• Anahtarları mümkünse belirli IP'lere veya ortamlara kapsayın.
• Sunucuda doğrulayın. Dönen kodun kullanıcının gönderdiğiyle eşleştiğini sunucu tarafında onaylayın, istemciye asla güvenmeyin.
• Kendi uç noktalarınızı oran sınırlayın ki bir saldırgan doğrulama akışınızı bakiyenizi yakmak için kötüye kullanamasın.

Ürününüz tek kullanımlık kodlar için SMS ile e-posta teslimatı arasında karar vermek zorundaysa, SMS OTP ile e-posta OTP karşılaştırmamız maliyet, teslim edilebilirlik ve kullanıcı deneyimi açısından dengeleri açıklar.

Test ve Staging

Doğrulama akışlarını üretim anahtarlarıyla canlı üçüncü taraf servislere karşı test etmeyin. Bunun yerine:

• Küçük bakiyeli bir staging cüzdanı kullanın.
• Birim düzeyi mantık için sağlayıcı arayüzünü taklit eden entegrasyon testleri yazın.
• Yayından önce düşük maliyetli ülkelere karşı az sayıda gerçek uçtan uca kontrol çalıştırın.
• Her aktivasyon ID'sini sonucuyla birlikte günlükleyin ki hataları sonradan denetleyebilesiniz.

Buradaki iyi gözlemlenebilirlik işe yarar. Bir ülke havuzu bozulduğunda, panolarınız kullanıcılar şikayet etmeden çok önce artan bir hata oranı göstermeli.

E-posta Doğrulamayı da Ne Zaman Eklemeli

Birçok uygulama hem telefonu hem e-postayı doğrular. SMSBulk, SMS API'sini yansıtan bir e-posta doğrulama API'si sunduğu için aynı kimlik doğrulama kalıbını, cüzdanı ve istemci kod yapısını yeniden kullanabilirsiniz. Tek bir entegrasyon zihniyeti her iki kanalı kapsar, bu da bakımı azaltır.

Risk modelinize göre karar verin. Yüksek değerli hesaplar genelde her iki faktörden fayda sağlarken, düşük sürtünmeli kayıtlar yalnızca birine ihtiyaç duyabilir.

Sık Yapılan Entegrasyon Hataları

• Çok agresif sorgulama. Bu, oran limitlerini tetikler ve istekleri boşa harcar. Backoff kullanın.
• Aktivasyon ID yaşam döngüsünü yok saymak. İptal etmeyi unutmak numara ve para sızdırır.
• Tek ülkeyi sabit kodlamak. O kuruduğu an sıkışırsınız. Her zaman yedeğiniz olsun.
• İstemci tarafı doğrulamaya güvenmek. Her zaman sunucuda onaylayın.
• API anahtarını istemci tarafında yayınlamak. Cüzdanınızı boşaltmanın en hızlı yolu budur.

Bu beşinden kaçının, entegrasyonunuz çoğundan zaten daha sağlam olacaktır.

Sıkça Sorulan Sorular

Kodlar ne kadar hızlı gelir? Genelde birkaç saniye ile bir dakika arasında. Güvende olmak için yaklaşık iki dakikalık bir sorgu penceresi kurun, sonra zarifçe başarısız olun.

Bir numarayı birden fazla servis için kullanabilir miyim? Genelde hayır. İşaretlenmeyi ve reddi önlemek için servis başına yeni numara isteyin.

Hiç kod gelmezse ne olur? Numarayı serbest bırakmak için aktivasyonu iptal edin. Çoğu platformda yalnızca başarılı teslimatlar için ücretlendirilirsiniz.

Webhook'a ihtiyacım var mı? Mutlaka değil. Backoff'lu iyi tasarlanmış bir poller her yerde güvenilir çalışır ve dağıtımı daha basittir.

Aynı API hem SMS hem e-posta doğrulamayı çalıştırabilir mi? SMSBulk ile evet. E-posta API'si SMS tasarımını yansıtır, yani tek bir kod tabanı ikisini de yönetir.

SMSBulk ile Başlayın

Güvenilir bir doğrulama akışı yayınlamaya hazır mısınız? SMSBulk hesabı oluşturun, tek bir cüzdan yükleyin ve dakikalar içinde API anahtarınızı üretin. 200'den fazla ülkede SMS doğrulama numaralarına, aynı yapıyı yansıtan bir e-posta doğrulama API'sine ve aynı bakiyedeki seyahat eSIM'lerine erişirsiniz. Dokümanları okuyun, yukarıdaki polling iskeletini yerleştirin, mantıklı failover ekleyin ve sıfırdan kurmaktan çok daha hızlı üretim seviyesinde bir entegrasyonunuz olsun.