Ana içeriğe geç

Entegratör Dokümantasyonu

SMS API Entegrasyon Kılavuzu​

Sürüm: 1.0
Son Güncelleme: 26 Mart 2025
İletişim: destek@mobildev.com

İçindekiler​

  1. Genel Bakış
  2. Hızlı Başlangıç
  3. Senaryo 1: Transactional SMS API Key
  4. Senaryo 2: Kampanya SMS OAuth2 Yetkilendirme
  5. Ortak Güvenlik Kuralları
  6. Hata Kodları
  7. Test Senaryoları
  8. SSS

1. Genel Bakış​

1.1 Hangi Senaryo Ne Zaman Kullanılır?​

İhtiyacınızKullanılacak YöntemDoküman Bölümü
Sistemden sisteme otomatik SMS (şifre sıfırlama, 2FA, bildirim)API Key + HMACBölüm 3
Web arayüzünüzden manuel kampanya gönderimiOAuth2 + JWTBölüm 4

1.2 Temel Bilgiler​

BilgiDeğer
API Base URLhttps://xmlapi.mobildev.com
Desteklenen FormatJSON / XML
Karakter SetiUTF-8
Zaman DilimiUTC+3 (Türkiye Saati)
Rate LimitTransactional: 5000/dk, Kampanya: 10000/saat

2. Hızlı Başlangıç​

2.1 İlk Adımlar​

  1. Entegrator / Müşteri Başvuru adımları

2.2 Test Ortamı Bilgileri​

Test API Base URL: https://test-xmlapi.mobildev.com
Test Entegratör Client ID: ent_test_2024_001
Test Entegratör Client Secret: test_secret_xyz789
Test API Key: test_api_key_123456

⚠️ Test ortamında SMS gerçekten gönderilmez, simüle edilir.

3. Senaryo 1: Transactional SMS API Key​

3.1 API Key Oluşturma​

⚠️ Bu işlem entegratör panelinizden yapılır. Her entegratör kendi API key'lerini oluşturabilir.

Panelde yapmanız gerekenler:

  1. "API Key'lerim" sayfasına gidin
  2. "Yeni API Key Oluştur" butonuna tıklayın
  3. Key adı girin (örn: "Prod SMS Key")
  4. IP Whitelist Ekleyin
  5. Entegrator Firma Bilgisini Ekleyin (Burası Detaylandırılacak)
  6. Geçerlilik süresi seçin (30/60/90 gün)
  7. E-İmza veya Mobil İmza ile onaylayın

Oluşturduktan sonra size gösterilecek bilgiler:

{
    "api_key": "ent_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "api_secret": "xK9mQ2pR5tY7wE3aG8bN4cL6dV0fH1jZ",
    "valid_until": "2025-06-24T10:30:00Z"
}

🔐 API Secret sadece 1 kez gösterilir! Güvenli bir yere kaydedin.

3.2 Transactional SMS Gönderme​

Endpoint​

POST /v1/transactional/send

Headers​

HeaderZorunluAçıklama
X-API-Key✅Size verilen API Key
X-Timestamp✅Unix timestamp (saniye cinsinden)
X-Nonce✅Benzersiz UUID (her istekte farklı)
X-Signature✅HMAC-SHA256 imzası
Content-Type✅application/json

İmza Hesaplama​

const crypto = require('crypto');

function calculateSignature(apiSecret, method, path, timestamp, nonce, body) {
    const payload = `${method}\n${path}\n${timestamp}\n${nonce}\n${body}`;
    return crypto
        .createHmac('sha256', apiSecret)
        .update(payload)
        .digest('hex');
}

İstek Gövdesi​

<MainmsgBody>
    <Action>0</Action>
    <Mesgbody>Mobildev XMLAPI Servis Test Mesajidir</Mesgbody>
    <Numbers>5056647139</Numbers>
    <AccountId></AccountId>
    <Originator></Originator>
    <SDate>090520231500</SDate>
    <EDate></EDate>
    <Encoding>0</Encoding>
    <MessageType>C</MessageType>
    <RecipientType>B</RecipientType>
    <Tags></Tags>
</MainmsgBody>
AlanZorunluTipAçıklama
Action✅string veya arrayTek numara veya liste (max 1000)

Örnek İstek (Node.js)​

const axios = require('axios');
const crypto = require('crypto');

