SMS doğrulama API'si
SMS doğrulama API'si üç çağrıdan ibaret: numara al, kodu bekle, numarayı bırak. 225 ülkede 517 servise ulaşır, numaralar €0,07 seviyesinden başlar ve hiçbir şey almayan bir aktivasyon destek kaydı gerekmeden iade edilir. Anahtarlar kapsamlıdır, satın almalar idempotenttir ve eski handler_api istemcileri değişiklik yapılmadan çalışır.
Tek blokta API
28 Ağu 2026 tarihinde güncellendi- Temel URL
- https://virtualsmsnumbers.com/api/v1
- Kimlik doğrulama
- Bearer anahtar ya da X-Api-Key
- Hız sınırı
- 120/dk, ani 20/sn
- İdempotans penceresi
- 24 saat
- Otomatik iade süresi
- 20 dakika
- En ucuz aktivasyon
- €0,07
- Kapsanan ülke
- 225
- Biçim
- JSON, sent, ISO 8601 UTC
Fiyatlar ve stok, yayımlanmış bir fiyat listesinden değil, operatör havuzunun o anki durumundan geliyor.
Üç çağrılık akış
Dokümantasyondaki her şey isteğe bağlı. Doğrulama yolunun tamamı bu ve 2019'dan beri değişmedi.
- 1
POST /activations
Bir servis, hangisi olduğu önemliyse bir de ülke isteyin. Yanıt numarayı, sent cinsinden fiyatı ve bitiş zaman damgasını taşır. Tekrarlanan bir isteğin ikinci bir numara satın alamaması için Idempotency-Key gönderin; çağıran taraf otomatikse bir de max_price_cents.
- 2
GET /activations/{id}?wait=180
Uzun yoklama. Bağlantı, mesaj düşene ya da zaman aşımı dolana kadar açık tutulur; böylece tek istek, aksi hâlde doksan istek yapacak bir döngünün yerini alır. Durum, ham metnin yanında ayrıştırılmış kodla birlikte code_received olarak döner, çünkü göndericiler kodu farklı biçimlendirir.
- 3
POST /activations/{id}/complete
Aktivasyonu kapatın ve hattı serbest bırakın. Hiçbir şey gelmediyse hiçbir şey yapmayın: pencerenin süresi kendiliğinden dolar ve bakiye geri yüklenir. Erken iptal, aynı çağrının farklı adıdır.
Çalışan bir örnek
VSN_KEY değerini ayarlayın ve çalıştırın. Yorum satırlarındaki yanıtlar gerçek biçimlerdir, saklamak isteyeceğiniz alanlar dahil.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Hız sınırları
Anahtar başına dakikada 120 istek, saniyede 20'ye kadar ani yükselme. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset taşır; 429 ise tahmin ettirmek yerine ne kadar bekleyeceğinizi söyler.
API amaçlandığı gibi kullanılırsa sınır nadiren darboğazdır: doksan yoklama yerine tek uzun yoklama, zamanlayıcı yerine webhook ve ülke ile servis listelerinin açılışta önbelleğe alınması. Gerçekten daha fazla alana ihtiyacınız varsa isteyin: bir sınırı yükseltmek, bir anahtar filosunda hata ayıklamaktan ikimiz için de kolaydır.
İdempotans
POST /activations üzerinde bir Idempotency-Key başlığı gönderin. Aynı anahtarı 24 saat içinde tekrarlamak, ikinci bir numara satın alıp sizi iki kez ücretlendirmek yerine, özgün aktivasyonu güncel hâliyle ve Idempotent-Replay başlığıyla döndürür.
Anahtar gövdenin özeti değildir: kullanılmış bir anahtarla farklı bir yük göndermek yine ilk aktivasyonu döndürür. Mantıksal satın alma başına tek anahtar üretin — UUID yeterlidir — ve onu yeniden denemelerde kullanın, asla farklı satın almalarda.
Eski handler_api istemcileri
Klasik handler_api.php protokolü için yazılmış betikler çalışmaya devam eder. Onları uyumluluk uç noktasına yöneltin, api_key değerini değiştirin; aynı eylemler her zamanki ACCESS_ ve STATUS_ belirteçlerini döndürür.
Bu, aynı havuzun üzerindeki bir çeviri katmanıdır; dolayısıyla fiyatlar, stok ve iadeler her iki yolda da birebir aynı davranır. Yeni kod yine de /api/v1 kullanmalı: JSON yanıtlar, belirteç biçiminde yeri olmayan zaman damgalarını, hata kodlarını ve fiyat alanlarını taşır.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Ajanlar, MCP ve keşif
Barındırılan bir MCP sunucusu, bir OpenAPI 3.1 belgesi ve bir llms.txt dizini var; böylece bir ajan ihtiyaç duyduğu üç aracı elle yazılmış tutkal olmadan keşfedebilir. İstemcinizi aşağıdaki uç noktaya yöneltin; al, bekle ve bırak araçlarını bulacaktır.
Otonom bir şeyin bakiyeden harcamasına izin vermeden önce: anahtarı numbers:read ve numbers:write ile sınırlayın, her satın almaya max_price_cents tavanı koyun ve ona kendi anahtarını verin ki iptal etmek üretim entegrasyonunuzu düşürmesin.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Üretime geçmeden önce
- Her satın almada max_price_cents ayarlayın. Fiyatlar havuzla birlikte hareket eder ve sınırsız bir ajan seve seve pahalı ucundan alır.
- Kimlikleri opak dizeler olarak ele alın. Aktivasyon kimlikleri bugün on haneli; bu bir söz değil, uzunlukları da öyle.
- Hata koduna göre dallanın, asla mesaja göre değil. Kodlar bir sürüm içinde sabittir; mesajlar insanlar için yazılır ve yeniden yazılır.
- sms.received olayına abone olun ve imzayı doğrulayın — ham gövde üzerinde HMAC-SHA256, beş dakikalık tekrar penceresiyle — size zaten bildirilebilecek bir durumu yoklamak yerine.
- Hesaplamaları tam sayı sent alanları üzerinde yapın. Yanlarındaki biçimlendirilmiş dizeler görüntüleme içindir ve dile göre değişir.
Tam dokümantasyon
Altı uç nokta, hata tabloları, webhook yükleri, kapsamlar ve eski belirteç eşlemesi.
Sık sorulan sorular
Servisin gönderdiği andan itibaren ortanca teslim dokuz saniyenin altında. Uzun yoklama, kuyruğun uzun olması nedeniyle var: aktivasyon 20 dakika açık kalır ve hiçbir şey düşmezse iadeyle sona erer.
Sizin ele almanız gereken bir şey yok. Pencere kapanır, bakiye otomatik olarak geri yüklenir ve aktivasyon, API'den okuyabileceğiniz bir süresi dolmuş durumla biter.
Evet ve hiçbir maliyeti yok. Anahtarlar sabit kapsamlar, isteğe bağlı bir IP izin listesi ve oluştururken seçilen bir bitiş tarihi taşır; böylece sızan bir staging anahtarı üretimde numara satın alamaz.
İnce, bağımlılıksız sarmalayıcılar var, ama API JSON üzerinden altı uç noktadan ibaret: üç çağrılık akış için fetch, requests ya da curl gerçekten yeterli.
Tek bir aktivasyonda evet: aktivasyon açıkken ek mesajlar aynı numaraya gelir. Oturumlar arasında kiralama gerekir; kiralama hattı dört saatten on iki aya kadar tutar.
Hayır. Aynı havuz, aynı fiyatlar; yalnızca yanıtın kodlaması farklı.