GetirSMS API Dokümantasyonu

GetirSMS API

SMS Gönderim Platformu REST API v1

GetirSMS API, uygulamalarınız ve sistemleriniz üzerinden programatik olarak SMS göndermenize, gönderim raporlarını sorgulamanıza ve bakiye bilgilerinizi kontrol etmenize olanak sağlar. RESTful mimari üzerine kurulmuştur ve JSON formatında veri alışverişi yapar.

RESTful API

Standart HTTP metotları ile kolay entegrasyon

Yüksek Performans

Tek istekte 100.000 numaraya SMS

Güvenli

API Key + IP Whitelist + Rate Limit

Base URL

https://your-domain.com/api/v1

Tüm endpoint'ler bu base URL üzerinden erişilir.

Kimlik Doğrulama

Tüm API isteklerinde kimlik doğrulaması gereklidir. API Key'inizi aşağıdaki yöntemlerden biriyle gönderebilirsiniz:

Authorization: Bearer API_KEYÖnerilen yöntem

X-API-Key: API_KEYAlternatif header

?api_key=API_KEYQuery parametresi (önerilmez)

🔑 API Key Nasıl Alınır?

GetirSMS paneline giriş yapın
Sol menüden SMS API bölümüne gidin
Yeni API Key butonuna tıklayın
Key adı, izinler ve opsiyonel ayarları belirleyin
Oluşturulan key'i güvenli bir yere kaydedin (sadece bir kez gösterilir!)

Örnek İstek

curl -X GET https://your-domain.com/api/v1/sms/balance \
  -H "Authorization: Bearer gsms_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

API Key İzinleri

Parametre	Tip	Zorunlu	Açıklama
sms:send	permission	Hayır	SMS gönderme izni
sms:report	permission	Hayır	Rapor sorgulama izni
sms:balance	permission	Hayır	Bakiye sorgulama izni
sms:status	permission	Hayır	Durum sorgulama izni

SMS Gönder

POST/api/v1/sms/send

Tek veya toplu SMS gönderimi yapar. Tek istekte en fazla 100.000 numaraya SMS gönderebilirsiniz. Her numara 1 kredi harcar. İstek JSON veya application/x-www-form-urlencoded formatında gönderilebilir.

Request Body Parametreleri

Parametre	Tip	Zorunlu	Açıklama
to	string \| string[]	Evet	Alıcı numara(lar). Tekli: "5551234567", çoklu: ["555...", "555..."] veya virgülle ayrılmış string
message	string	Evet	SMS mesaj içeriği. Maksimum karakter: GSM 160, Unicode 70
originator	string	Hayır	Gönderici adı (başlık). Belirtilmezse hesap varsayılanı kullanılır
encoding	string	Hayır	Karakter kodlaması. Değerler: "default", "tr" (Türkçe), "unicode"

Başarılı Yanıt (200)

{
  "success": true,
  "data": {
    "id": "clxx1234abcd",
    "messageId": "123456789",
    "phoneCount": 2,
    "creditCost": 2,
    "status": "sent",
    "message": "2 numaraya SMS başarıyla gönderildi."
  }
}

Hata Yanıtı (4xx/5xx)

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Yetersiz kredi. Mevcut: 50, Gerekli: 1000"
  }
}

Kod Örneği — cURL

curl -X POST https://your-domain.com/api/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["5551234567", "5559876543"],
    "message": "Merhaba, siparişiniz kargoya verildi!",
    "originator": "SIRKETADI"
  }'

Rapor Sorgula

GET/api/v1/sms/report?id=REQUEST_ID

POST/api/v1/sms/reportBody: {"id": "REQUEST_ID"}

Daha önce gönderilen bir SMS talebinin detaylı iletim raporunu sorgular. Rapor; iletilen, bekleyen ve başarısız SMS sayılarını içerir.

Parametreler

Parametre	Tip	Zorunlu	Açıklama
id	string	Evet	SMS gönderim talebi ID'si (SMS Gönder yanıtındaki 'id' alanı)

Başarılı Yanıt

{
  "success": true,
  "data": {
    "id": "clxx1234abcd",
    "status": "completed",
    "phoneCount": 1000,
    "creditCost": 1000,
    "report": {
      "delivered": 950,
      "pending": 0,
      "failed": 50,
      "total": 1000,
      "status": "published",
      "date": "2026-06-01T12:00:00.000Z"
    },
    "refund": {
      "amount": 50,
      "date": "2026-06-01T12:05:00.000Z"
    },
    "createdAt": "2026-06-01T10:00:00.000Z",
    "sentAt": "2026-06-01T10:00:05.000Z"
  }
}

📊 Rapor Durumları

draft

Rapor henüz tamamlanmadı, gönderim devam ediyor

complete

Tüm SMS'ler raporlandı, admin onayı bekleniyor

published