const API_KEY = 'ent_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';
const API_SECRET = 'xK9mQ2pR5tY7wE3aG8bN4cL6dV0fH1jZ';
const BASE_URL = 'https://xmlapi.mobildev.com';

async function sendTransactionalSMS(to, message) {
    const method = 'POST';
    const path = '/v1/transactional/send';
    const timestamp = Math.floor(Date.now() / 1000);
    const nonce = crypto.randomUUID();
    const body = JSON.stringify({ to, message });
    
    const signature = crypto
        .createHmac('sha256', API_SECRET)
        .update(`${method}\n${path}\n${timestamp}\n${nonce}\n${body}`)
        .digest('hex');
    
    const response = await axios.post(`${BASE_URL}${path}`, { to, message }, {
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY,
            'X-Timestamp': timestamp,
            'X-Nonce': nonce,
            'X-Signature': signature
        }
    });
    
    return response.data;
}

Örnek Yanıt​

ID:123456789
01 : Bkz Hatta kodları

3.3 SMS Durumu Sorgulama​

GET /v1/transactional/status/{message_id}
<MainReportRoot>
    <MsgID>1825415058</MsgID>
</MainReportRoot>

Headers​

HeaderZorunluAçıklama
X-API-Key✅API Key
X-Timestamp✅Unix timestamp
X-Nonce✅Benzersiz UUID
X-Signature✅HMAC imzası

Örnek Yanıt​

SMS API Standart Raporları

3.4 API Key Süre Uzatma​

Yöntem 1: Email ile gelen linkten

  • Her API key süre dolumuna 7 gün kala email alırsınız
  • Linke tıklayıp giriş yaparak 90 gün uzatabilirsiniz

Yöntem 2: Panelden manuel

  1. "API Key'lerim" sayfasına gidin
  2. Uzatmak istediğiniz key'in yanındaki "Süre Uzat" butonuna tıklayın
  3. E-İmza veya Mobil İmza ile onaylayın

4. Senaryo 2: Kampanya SMS OAuth2 Yetkilendirme​

4.1 Genel Akış​

Kullanıcı (Entegrator Paneli)          Mobildev Auth              Mobildev Auth API
       │                                    │                           │
       │  1. "Yetki Ver" butonuna tıklar    │                           │
       │───────────────────────────────────>│                           │
       │                                    │                           │
       │  2. OAuth ekranımıza yönlendirilir │                           │
       │<───────────────────────────────────│                           │
       │                                    │                           │
       │  3. Giriş yapar + imzalar          │                           │
       │───────────────────────────────────>│                           │
       │                                    │                           │
       │  4. Authorization code alır        │                           │
       │<───────────────────────────────────│                           │
       │                                    │                           │
       │  5. Code'u backend'inize gönderir  │                           │
       │                                    │                           │
       │  6. Token isteği (code + secret)   │──────────────────────────>│
       │                                    │                           │
       │  7. Access Token alır              │<──────────────────────────│
       │                                    │                           │
       │  8. Token ile SMS gönderir         │──────────────────────────>│

4.2 OAuth İstemci Bilgileri​

Panelinizden size verilecek bilgiler:

{
    "client_id": "ent_bt_2024_001",
    "client_secret": "sec_8xK9mQ2pR5tY7wE3",
    "redirect_uris": [
        "https://sizinsiteniz.com/oauth/callback",
        "https://sizinsiteniz.com/oauth/callback-test"
    ]
}

4.3 Yetkilendirme İsteği (Frontend)​

// Kullanıcı butona tıkladığında
function startOAuth() {
    const clientId = "ent_bt_2024_001";
    const redirectUri = encodeURIComponent("https://sizinsiteniz.com/oauth/callback");
    const scope = encodeURIComponent("sms:campaign sms:report");
    const state = crypto.randomUUID();
    
    // State'i sakla (CSRF koruması)
    sessionStorage.setItem('oauth_state', state);
    
    // OAuth sayfamıza yönlendir
    window.location.href = `https://xmlapi.mobildev.com/oauth/authorize?` +
        `client_id=${clientId}&` +
        `redirect_uri=${redirectUri}&` +
        `response_type=code&` +
        `scope=${scope}&` +
        `state=${state}`;
}

4.4 Callback ve Token Alma (Backend)​

