TL;DR: SMSCode API, SMS doğrulama süreçlerini otomatikleştirmek isteyen geliştiriciler için tasarlanmıştır. API anahtarınızı alın, platform ve ülke seçin, numara aktive edin, OTP kodu alın — hepsi birkaç HTTP isteğiyle. Python, JavaScript ve cURL örnekleri bu rehberde.
SMSCode’un web paneli bireysel kullanım için mükemmeldir. Bir ülke seçersiniz, platform seçersiniz, numarayı kiralar ve SMS’i beklersiniz. Tüm bunları tıklama ve beklemeyle kendiniz yönetirsiniz.
Ancak işler büyüdüğünde bu yaklaşım çalışmaz. Yüzlerce hesap doğrulaması yapan bir yazılım ekibi, SMS doğrulaması içeren bir akışı otomatik test eden bir QA mühendisi, ya da kendi ürününe SMS doğrulama özelliği entegre etmek isteyen bir geliştirici için REST API tek gerçekçi çözümdür.
Bu rehberde SMSCode API’sinin nasıl kullanılacağını baştan sona ele alıyoruz. Temel REST bilgisine sahip olduğunuz varsayılıyor.
API Erişimi: İlk Adımlar
API Anahtarı Alma
- smscode.gg adresine gidin ve oturum açın
- Sağ üst köşedeki kullanıcı menüsünden “Hesap Ayarları” veya “API” seçeneğine gidin
- API anahtarınızı kopyalayın
API anahtarı, tüm isteklerinizde kimlik doğrulama için kullanılır. Bu anahtarı kimseyle paylaşmayın, kaynak koduna yazmayın. Anahtarın yetkisiz kullanımı bakiyenizi tüketir.
API Base URL
SMSCode iki farklı API formatını destekler. Bu rehberde SMS Activate uyumlu formattan bahsedeceğiz; bu format en geniş kütüphane ve araç desteğine sahiptir:
https://smscode.gg/stubs/handler_api.php
Tüm istekler bu URL’e yapılır. İstek parametreleri query string olarak eklenir.
Kimlik Doğrulama
Her istekte API anahtarı api_key parametresi olarak gönderilir:
?api_key=YOUR_API_KEY
Temel API Akışı
SMS doğrulama otomasyonunun standart akışı dört adımdan oluşur:
- Numara Al (
getNumber) — Platform ve ülke belirterek bir numara satın al - Durum Kontrol Et (
getStatus) — SMS gelene kadar periyodik olarak sorgula - Kodu Oku — Gelen SMS kodunu işle
- Aktivasyonu Bitir (
setStatus) — Başarılı veya başarısız olarak kapat
Bu akış tüm platformlar için aynıdır; yalnızca platform kodu ve ülke kodu değişir.
API Endpoint Referansı
Numara Alma: getNumber
Belirli bir platform ve ülke için numara satın alır ve bakiyeden düşer.
Örnek istek:
GET /stubs/handler_api.php?api_key=YOUR_KEY&action=getNumber&service=wa&country=0
Parametreler:
| Parametre | Zorunlu | Açıklama |
|---|---|---|
action | Evet | getNumber sabit değeri |
service | Evet | Platform kodu (ör. wa, tg, go) |
country | Evet | Ülke ID’si; 0 = herhangi bir ülke |
operator | Hayır | Operatör tercihi |
ref | Hayır | Referans kodu |
Başarılı yanıt:
ACCESS_NUMBER:123456789:79001234567
Format: ACCESS_NUMBER:{ID}:{TELEFON_NUMARASI}
ID: Sonraki adımlarda kullanacağınız aktivasyon kimliğiTELEFON_NUMARASI: Platforma gireceğiniz numara
Hata yanıtları:
| Yanıt | Anlam | Çözüm |
|---|---|---|
NO_NUMBERS | O platform/ülke için stok yok | Farklı ülke dene veya bekle |
NO_BALANCE | Bakiye yetersiz | Dashboard’dan bakiye yükle |
BAD_SERVICE | Geçersiz platform kodu | Doğru kodu kontrol et |
BAD_KEY | API anahtarı geçersiz | Anahtarı kontrol et |
Durum Sorgulama: getStatus
Aktif aktivasyonun durumunu ve gelen SMS içeriğini sorgular.
Örnek istek:
GET /stubs/handler_api.php?api_key=YOUR_KEY&action=getStatus&id=123456789
Parametreler:
| Parametre | Zorunlu | Açıklama |
|---|---|---|
action | Evet | getStatus sabit değeri |
id | Evet | getNumber’dan dönen aktivasyon ID’si |
Olası yanıtlar:
| Yanıt | Anlam |
|---|---|
STATUS_WAIT_CODE | Henüz SMS gelmedi, bekliyoruz |
STATUS_OK:123456 | SMS geldi, kod: 123456 |
STATUS_CANCEL | Aktivasyon iptal edildi |
STATUS_WAIT_RETRY | Yeniden SMS bekleniyor |
STATUS_WAIT_RESEND | SMS yeniden gönderme bekleniyor |
SMS geldiğinde yanıt STATUS_OK:KOD formatında döner. İki nokta üst üste karakterinden sonraki kısım OTP kodudur.
Durum Güncelleme: setStatus
Aktivasyonun durumunu güncellemek için kullanılır. SMS alındıktan sonra aktivasyonu tamamlamak veya iptal etmek bu endpoint ile yapılır.
Örnek istek:
GET /stubs/handler_api.php?api_key=YOUR_KEY&action=setStatus&id=123456789&status=6
Status değerleri:
| Değer | Anlam | Ne Zaman Kullanılır |
|---|---|---|
1 | SMS alındı, kod görüntülendi | SMS geldiğinde otomatik set edilebilir |
3 | Yeniden SMS talep et | İlk kod işe yaramadıysa |
6 | Aktivasyon tamamlandı | Doğrulama başarılı |
8 | Aktivasyon iptal edildi | Doğrulama başarısız veya iptal |
Aktivasyonu her zaman 6 (tamamlandı) veya 8 (iptal) ile kapatın. Bu, iade hesaplamasının doğru çalışmasını sağlar.
Bakiye Sorgulama: getBalance
Hesap bakiyesini sorgular. Otomasyon sistemleri bakiye izleme için bunu düzenli çalıştırmalıdır.
Örnek istek:
GET /stubs/handler_api.php?api_key=YOUR_KEY&action=getBalance
Yanıt:
ACCESS_BALANCE:45.50
İki nokta üst üste karakterinden sonraki değer mevcut bakiyedir (USD).
Fiyat ve Stok Sorgulama: getPrices
Tüm platform ve ülke kombinasyonları için güncel fiyat ve stok bilgisi döner. Katalog oluşturmak veya en uygun ülkeyi belirlemek için kullanılır.
Örnek istek:
GET /stubs/handler_api.php?api_key=YOUR_KEY&action=getPrices&service=wa
Yanıt, platform bazında ülke-fiyat-stok bilgisi içeren JSON nesnesidir.
Yaygın Platform Kodları
| Platform | Servis Kodu | Not |
|---|---|---|
wa | En yaygın kullanılan | |
| Telegram | tg | Non-VoIP numara gerektirir |
go | Gmail, G hesap doğrulaması | |
ig | ||
fb | ||
| Twitter/X | tw | |
| TikTok | tt | |
| Binance | bn | |
| Coinbase | ci | |
| Spotify | sp | |
| Discord | ds | |
| Tinder | ti | |
| OpenAI/ChatGPT | oi | |
| Steam | st | |
| PayPal | pp |
Platform kodu listesi değişebilir. Güncel tam liste için getPrices endpoint’ini veya SMSCode dokümantasyonunu kontrol edin.
Kod Örnekleri
Python
import requests
import time
import os
API_KEY = os.environ.get("SMSCODE_API_KEY", "your_api_key_here")
BASE_URL = "https://smscode.gg/stubs/handler_api.php"
def get_balance() -> float:
"""Hesap bakiyesini sorgula."""
response = requests.get(BASE_URL, params={
"api_key": API_KEY,
"action": "getBalance"
})
text = response.text.strip()
if text.startswith("ACCESS_BALANCE"):
return float(text.split(":")[1])
raise Exception(f"Bakiye sorgulanamadı: {text}")
def get_number(service: str, country: int = 0) -> dict:
"""
Platform için numara satın al.
Args:
service: Platform kodu (ör. 'wa', 'tg', 'go')
country: Ülke ID'si; 0 = herhangi
Returns:
{'id': '...', 'phone': '...'}
"""
response = requests.get(BASE_URL, params={
"api_key": API_KEY,
"action": "getNumber",
"service": service,
"country": country
})
text = response.text.strip()
if text.startswith("ACCESS_NUMBER"):
parts = text.split(":")
return {"id": parts[1], "phone": parts[2]}
# Hata durumları
error_map = {
"NO_NUMBERS": "Bu platform/ülke için stok yok",
"NO_BALANCE": "Bakiye yetersiz — bakiye yükleyin",
"BAD_SERVICE": "Geçersiz platform kodu",
"BAD_KEY": "API anahtarı geçersiz",
}
raise Exception(error_map.get(text, f"Bilinmeyen hata: {text}"))
def wait_for_code(activation_id: str, timeout: int = 120) -> str:
"""
SMS kodunu bekle.
Args:
activation_id: getNumber'dan dönen ID
timeout: Maksimum bekleme süresi (saniye)
Returns:
OTP kodu (str)
Raises:
Exception: Timeout veya iptal durumunda
"""
deadline = time.time() + timeout
while time.time() < deadline:
response = requests.get(BASE_URL, params={
"api_key": API_KEY,
"action": "getStatus",
"id": activation_id
})
status = response.text.strip()
if status.startswith("STATUS_OK:"):
return status.split(":", 1)[1]
if status == "STATUS_CANCEL":
raise Exception("Aktivasyon iptal edildi")
if status not in ("STATUS_WAIT_CODE", "STATUS_WAIT_RETRY", "STATUS_WAIT_RESEND"):
raise Exception(f"Beklenmedik durum: {status}")
time.sleep(5)
raise Exception(f"Timeout: {timeout} saniyede SMS gelmedi")
def set_status(activation_id: str, status: int) -> bool:
"""
Aktivasyon durumunu güncelle.
Args:
activation_id: Aktivasyon ID'si
status: 1 (alındı), 3 (yeniden gönder), 6 (tamamla), 8 (iptal et)
Returns:
True (başarılı)
"""
response = requests.get(BASE_URL, params={
"api_key": API_KEY,
"action": "setStatus",
"id": activation_id,
"status": status
})
return response.text.strip() in ("ACCESS_CANCEL", "ACCESS_READY", "ACCESS_RETRY_GET")
def complete_activation(activation_id: str):
"""Aktivasyonu başarılı olarak tamamla."""
set_status(activation_id, 6)
def cancel_activation(activation_id: str):
"""Aktivasyonu iptal et (başarısız veya artık gerekli değil)."""
set_status(activation_id, 8)
# Tam kullanım örneği
def get_otp_for_platform(service: str, country: int = 0) -> tuple:
"""
Platform için numara al ve OTP kodunu döndür.
Returns:
(telefon_numarasi, otp_kodu) tuple
Kullanım:
phone, otp = get_otp_for_platform("wa")
"""
number_info = None
try:
# Bakiye kontrolü
balance = get_balance()
print(f"Mevcut bakiye: ${balance:.2f}")
# Numara al
number_info = get_number(service, country)
phone = number_info["phone"]
act_id = number_info["id"]
print(f"Numara alındı: {phone} (ID: {act_id})")
# Platforma numara gir — buraya platform-spesifik kod gelir
# platform.register(phone)
# SMS bekle
otp = wait_for_code(act_id)
print(f"OTP kodu: {otp}")
# Aktivasyonu tamamla
complete_activation(act_id)
return phone, otp
except Exception as e:
print(f"Hata: {e}")
if number_info:
cancel_activation(number_info["id"])
raise
if __name__ == "__main__":
phone, otp = get_otp_for_platform("wa")
print(f"\nSonuç: Numara={phone}, OTP={otp}")
JavaScript / Node.js
const axios = require('axios');
const API_KEY = process.env.SMSCODE_API_KEY || 'your_api_key_here';
const BASE_URL = 'https://smscode.gg/stubs/handler_api.php';
const apiRequest = (params) => axios.get(BASE_URL, { params: { api_key: API_KEY, ...params } });
async function getBalance() {
const { data } = await apiRequest({ action: 'getBalance' });
const text = data.trim();
if (text.startsWith('ACCESS_BALANCE:')) {
return parseFloat(text.split(':')[1]);
}
throw new Error(`Bakiye sorgulanamadı: ${text}`);
}
async function getNumber(service, country = 0) {
const { data } = await apiRequest({ action: 'getNumber', service, country });
const text = data.trim();
if (text.startsWith('ACCESS_NUMBER:')) {
const [, id, phone] = text.split(':');
return { id, phone };
}
const errors = {
NO_NUMBERS: 'Bu platform/ülke için stok yok',
NO_BALANCE: 'Bakiye yetersiz',
BAD_SERVICE: 'Geçersiz platform kodu',
BAD_KEY: 'API anahtarı geçersiz',
};
throw new Error(errors[text] || `Bilinmeyen hata: ${text}`);
}
async function waitForCode(activationId, timeout = 120000, interval = 5000) {
const deadline = Date.now() + timeout;
while (Date.now() < deadline) {
const { data } = await apiRequest({ action: 'getStatus', id: activationId });
const status = data.trim();
if (status.startsWith('STATUS_OK:')) {
return status.split(':', 2)[1];
}
if (status === 'STATUS_CANCEL') {
throw new Error('Aktivasyon iptal edildi');
}
await new Promise(resolve => setTimeout(resolve, interval));
}
throw new Error(`Timeout: ${timeout / 1000} saniyede SMS gelmedi`);
}
async function setStatus(activationId, status) {
await apiRequest({ action: 'setStatus', id: activationId, status });
}
async function getOTPForPlatform(service, country = 0) {
let numberInfo;
try {
const balance = await getBalance();
console.log(`Bakiye: $${balance.toFixed(2)}`);
numberInfo = await getNumber(service, country);
console.log(`Numara alındı: ${numberInfo.phone}`);
// Platforma numara gir
// await platform.register(numberInfo.phone);
const otp = await waitForCode(numberInfo.id);
console.log(`OTP: ${otp}`);
await setStatus(numberInfo.id, 6); // Tamamla
return { phone: numberInfo.phone, otp };
} catch (error) {
if (numberInfo) {
await setStatus(numberInfo.id, 8).catch(() => {}); // İptal et
}
throw error;
}
}
// Kullanım
(async () => {
const { phone, otp } = await getOTPForPlatform('wa');
console.log(`Tamamlandı! Numara: ${phone}, OTP: ${otp}`);
})().catch(console.error);
cURL (Komut Satırı)
Hızlı test ve shell script entegrasyonu için:
# Değişkenler
API_KEY="your_api_key_here"
BASE_URL="https://smscode.gg/stubs/handler_api.php"
# Bakiye sorgula
curl -s "$BASE_URL?api_key=$API_KEY&action=getBalance"
# WhatsApp için numara al
curl -s "$BASE_URL?api_key=$API_KEY&action=getNumber&service=wa&country=0"
# Durum sorgula (ID'yi değiştirin)
curl -s "$BASE_URL?api_key=$API_KEY&action=getStatus&id=123456789"
# Aktivasyonu tamamla
curl -s "$BASE_URL?api_key=$API_KEY&action=setStatus&id=123456789&status=6"
# Aktivasyonu iptal et
curl -s "$BASE_URL?api_key=$API_KEY&action=setStatus&id=123456789&status=8"
# Fiyatları listele (tüm platformlar)
curl -s "$BASE_URL?api_key=$API_KEY&action=getPrices" | python3 -m json.tool
Tam bash script örneği:
#!/bin/bash
set -euo pipefail
API_KEY="${SMSCODE_API_KEY:-}"
BASE_URL="https://smscode.gg/stubs/handler_api.php"
SERVICE="${1:-wa}"
COUNTRY="${2:-0}"
TIMEOUT=120
if [ -z "$API_KEY" ]; then
echo "Hata: SMSCODE_API_KEY ortam değişkeni tanımlı değil" >&2
exit 1
fi
call_api() {
curl -s "$BASE_URL?api_key=$API_KEY&$*"
}
echo "Numara alınıyor: service=$SERVICE, country=$COUNTRY"
RESPONSE=$(call_api "action=getNumber&service=$SERVICE&country=$COUNTRY")
if [[ "$RESPONSE" != ACCESS_NUMBER:* ]]; then
echo "Hata: $RESPONSE" >&2
exit 1
fi
ID=$(echo "$RESPONSE" | cut -d: -f2)
PHONE=$(echo "$RESPONSE" | cut -d: -f3)
echo "Numara alındı: $PHONE (ID: $ID)"
START=$(date +%s)
while true; do
NOW=$(date +%s)
ELAPSED=$((NOW - START))
if [ $ELAPSED -ge $TIMEOUT ]; then
echo "Timeout: SMS gelmedi" >&2
call_api "action=setStatus&id=$ID&status=8" > /dev/null
exit 1
fi
STATUS=$(call_api "action=getStatus&id=$ID")
if [[ "$STATUS" == STATUS_OK:* ]]; then
OTP="${STATUS#STATUS_OK:}"
echo "OTP: $OTP"
call_api "action=setStatus&id=$ID&status=6" > /dev/null
echo "Aktivasyon tamamlandı"
exit 0
fi
if [ "$STATUS" = "STATUS_CANCEL" ]; then
echo "Aktivasyon iptal edildi" >&2
exit 1
fi
sleep 5
done
Hata Yönetimi ve Güvenilirlik
Sağlam bir API entegrasyonu için hata senaryolarını önceden planlamanız gerekir:
import time
import random
def get_number_with_retry(service: str, max_retries: int = 3, country: int = 0) -> dict:
"""
Yeniden deneme mantığıyla numara al.
NO_NUMBERS durumunda bekleyerek yeniden dener.
"""
for attempt in range(max_retries):
try:
return get_number(service, country)
except Exception as e:
error_msg = str(e)
if "NO_NUMBERS" in error_msg:
if attempt < max_retries - 1:
wait_time = 30 * (attempt + 1) # 30s, 60s, 90s
print(f"Stok yok ({attempt + 1}. deneme), {wait_time}s bekleniyor...")
time.sleep(wait_time)
else:
raise
elif "NO_BALANCE" in error_msg:
raise # Bakiye hatası için yeniden deneme yapma
else:
# Beklenmedik hata — kısa beklemeyle yeniden dene
if attempt < max_retries - 1:
time.sleep(2 ** attempt + random.uniform(0, 1))
else:
raise
raise Exception(f"{max_retries} denemede numara alınamadı")
Rate Limiting ve İstek Hız Yönetimi
API’ye aşırı istek göndermek hem hesabınızı kısıtlar hem de hizmet kalitesini düşürür. Önerilen pratikler:
Durum sorgulamaları: Her sorgu arasında en az 5 saniye bekleyin. 5 saniyeden daha sık sorgulama çoğu durumda anlamsızdır — SMS genellikle 10-60 saniye içinde gelir.
Toplu işlemler: Paralel işlem başlatıyorsanız aralarına kısa gecikme ekleyin. 50 paralel istek aynı anda göndermek yerine her birini 0,5-1 saniye arayla başlatın.
NO_NUMBERS yanıtı: Hemen tekrar denemek yerine 30-60 saniye bekleyin. Stok genellikle birkaç dakika içinde yenilenir.
Hata döngüsünden kaçının: Aynı hatayı defalarca almanız, yaklaşımınızı değiştirmeniz gerektiğinin işaretidir — farklı ülke deneyin, platform kodunu kontrol edin veya daha sonra tekrar deneyin.
Güvenlik: API Anahtarını Koruma
import os
# YANLIŞ — anahtarı kaynak koduna yazmayın
API_KEY = "sk_live_abc123xyz..."
# DOĞRU — ortam değişkeninden alın
API_KEY = os.environ.get("SMSCODE_API_KEY")
if not API_KEY:
raise ValueError("SMSCODE_API_KEY ortam değişkeni tanımlı değil")
# .env dosyası (asla Git'e commit etmeyin)
SMSCODE_API_KEY=your_actual_key_here
# .gitignore
.env
.env.local
.env.production
Loglama sırasında dikkat: API anahtarı ve OTP kodlarını log dosyalarına yazmayın. Bir güvenlik olayı yaşandığında log dosyaları saldırganlara değerli bilgi sağlayabilir.
Pratikte Kullanım Senaryoları
Senaryo 1: Otomatik hesap oluşturma
Büyük ölçekte platform hesabı oluşturmanız gerektiğinde API’yi kullanabilirsiniz. Her hesap için numara al → platforma gir → OTP bekle → kodu gir → aktivasyonu tamamla döngüsünü otomatize edin.
Senaryo 2: CI/CD testi
Uygulamanız SMS doğrulama içeren bir akış kullanıyorsa, bu akışı her derleme veya deployment sonrasında otomatik test edebilirsiniz. Test tamamlanınca numara iptal edilir, maliyet minimumdur.
Senaryo 3: Çoklu ülke testi
Farklı ülke numaralarıyla platform davranışını test etmek için API’yi kullanın. Fiyat farklılıklarını, içerik politikalarını veya özellik farklılıklarını araştırmak için değerlidir.
Senaryo 4: Platform entegrasyonu
Kendi SaaS ürününüz SMS doğrulama gerektiriyorsa, SMSCode API’sini ürününüze entegre edebilirsiniz. Kullanıcılarınız numara kiralamadan SMS doğrulaması alabilir.
SMS Activate Uyumluluğu
SMSCode, SMS Activate ile tam API uyumluluğu sunar. Bu ne anlama gelir?
SMS Activate için yazılmış tüm kütüphaneler, araçlar ve scriptler, yalnızca base URL değiştirilerek SMSCode ile çalışır:
# SMS Activate kütüphanesi kullanıyorsanız
# Bunu değiştirin:
BASE_URL = "https://api.sms-activate.org/stubs/handler_api.php"
# Buna:
BASE_URL = "https://smscode.gg/stubs/handler_api.php"
Kod değişikliği bu kadardır. API parametreleri, yanıt formatları ve hata kodları birebir aynıdır.
FAQ
API dokümantasyonu nerede bulunur?
SMSCode web panelinde API bölümünde tam dokümantasyon mevcuttur. Bu rehber temel kullanım için yeterlidir; ileri seviye özellikler için paneldeki dokümantasyona başvurun.
API SMS Activate ile uyumlu mu?
Evet. SMSCode, SMS Activate uyumlu API sunar. SMS Activate için yazılmış mevcut kütüphaneler ve araçlar, yalnızca base URL değiştirilerek SMSCode ile çalışır.
Toplu numara alımı yapılabilir mi?
Her numara için ayrı getNumber isteği gerekir. Paralel istekler gönderilebilir; ancak rate limiting kurallarına dikkat edin. Çok sayıda paralel işlem için istekler arasına kısa gecikme ekleyin.
Hangi programlama dilleri için resmi SDK var?
SMSCode API standart HTTP üzerine kurulu olduğundan, HTTP istemcisi olan her dil ile kullanılabilir: Python, JavaScript/Node.js, PHP, Go, Ruby, Java, C#, Rust ve daha fazlası. Bu rehberde Python ve JavaScript örnekleri mevcuttur.
Log dosyalarında güvenli loglama nasıl yapılır?
API çağrılarını loglayın ancak hassas bilgileri maskeleleyin:
# Kötü: API anahtarı logda görünüyor
logger.info(f"İstek URL: {url}?api_key={API_KEY}&action=getBalance")
# İyi: Anahtar maskelendi
logger.info(f"Bakiye sorgulanıyor (api_key=****)")
OTP kodu birden fazla kez kullanılabilir mi?
Hayır. OTP kodları tek kullanımlık olarak tasarlanmıştır. Kod platforma bir kez girildikten sonra geçersiz hale gelir. Yeni bir doğrulama için yeni numara kiralamanız gerekir.
SMSCode API ile SMS doğrulama süreçlerinizi tam otomasyona alabilirsiniz. Başlamak için SMSCode’a kayıt olun ve API anahtarınızı alın.
İlgili rehberler: