SMSCode API Kullanımı: Geliştirici Entegrasyon Rehberi (2026)

SMSCode API Kullanımı: Geliştirici Entegrasyon Rehberi (2026)

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

  1. smscode.gg adresine gidin ve oturum açın
  2. Sağ üst köşedeki kullanıcı menüsünden “Hesap Ayarları” veya “API” seçeneğine gidin
  3. 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:

  1. Numara Al (getNumber) — Platform ve ülke belirterek bir numara satın al
  2. Durum Kontrol Et (getStatus) — SMS gelene kadar periyodik olarak sorgula
  3. Kodu Oku — Gelen SMS kodunu işle
  4. 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:

ParametreZorunluAçıklama
actionEvetgetNumber sabit değeri
serviceEvetPlatform kodu (ör. wa, tg, go)
countryEvetÜlke ID’si; 0 = herhangi bir ülke
operatorHayırOperatör tercihi
refHayırReferans 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ği
  • TELEFON_NUMARASI: Platforma gireceğiniz numara

Hata yanıtları:

YanıtAnlamÇözüm
NO_NUMBERSO platform/ülke için stok yokFarklı ülke dene veya bekle
NO_BALANCEBakiye yetersizDashboard’dan bakiye yükle
BAD_SERVICEGeçersiz platform koduDoğru kodu kontrol et
BAD_KEYAPI anahtarı geçersizAnahtarı 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:

ParametreZorunluAçıklama
actionEvetgetStatus sabit değeri
idEvetgetNumber’dan dönen aktivasyon ID’si

Olası yanıtlar:

YanıtAnlam
STATUS_WAIT_CODEHenüz SMS gelmedi, bekliyoruz
STATUS_OK:123456SMS geldi, kod: 123456
STATUS_CANCELAktivasyon iptal edildi
STATUS_WAIT_RETRYYeniden SMS bekleniyor
STATUS_WAIT_RESENDSMS 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ğerAnlamNe Zaman Kullanılır
1SMS alındı, kod görüntülendiSMS geldiğinde otomatik set edilebilir
3Yeniden SMS talep etİlk kod işe yaramadıysa
6Aktivasyon tamamlandıDoğrulama başarılı
8Aktivasyon iptal edildiDoğ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ı

PlatformServis KoduNot
WhatsAppwaEn yaygın kullanılan
TelegramtgNon-VoIP numara gerektirir
GooglegoGmail, G hesap doğrulaması
Instagramig
Facebookfb
Twitter/Xtw
TikToktt
Binancebn
Coinbaseci
Spotifysp
Discordds
Tinderti
OpenAI/ChatGPToi
Steamst
PayPalpp

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:

SMSCode'i denemeye hazır mısınız?

Hesap oluşturun ve ilk sanal numaranızı iki dakikadan kısa sürede alın.

Başlayın →