// GET /oauth/callback
app.get('/oauth/callback', async (req, res) => {
    const { code, state } = req.query;
    
    // State doğrulama
    const savedState = sessionStorage.getItem('oauth_state');
    if (state !== savedState) {
        return res.status(400).send('Invalid state');
    }
    
    // Token isteği
    const tokenResponse = await fetch('https://xmlapi.mobildev.com/oauth/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64')
        },
        body: new URLSearchParams({
            grant_type: 'authorization_code',
            code: code,
            redirect_uri: 'https://sizinsiteniz.com/oauth/callback',
            client_id: clientId
        })
    });
    
    const tokens = await tokenResponse.json();
    
    // Token'ları güvenli sakla
    await saveTokens(tokens);
    
    res.send('Yetkilendirme başarılı!');
});

4.5 Token Yanıtı​

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "scope": "sms:campaign sms:report",
    "issued_at": 1742995200
}

4.6 Kampanya SMS Gönderme​

Endpoint​

POST /v1/campaign/send

Headers​

HeaderZorunluAçıklama
Authorization✅Bearer <access_token>
Content-Type✅application/json

İstek Gövdesi​

<MainmsgBody>
    <Action>1</Action>
    <Messages>
        <Message>
            <Mesgbody>Lorem ipsum dolor sit amet, consectetur adipiscing elit. .</Mesgbody>
            <Number>5056647139</Number>
        </Message>
    </Messages>
    <AccountId></AccountId>
    <Originator></Originator>
    <SDate></SDate>
    <EDate></EDate>
    <Encoding>1</Encoding>
    <MessageType>C</MessageType>
    <RecipientType></RecipientType>
    <Tags></Tags>
</MainmsgBody>
AlanZorunluTipAçıklama

Örnek İstek (Node.js)​

async function sendCampaign(accessToken, campaignData) {
    const response = await axios.post(
        'https://xmlapi.mobildev.com/v1/campaign/send',
        campaignData,
        {
            headers: {
                'Authorization': `Bearer ${accessToken}`,
                'Content-Type': 'application/json'
            }
        }
    );
    return response.data;
}

Örnek Yanıt​

ID:1234567890
01
02
03

4.7 Kampanya Durumu Sorgulama​

GET /v1/campaign/status/{ID}

Headers​

HeaderZorunlu
Authorization✅ Bearer <access_token>

Örnek Yanıt​

Standart SMS Raporları

4.8 Yetkiyi İptal Etme​

Kullanıcılar panelimizden yetkilerini iptal edebilir. İptal durumunda:

  • Access token anında geçersiz olur
  • Webhook ile size bildirim gönderilir (opsiyonel)

5. Ortak Güvenlik Kuralları​

5.1 IP Beyaz Listesi​

Tüm API istekleri önceden tanımlanmış IP aralıklarından gelmelidir. Yetkili IP Adresleri Uygulama Yönetim panelinden eklenir.

IP aralığı ekleme:

5.2 Rate Limitler​

EndpointLimitAşımda
/v1/transactional/send5000/dkHTTP 429
/v1/campaign/send10000/saatHTTP 429
/oauth/token100/günHTTP 429

Rate Limit Headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4995
X-RateLimit-Reset: 1705308600

5.3 Zaman Aşımı​

  • İsteklerin 30 saniye içinde tamamlanması gerekir
  • OAuth authorization code 10 dakika geçerlidir
  • Access token seçtiğiniz süre (1/7/30 gün) geçerlidir

6. Hata Kodları​

6.1 HTTP Status Kodları​

KodAnlamıAçıklama
200Başarılıİstek başarıyla işlendi
400Hatalı İstekEksik veya geçersiz parametre
401YetkisizAPI Key/Token geçersiz veya eksik
403YasakIP beyaz liste, zaman aralığı veya scope hatası
404BulunamadıEndpoint veya kaynak yok
429Çok Fazla İstekRate limit aşıldı
500Sunucu HatasıBizim tarafımızda bir sorun

6.2 Detaylı Hata Kodları​

