VarSMS API Entegrasyon Rehberi: Adım Adım Kılavuz

VarSMS API'ye Giriş

VarSMS RESTful API'si, modern web ve mobil uygulamalara SMS onay, sanal numara ve doğrulama hizmetlerini entegre etmenin en kolay yoludur. Bu rehberde, VarSMS API'sini projenize nasıl entegre edeceğinizi adım adım öğreneceksiniz.

API Özellikleri

• RESTful mimari
• JSON formatında veri alışverişi
• HTTPS/SSL güvenli bağlantı
• Webhook desteği
• Rate limiting koruması
• Detaylı hata kodları
• Çoklu dil desteği (PHP, Python, Java, Node.js, .NET, Ruby)
• Gerçek zamanlı durum bildirimleri

1. API Anahtarı Alma

VarSMS API'sini kullanmak için öncelikle bir API anahtarı almanız gerekir:

1. VarSMS müşteri paneline giriş yapın
2. "API Ayarları" bölümüne gidin
3. "Yeni API Anahtarı Oluştur" butonuna tıklayın
4. API anahtarınızı güvenli bir yerde saklayın

Önemli: API anahtarınızı kimseyle paylaşmayın ve kaynak kodunuzda hardcode etmeyin. Ortam değişkenleri (environment variables) kullanın.

2. Temel API Kullanımı

Base URL

https://api.smsvar.com/v1

Authentication

Tüm API isteklerinde header'da API anahtarınızı göndermeniz gerekir:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

3. SMS Onay Kodu Gönderme

Endpoint

POST /sms/send

Request Body

{
  "phone": "+905551234567",
  "message": "Doğrulama kodunuz: {CODE}",
  "sender": "VarSMS",
  "code_length": 6,
  "expire_minutes": 5
}

Response

{
  "success": true,
  "message": "SMS başarıyla gönderildi",
  "data": {
    "sms_id": "sms_abc123xyz",
    "phone": "+905551234567",
    "code": "123456",
    "expire_at": "2025-11-10T10:05:00Z",
    "status": "sent"
  }
}

PHP Örneği

<?php
$apiKey = getenv('VARSMS_API_KEY');
$url = 'https://api.smsvar.com/v1/sms/send';

$data = [
    'phone' => '+905551234567',
    'message' => 'Doğrulama kodunuz: {CODE}',
    'sender' => 'VarSMS',
    'code_length' => 6,
    'expire_minutes' => 5
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    echo "SMS gönderildi. ID: " . $result['data']['sms_id'];
} else {
    echo "Hata: " . $result['message'];
}

curl_close($ch);
?>

Python Örneği

import os
import requests

api_key = os.getenv('VARSMS_API_KEY')
url = 'https://api.smsvar.com/v1/sms/send'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

data = {
    'phone': '+905551234567',
    'message': 'Doğrulama kodunuz: {CODE}',
    'sender': 'VarSMS',
    'code_length': 6,
    'expire_minutes': 5
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result['success']:
    print(f"SMS gönderildi. ID: {result['data']['sms_id']}")
else:
    print(f"Hata: {result['message']}")

Node.js Örneği

const axios = require('axios');

const apiKey = process.env.VARSMS_API_KEY;
const url = 'https://api.smsvar.com/v1/sms/send';

const data = {
  phone: '+905551234567',
  message: 'Doğrulama kodunuz: {CODE}',
  sender: 'VarSMS',
  code_length: 6,
  expire_minutes: 5
};

axios.post(url, data, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (response.data.success) {
    console.log(`SMS gönderildi. ID: ${response.data.data.sms_id}`);
  }
})
.catch(error => {
  console.error('Hata:', error.response.data.message);
});

4. SMS Onay Kodu Doğrulama

Endpoint

POST /sms/verify

Request Body

{
  "sms_id": "sms_abc123xyz",
  "code": "123456"
}

Response

{
  "success": true,
  "message": "Kod doğrulandı",
  "data": {
    "verified": true,
    "phone": "+905551234567",
    "verified_at": "2025-11-10T10:03:45Z"
  }
}

5. Sanal Numara İşlemleri

Mevcut Numaraları Listele

GET /virtual-numbers?country=TR&status=available

Sanal Numara Satın Al

POST /virtual-numbers/purchase

{
  "number_id": "vn_xyz789abc",
  "duration": "daily"
}