Rapor yayınlandı, iade varsa yapıldı

Kod Örneği — cURL

curl -X GET "https://your-domain.com/api/v1/sms/report?id=REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Durum Sorgula

GET/api/v1/sms/status?id=REQUEST_ID

Bir SMS gönderim talebinin mevcut durumunu ve temel bilgilerini sorgular. Rapor detayı içinendpoint'ini kullanın.

Parametreler

Parametre	Tip	Zorunlu	Açıklama
id	string	Evet	SMS gönderim talebi ID'si

Başarılı Yanıt

{
  "success": true,
  "data": {
    "id": "clxx1234abcd",
    "status": "sent",
    "phoneCount": 500,
    "creditCost": 500,
    "charCount": 98,
    "originator": "SIRKETADI",
    "messageId": "123456789",
    "reportStatus": "draft",
    "createdAt": "2026-06-01T10:00:00.000Z",
    "sentAt": "2026-06-01T10:00:05.000Z"
  }
}

Bakiye Sorgula

GET/api/v1/sms/balance

Hesabınızdaki mevcut kredi bakiyesini, günlük limiti ve bugünkü kullanım istatistiklerini döndürür.

Başarılı Yanıt

{
  "success": true,
  "data": {
    "credits": 50000,
    "unlimited": false,
    "dailyLimit": null,
    "today": {
      "smsCount": 1200,
      "creditUsed": 1200,
      "requestCount": 5
    }
  }
}

Yanıt Alanları

Parametre	Tip	Zorunlu	Açıklama
credits	number	Evet	Mevcut kredi bakiyesi
unlimited	boolean	Evet	Sınırsız kredi aktif mi
dailyLimit	number\|null	Evet	Günlük SMS limiti (null = limitsiz)
today.smsCount	number	Evet	Bugün gönderilen toplam SMS
today.creditUsed	number	Evet	Bugün harcanan toplam kredi
today.requestCount	number	Evet	Bugünkü toplam istek sayısı

Kod Örneği — cURL

curl -X GET "https://your-domain.com/api/v1/sms/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hata Kodları

API hata durumlarında aşağıdaki formatta yanıt döner. code alanı programatik kontrol için, message alanı kullanıcıya gösterilebilir mesaj içerir.

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Hata açıklaması"
  }
}

Kod	HTTP	Açıklama	Çözüm
AUTH_REQUIRED	401	API Key gönderilmedi	Authorization header ekleyin
INVALID_KEY	401	Geçersiz API Key	Key doğruluğunu kontrol edin
KEY_EXPIRED	401	API Key süresi dolmuş	Yeni key oluşturun
KEY_DISABLED	401	API Key deaktif edilmiş	Panelden key'i aktif edin
API_DISABLED	403	API erişimi kapalı	Admin ile iletişime geçin
RATE_LIMITED	429	İstek limiti aşıldı	Biraz bekleyin ve tekrar deneyin
INSUFFICIENT_CREDITS	402	Yetersiz kredi	Kredi yükleyin
INVALID_PARAMS	400	Geçersiz parametreler	Request body kontrol edin
IP_BLOCKED	403	IP adresi engellenmiş	Admin ile iletişime geçin
IP_NOT_WHITELISTED	403	IP whitelist'te değil	IP'nizi key ayarlarına ekleyin
PERMISSION_DENIED	403	Yetersiz izin	Key izinlerini kontrol edin
ACCOUNT_LOCKED	403	Hesap kilitlenmiş	Admin ile iletişime geçin
INTERNAL_ERROR	500	Sunucu hatası	Destek ile iletişime geçin

Rate Limiting

API istekleri rate limit ile korunmaktadır. Varsayılan limit API key başına 60 istek/dakika'dır. Bu limit API key oluştururken veya admin tarafından değiştirilebilir.

Limit Türü	Varsayılan	Açıklama
API İstek Limiti	60 req/dk	API key başına dakikada maksimum istek sayısı
SMS Gönderim Limiti	100.000/istek	Tek istekte gönderilebilecek maksimum numara
Günlük SMS Limiti	Admin ayarlar	Kullanıcı bazlı günlük toplam SMS limiti
API Key Sayısı	Max 10	Kullanıcı başına oluşturulabilecek API key sayısı

Rate Limit Aşıldığında

HTTP 429 Too Many Requests yanıtı döner:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit aşıldı. Lütfen biraz bekleyin."
  }
}

💡 IP Whitelist

API key'inize IP whitelist ekleyerek sadece belirli IP adreslerinden erişime izin verebilirsiniz. Bu, güvenliği artırmanın en etkili yollarından biridir. API key oluştururken veya düzenlerken virgülle ayrılmış IP adresleri ekleyebilirsiniz.

GetirSMS API Dokümantasyonu v1.0 — Sorularınız için panelden destek alabilirsiniz.