errorAçıklamaÇözüm
invalid_api_keyAPI Key geçersizDoğru API Key kullandığınızdan emin olun
api_key_expiredAPI Key süresi dolmuşPanelden süre uzatın
invalid_signatureHMAC imzası yanlışİmza hesaplama mantığınızı kontrol edin
timestamp_expiredTimestamp çok eskiSistem saatinizi senkronize edin
nonce_already_usedNonce tekrar kullanılmışHer istekte yeni UUID üretin
ip_not_whitelistedIP beyaz listede değilIP adresinizi ekleyin
time_restrictionZaman aralığı dışıİzin verilen saatlerde gönderin
insufficient_scopeScope yetkisi yokDaha geniş yetki alın
token_expiredJWT süresi dolmuşYeniden yetkilendirme yapın
consent_revokedYetki iptal edilmişYeniden yetkilendirme yapın
insufficient_balanceBakiye yetersizBakiye yükleyin
rate_limit_exceededRate limit aşıldıBekleyip tekrar deneyin

7. Test Senaryoları​

7.1 Senaryo 1 – Transactional SMS Testleri​

Test 1.1: Başarılı SMS Gönderimi​

curl -X POST https://test-xmlapi.mobildev.com/v1/transactional/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test_api_key_123456" \
  -H "X-Timestamp: 1742995200" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Signature: hesaplanacak_hmac" \
  -d '{
    "to": "5551234567",
    "message": "Test mesajı",
    "template_id": "test_template"
  }'

Beklenen Yanıt: HTTP 200, success: true

Test 1.2: Geçersiz API Key​

curl -X POST https://test-xmlapi.mobildev.com/v1/transactional/send \
  -H "X-API-Key: yanlis_api_key" \
  ...

Beklenen Yanıt: HTTP 401, error: invalid_api_key

Test 1.3: Hatalı İmza​

curl -X POST https://test-xmlapi.mobildev.com/v1/transactional/send \
  -H "X-Signature: yanlis_imza" \
  ...

Beklenen Yanıt: HTTP 401, error: invalid_signature

Test 1.4: Süresi Dolmuş API Key​

API Key süresi dolduktan sonra gönderim deneyin.

Beklenen Yanıt: HTTP 401, error: api_key_expired

Test 1.5: Beyaz Liste Dışı IP​

Farklı bir IP'den istek gönderin.

Beklenen Yanıt: HTTP 403, error: ip_not_whitelisted

7.2 Senaryo 2 – OAuth2 Kampanya Testleri​

Test 2.1: Yetkilendirme Akışı​

  1. Yetkilendirme isteği başlat:
window.location.href = 'https://test-xmlapi.mobildev.com/oauth/authorize?client_id=ent_test_2024_001&redirect_uri=https://test.sizinsiteniz.com/callback&response_type=code&scope=sms:campaign&state=test123';

  1. Beklenen: OAuth login sayfası açılır

  2. Test kullanıcısı ile giriş yap:

    • Email: test@entegrator.com
    • Şifre: Test123!

  3. Mobil İmza test kodu: 123456

  4. Beklenen: Authorization code ile callback'e yönlenme

Test 2.2: Token Alma​

curl -X POST https://test-xmlapi.mobildev.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'ent_test_2024_001:test_secret_xyz789' | base64)" \
  -d "grant_type=authorization_code&code=alınan_code&redirect_uri=https://test.sizinsiteniz.com/callback&client_id=ent_test_2024_001"

Beklenen Yanıt: HTTP 200, access_token içerir

Test 2.3: Geçersiz Code ile Token Alma​

curl -X POST https://test-xmlapi.mobildev.com/oauth/token \
  -d "grant_type=authorization_code&code=gecersiz_code&..."

Beklenen Yanıt: HTTP 400, error: invalid_grant

Test 2.4: Token ile Kampanya Gönderme​

curl -X POST https://test-xmlapi.mobildev.com/v1/campaign/send \
  -H "Authorization: Bearer alınan_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_name": "Test Kampanya",
    "segments": ["test_group"],
    "message": "Bu bir test kampanyasıdır."
  }'

Beklenen Yanıt: HTTP 200, campaign_id içerir

Test 2.5: Zaman Aralığı Kontrolü​

Yetki alırken time_start: 09:00, time_end: 17:00 seçtiyseniz, bu saat dışında gönderim deneyin.

Beklenen Yanıt: HTTP 403, error: time_restriction

Test 2.6: Süresi Dolmuş Token​

Token süresi dolduktan sonra gönderim deneyin.

Beklenen Yanıt: HTTP 401, error: token_expired

Test 2.7: Yetki İptali​

  1. Kullanıcı panelinden yetkiyi iptal edin
  2. İptal edilen token ile gönderim deneyin