Sanal Numaraya Gelen SMS'leri Al

GET /virtual-numbers/{number_id}/messages

6. Webhook Entegrasyonu

VarSMS webhook sistemi, SMS durumu değişikliklerini gerçek zamanlı olarak uygulamanıza bildirir.

Webhook URL Tanımlama

Müşteri panelinden "Webhook Ayarları" bölümüne gidin ve callback URL'inizi tanımlayın:

https://varsms.com/webhooks/varsms

Webhook Payload

{
  "event": "sms.delivered",
  "sms_id": "sms_abc123xyz",
  "phone": "+905551234567",
  "status": "delivered",
  "delivered_at": "2025-11-10T10:02:30Z",
  "operator": "Turkcell"
}

Webhook Doğrulama

Güvenlik için webhook isteklerini doğrulayın:

<?php
$signature = $_SERVER['HTTP_X_VARSMS_SIGNATURE'];
$payload = file_get_contents('php://input');
$secret = getenv('VARSMS_WEBHOOK_SECRET');

$expectedSignature = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($signature, $expectedSignature)) {
    http_response_code(403);
    die('Invalid signature');
}

$data = json_decode($payload, true);
// Webhook verisini işle
?>

7. Hata Yönetimi

VarSMS API, standart HTTP durum kodları ve detaylı hata mesajları döndürür:

HTTP Durum Kodları

• 200 OK: İstek başarılı
• 201 Created: Kaynak oluşturuldu
• 400 Bad Request: Geçersiz istek
• 401 Unauthorized: Geçersiz API anahtarı
• 403 Forbidden: Yetkisiz erişim
• 404 Not Found: Kaynak bulunamadı
• 429 Too Many Requests: Rate limit aşıldı
• 500 Internal Server Error: Sunucu hatası

Hata Response Örneği

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Geçersiz telefon numarası formatı",
    "details": "Telefon numarası +90 ile başlamalıdır"
  }
}

8. Rate Limiting

API istekleriniz rate limiting'e tabidir. Limitler şunlardır:

• SMS gönderimi: 100 istek/dakika
• Doğrulama: 1000 istek/dakika
• Diğer endpoint'ler: 60 istek/dakika

Rate limit aşımında HTTP 429 hatası alırsınız. Response header'larında limit bilgisi bulunur:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699619400

9. Test Ortamı

VarSMS test ortamı, gerçek SMS göndermeden API'yi test etmenizi sağlar:

Test Base URL

https://api-test.smsvar.com/v1

Test Telefon Numaraları

Test ortamında bu numaraları kullanabilirsiniz:

• +905551111111 (her zaman başarılı)
• +905552222222 (her zaman başarısız)
• +905553333333 (gecikme simülasyonu)

10. En İyi Uygulamalar

Güvenlik

• API anahtarlarını asla kaynak kodunda saklamayın
• HTTPS kullanın
• Webhook signature'ları doğrulayın
• Rate limiting'i göz önünde bulundurun

Performans

• Asenkron istekler kullanın
• Webhook'ları tercih edin (polling yerine)
• Connection pooling kullanın
• Retry mekanizması ekleyin

Kullanıcı Deneyimi

• Yükleme göstergeleri ekleyin
• Hata mesajlarını kullanıcı dostu yapın
• SMS gelmezse "Tekrar Gönder" seçeneği sunun
• Zaman aşımı durumlarını yönetin

11. SDK ve Kütüphaneler

VarSMS resmi SDK'ları:

• PHP: composer require varsms/php-sdk
• Python: pip install varsms
• Node.js: npm install varsms
• Java: Maven/Gradle desteği
• .NET: NuGet paketi

12. Destek ve Kaynaklar

• 📚 Detaylı API Dokümantasyonu
• 💬 7/24 Teknik Destek
• 💻 Örnek Projeler
• 🐛 Hata Bildirimi

Sonuç

VarSMS API'si, güçlü özellikleri ve kolay kullanımı ile SMS onay ve sanal numara hizmetlerini uygulamanıza entegre etmenin en iyi yoludur. Bu rehberdeki adımları takip ederek, kısa sürede entegrasyonu tamamlayabilir ve kullanıcılarınıza güvenli doğrulama hizmetleri sunabilirsiniz.

Herhangi bir sorunuz olursa, VarSMS teknik destek ekibi size yardımcı olmak için hazırdır.