SMS Activate App REST API ile kodunuz özel numara satın alır, doğrulama başlatır ve SMS kodunu okur. Kendi uygulamalarınız, hesaplarınız ve testleriniz için.
Bu rehber akışın tamamını anlatır: numara seçmek, numarayı güvenle satın almak, OTP (tek kullanımlık şifre) kodunu okumak ve işiniz bittiğinde numarayı bırakmak.
Ne zaman otomatikleştirmeli
Otomasyon, size ait olan ve tekrarladığınız işler için uygundur. Üç yaygın durum:
- Kendi uygulamanızdaki SMS adımlarının uçtan uca testleri: kayıt, giriş, şifre sıfırlama ve 2FA (iki faktörlü kimlik doğrulama).
- Kendi hizmet hesaplarınızda ve dahili araçlarınızda 2FA'nın çalışmaya devam etmesi.
- İşlettiğiniz bir ürünün içindeki doğrulama adımı.
Her numara özel bir sanal numaradır. Ülkeye bağlı olarak bir operatörün numara aralığından gelen gerçek bir mobil veya yerel numaradır. Numara 28 günlük süre boyunca hesabınızda kalır. Aynı numara sonraki kodları da alabilir. Böylece süre boyunca yeniden doğrulama ve hesap kurtarma çalışmaya devam eder.
İki sınır geçerlidir. Numara verildikten sonra işlem kesinleşir ve iade edilmez. Numarayı kabul edip etmeyeceğine biz değil, doğrulama yaptığınız platform karar verir.
Kodların çoğu, platform gönderdikten sonraki birkaç dakika içinde gelir. Henüz bir teslim oranı yayımlamıyoruz. Bu yüzden bir numarayı temel alan bir iş akışı kurmadan önce numarayı hedef platformunuzla deneyin.
API SMS alır. SMS göndermez.
Başlamadan önce
- Kayıt sayfasında ücretsiz bir hesap oluşturun.
- Hesaba bakiye yükleyin.
- Hesap panelindeki API anahtarları sekmesinde veya Telegram botunda kişisel bir API anahtarı oluşturun.
Katalog dahil her istekte anahtarı gönderin:
Anahtar bakiyenizi harcar. Anahtarı sunucu tarafında, bir gizli bilgi deposunda veya CI gizli değişkeninde tutun. Anahtarı asla istemci koduna koymayın ve bir depoya commit etmeyin.
Başvuru bilgileri:
- Temel URL: https://api.sms-activate.app/v1/public
- Tutarlar tam sayı olarak USD sent cinsindendir. balanceCents: 2000, 20,00 $ anlamına gelir.
- Makinenin okuyabileceği belirtim: OpenAPI dosyası (OpenAPI 3.1).
- İnsanların okuyabileceği belgeler: API belgeleri.
- LLM ajanları için hazır bir beceri: ajan becerisi.
- Sınırlar: hesap başına dakikada en az 120 istek ve dakikada 30 satın alma. Bunlar aşıldığında yanıt, Retry-After başlığıyla birlikte rate_limited olur.
Doğrulama akışı
- GET /countries çağrısını yapın. Bu uç nokta her ülke için stok durumunu ve fiyat aralığını döndürür.
- Kullanılabilir bir numara seçmek için GET /numbers/search?country=US&limit=1 çağrısını yapın. Her sonuçta phoneNumber ve priceCents alanında sizin fiyatınız bulunur.
- Numarayı POST /numbers ile ve {"phone": "<phoneNumber>", "country": "US"} gövdesiyle satın alın. Bir Idempotency-Key: <uuid> başlığı ekleyin. Böylece yeniden deneme sizden asla iki kez ücret almaz. Başarılı bir satın alma number, chargedCents ve balanceAfterCents ile birlikte 201 döndürür. İki isteğe bağlı alan vardır: autoRenew (varsayılan true) ve note.
- Numarayı test ettiğiniz akışa girin ve SMS'i tetikleyin.
- Kodu okuyun. Yaklaşık 5 ila 15 saniyede bir o numara için GET /numbers/{id}/sms veya tüm numaralar için GET /sms sorgulayın ve bir zaman aşımı belirleyin. Her SMS'te id, numberId, from, to, body ve receivedAt alanları bulunur; kodu body alanından çıkarın. Akışlar cursor, limit ve nextCursor ile imleç tabanlı sayfalanır.
- Bitirin. Yenilemeyi durdurmak için {"autoRenew": false} ile PATCH /numbers/{id} gönderin veya numarayı bırakmak için DELETE /numbers/{id} kullanın. Her gün çalıştırdığınız bir test paketi için tek bir numarayı yenilemede tutmak, her çalıştırmada yeni numara satın almaktan genellikle daha basittir.
curl ile örnek
İlk çağrı bir numara bulur. İkincisi onu satın alır. Üçüncüsü gelen SMS'leri okur.
+15551234567 yerine ilk çağrının döndürdüğü bir numarayı yazın. Bir ağ hatasından sonra satın almayı yeniden denerseniz yeni bir Idempotency-Key değeri üretmeyin, aynı değeri tekrar kullanın.
Python örneği
Bu fonksiyon, zaten sahip olduğunuz bir numarada kodun gelmesini bekler. requests kütüphanesini kullanır ve anahtarı ortam değişkeninden okur.
Aynı numaraya daha önce gelen SMS'ler de eşleşebiliyorsa receivedAt değerini testinizin mesajı tetiklediği zamanla karşılaştırın ve yalnızca daha yeni olanı alın.
Yoklama (polling) yerine webhook
{"forwardWebhookUrl": "https://your-app.example.com/sms"} gövdesiyle PATCH /numbers/{id} gönderin; o numaraya gelen her SMS ve her arama, geldiği anda sunucunuza gönderilir. Adres önce kontrol edilir: test amaçlı bir POST isteğine 2xx durum koduyla yanıt vermelidir.
Her istek x-vpn-event, x-vpn-timestamp ve x-vpn-signature başlıklarını taşır. İmza, webhook gizli anahtarınızla v1.<timestamp>.<raw body> üzerinden hesaplanan HMAC-SHA256 değeridir. İmzayı ham baytlar üzerinde doğrulayın ve beş dakikadan fazla sapan bir zaman damgasını reddedin.
Bir kez çalışan bir test için yoklama daha basittir. Webhook ise kodları geldikçe işleyen ve uzun süre çalışan bir servise uygundur.
Hataları yanıt olarak ele alın
Her hata aynı yapıdadır:
Akışı her zaman error koduna göre dallandırın, HTTP durum koduna göre dallandırmayın. Tek bir durum kodu birden fazla ret nedenini taşıyabilir. Bu yüzden durum kodu tek başına ne olduğunu söylemez. Bazı retler bir details nesnesi ekler. Örneğin insufficient_balance hatasında requiredCents ve availableCents gelir.
İşlemeniz gereken kodlar:
- insufficient_balance: bakiyeniz satın alımı karşılamıyor. İşlemi durdurun ve bakiye yükleyin.
- no_numbers: şu anda eşleşen bir numara yok. Başka bir numara veya ülke seçin.
- number_unavailable: numara satıldı veya artık satışta değil. Yeniden arama yapın.
- validation_failed: istek gövdesi veya parametreler hatalı ya da satın alma isteğinde Idempotency-Key yok. Girdiyi düzeltin.
- idempotent_replay: bu Idempotency-Key ile gelen istek farklı bir gövde taşıyor veya hâlâ işleniyor. Bunu yeni bir satın alım olarak değerlendirmeyin.
- rate_limited: çok fazla istek var. Retry-After başlığının belirttiği süre kadar bekleyin.
- priceexceeded ve providerfailure: message alanını okuyun, kullanıcıya gösterin ve çalıştırmayı durdurun. provider_failure sonrasında yeniden satın almadan önce numaralarınızı kontrol edin.
Bunların hiçbiri körü körüne yeniden denenecek bir arıza değildir. Hatayı kodu çalıştıran kişiye gösterin veya çalıştırmayı durdurun. reqId değerini loglarınızda saklayın. Destek ekibi isteğinizi bu değerle bulur.
CI test paketinde
- SMS testlerini ayrı ve sıralı bir iş (job) olarak çalıştırın. Böylece iki test hiçbir zaman aynı kodu okumaz.
- API anahtarını bir CI gizli değişkeni (secret) olarak saklayın.
- Her kodu numaraya ve testin başladığı zamana göre ilgili testle eşleştirin.
- Bir zaman aşımı belirleyin. Süre dolduğunda testi, numarayı ve adımı belirten açık bir mesajla başarısız sayın.
- Her çalıştırmada yeni numara satın almak yerine tekrarlanan çalıştırmalar için yenilenen tek bir numara kullanın.
Faydalı videolar
Bu rehberde kullanılan tekniklerle ilgili üçüncü taraf videolar. Genel teknikleri anlatırlar ve hizmetimizi kapsamazlar.
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (Corey Schafer): Python'dan başlıklarla GET ve POST istekleri gönderir ve JSON yanıtlarını okur.
- Server-Sent Events Crash Course (Hussein Nasser): Server-Sent Events akışının nasıl çalıştığını ve hangi durumda yoklamadan daha iyi olduğunu anlatır.
- Polling vs Webhooks | System Design Tradeoffs (SoftwareDude): belirli aralıklarla sormanın ve anlık bildirim (push) almanın maliyetini ve faydasını karşılaştırır.
- Idempotency in APIs Explained | Why It Matters + Code Example (Arkynate): idempotency anahtarlarını ve güvenli yeniden denemeleri kod örneğiyle anlatır.
- Playwright Tutorial: Re-use state & Re-use Authentication (CommitQuality): test paketinde bir kez oturum açıp oturum durumunu yeniden kullanmayı gösterir. Böylece SMS adımı yalnızca gerektiğinde çalışır.
Sonraki adımlar
- Tam referansı API belgelerinde okuyun.
- Spesifikasyonu OpenAPI dosyasından araçlarınıza yükleyin.
- Bir LLM ajanına hazır ajan becerisini verin.
- Güncel fiyatları fiyatlandırma sayfasında kontrol edin.
- API üzerine bir ürün kurmayı planlıyorsanız sanal telefon numaralarıyla nasıl kazanç elde edilir başlıklı genel bakışı okuyun.