Beklenen Yanıt: HTTP 401, error: consent_revoked

7.3 Test Senaryoları Kontrol Listesi​

SenaryoTestBeklenenDurum
1.1Başarılı SMS200 OK☐
1.2Geçersiz API Key401 invalid_api_key☐
1.3Hatalı imza401 invalid_signature☐
1.4Süresi dolmuş key401 api_key_expired☐
1.5Beyaz liste dışı IP403 ip_not_whitelisted☐
1.6Rate limit aşımı429 rate_limit_exceeded☐
2.1OAuth akışıCode alınır☐
2.2Token alma200 + access_token☐
2.3Geçersiz code400 invalid_grant☐
2.4Kampanya gönderimi200 + campaign_id☐
2.5Zaman aralığı403 time_restriction☐
2.6Süresi dolmuş token401 token_expired☐
2.7Yetki iptali401 consent_revoked☐

8. SSS​

S1: API Secret'ımı kaybettim, ne yapmalıyım?​

C: Secret sadece 1 kez gösterilir. Kaybettiyseniz panelden yeni bir API Key oluşturmanız gerekir. Eski key'i iptal edin.

S2: Test ortamında gerçek SMS gönderiliyor mu?​

C: Hayır, test ortamında SMS simüle edilir. Gerçek gönderim için production ortamını kullanın.

S3: Birden fazla API Key oluşturabilir miyim?​

C: Evet, farklı uygulamalarınız için farklı API Key'ler oluşturabilirsiniz.

S4: SMS içeriğinde emoji kullanabilir miyim?​

C: Evet, Unicode desteği vardır. Ancak her emoji 2 karakter sayılır, karakter limitinizi etkiler.

S5: İmza hesaplamasında body nasıl olmalı?​

C: Body stringify edilmiş ve minify edilmiş (boşluksuz) JSON olmalı. Örnek: {"to":"555123","message":"test"}

S6: Hangi durumlarda yetkim iptal olur?​

C:

  • Kullanıcı panelden iptal ederse
  • Yetki süresi dolduğunda
  • Mevzuat gereği zorunlu iptal durumunda

S7: Webhook desteğiniz var mı?​

C: Evet, kampanya tamamlanma, API key süre dolumu gibi olaylar için webhook kurabiliriz. Detaylar için destek ekibiyle iletişime geçin.

S8: Hangi programlama dillerini destekliyorsunuz?​

C: REST API olduğu için tüm dilleri destekleriz. Örnek kodlar: Node.js, Python, PHP, Java, C#, Go.

Ekler​

Ek 1: Örnek Python Kodu (Transactional SMS)​

import requests
import time
import uuid
import hmac
import hashlib
import json

API_KEY = "ent_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
API_SECRET = "xK9mQ2pR5tY7wE3aG8bN4cL6dV0fH1jZ"
BASE_URL = "https://xmlapi.mobildev.com"

def send_sms(to, message):
    method = "POST"
    path = "/v1/transactional/send"
    timestamp = int(time.time())
    nonce = str(uuid.uuid4())
    body = json.dumps({"to": to, "message": message}, separators=(',', ':'))
    
    payload = f"{method}\n{path}\n{timestamp}\n{nonce}\n{body}"
    signature = hmac.new(
        API_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Timestamp": str(timestamp),
        "X-Nonce": nonce,
        "X-Signature": signature
    }
    
    response = requests.post(f"{BASE_URL}{path}", data=body, headers=headers)
    return response.json()

# Kullanım
result = send_sms("5551234567", "Test mesajı")
print(result)

Ek 2: Örnek PHP Kodu (OAuth Token)​

<?php
$clientId = 'ent_bt_2024_001';
$clientSecret = 'sec_8xK9mQ2pR5tY7wE3';
$code = $_GET['code']; // Callback'ten gelen code

$ch = curl_init('https://xmlapi.mobildev.com/oauth/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type' => 'authorization_code',
    'code' => $code,
    'redirect_uri' => 'https://sizinsiteniz.com/oauth/callback',
    'client_id' => $clientId
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/x-www-form-urlencoded',
    'Authorization: Basic ' . base64_encode($clientId . ':' . $clientSecret)
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

// Token'ları sakla
$accessToken = $tokens['access_token'];
?>