Etesio SMS API v1

Yazılımınızdan tek bir HTTPS çağrısıyla SMS gönderin, teslim durumunu sorgulayın. Bütün istek ve cevaplar düz JSON; kodlama, sarmalama yok.

Başlangıç

Hesap oluşturun ve gönderen başlığınızı onaylatın.
Panelde API Erişimi sayfasından bir anahtar oluşturun. Anahtar yalnız oluşturulduğu anda görünür.
Aşağıdaki uçları https://sms.etesio.com/api/v1 köküne çağırın.

Kimlik doğrulama

Her isteğe anahtarınızı Authorization başlığıyla ekleyin. Anahtarı panelden IP adresine kısıtlayabilirsiniz.

Authorization: Bearer ets_3f9c…
Content-Type: application/json

Dakikada anahtar başına 120 istek. Aşımda 429 ORAN_SINIRI döner.

POST/api/v1/gonder

Aynı metni birçok numaraya (toplu) ya da her numaraya ayrı metni (kişiye özel) gönderir.

Alan	Tip	Açıklama
`baslik`	string	Onaylı gönderen başlığınız (3–11 karakter). Zorunlu.
`mesaj`	string	Toplu gönderimde ortak metin. En fazla 10 parça.
`numaralar`	string[]	Toplu gönderimde alıcılar. `5550000001`, `05550000001`, `+90 555 000 00 01` biçimleri kabul edilir. En fazla 50.000.
`mesajlar`	{numara, mesaj}[]	Kişiye özel gönderim; `mesaj` + `numaralar` yerine kullanılır.
`turkce`	boolean	Varsayılan `true`: Türkçe karakterler korunur, tek parça 155 karakter. `false`: ş→s, ğ→g çevrilir, tek parça 160.
`zamanlama`	ISO 8601	İleri tarihli gönderim, örn. `2026-09-10T09:00:00+03:00`.

{ "baslik": "ORNEKFIRMA",
  "mesaj": "Siparişiniz kargoya verildi. Takip: 123456",
  "numaralar": ["5550000001", "0555 000 00 02"] }

→ 201
{ "id": 42, "durum": "gonderildi", "baslik": "ORNEKFIRMA", "parametrik": false,
  "aliciSayisi": 2, "gecersiz": 0, "karaliste": 0, "dusulenKredi": 2, "iadeKredi": 0,
  "iletilen": 0, "iletilmeyen": 0, "bekleyen": 2,
  "gonderimTarihi": "2026-09-08T10:12:33.751Z", "olusturmaTarihi": "…" }

Kişiye özel:

{ "baslik": "ORNEKFIRMA",
  "mesajlar": [
    { "numara": "5550000001", "mesaj": "Sayın Ali, doğrulama kodunuz 482913" },
    { "numara": "5550000002", "mesaj": "Sayın Ayşe, doğrulama kodunuz 771204" } ] }

Karalistenizdeki numaralar ve geçersiz numaralar gönderilmeden elenir, kredi düşmez. Kredi, gönderim anında düşer; ulaşmayan alıcıların kredisi rapor kesinleşince (en geç 24 saat) iade edilir. Düzenleme gereği her mesajın sonuna kısa bir izin/ret kodu eklenir ve karakter sayısına dahildir.

GET/api/v1/gonderim/{id}

Gönderimin güncel özeti; yukarıdaki cevapla aynı şekil. Durumlar: kuyrukta (zamanlanmış), gonderildi, basarisiz, iptal.

GET/api/v1/gonderim/{id}/alicilar

{ "gonderim": 42, "alicilar": [
  { "numara": "5550000001", "durum": "iletildi", "parca": 1, "iletim_tarihi": "2026-09-08T10:12:58.000Z", "hata": null },
  { "numara": "5550000002", "durum": "bekliyor",  "parca": 1, "iletim_tarihi": null, "hata": null } ] }

Alıcı durumları: bekliyor, iletildi, iletilmedi, karaliste. Rapor 1, 5, 30, 180 dakika ve 24 saatte güncellenir.

GET/api/v1/gonderimler?sayfa=1&adet=50

Son gönderimler, yeniden eskiye.

GET/api/v1/bakiye · GET/api/v1/basliklar

{ "musteri": "ETS-SMS-0002", "bakiye": 4820 }
{ "basliklar": ["ORNEKFIRMA", "ORNEK"] }

POST/api/v1/uzunluk

Anahtar gerektirmez. Metnin kaç parça tutacağını söyler.

{ "mesaj": "Merhaba dünya", "turkce": true }
→ { "kodlama": "turkce", "uzunluk": 18, "parca": 1, "kalan": 137 }

Karaliste

Uç	Gövde	Cevap
POST/api/v1/karaliste	`{ "numaralar": ["…"] }`	`{ "eklenen": 3, "gecersiz": [] }`
DELETE/api/v1/karaliste	`{ "numaralar": ["…"] }`	`{ "silinen": 1 }`
POST/api/v1/karaliste/sorgu	`{ "numaralar": ["…"] }`	`{ "karalistede": [...], "temiz": [...] }`

Hatalar

Hata cevabı her zaman { "hata": "...", "hataKodu": "..." } ve anlamlı HTTP kodu.

HTTP	hataKodu	Anlamı
400	DOGRULAMA_HATASI	Alan eksik ya da geçersiz; `detaylar` dizisi alanı söyler
401	YETKILENDIRME_HATASI	Anahtar yok ya da geçersiz
402	YETERSIZ_KREDI	`gereken` ve `bakiye` alanlarıyla
403	YETKI_HATASI	IP izinli değil ya da hesap aktif değil
404	BULUNAMADI_HATASI	Gönderim bulunamadı
422	ALICI_YOK	Bütün numaralar elendi
429	ORAN_SINIRI	Dakikada 120 istek aşıldı

Kod örnekleri

cURL

curl -X POST https://sms.etesio.com/api/v1/gonder \
  -H "Authorization: Bearer ets_…" -H "Content-Type: application/json" \
  -d '{"baslik":"ORNEKFIRMA","mesaj":"Merhaba","numaralar":["5550000001"]}'

PHP

$ch = curl_init('https://sms.etesio.com/api/v1/gonder');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ets_…', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['baslik' => 'ORNEKFIRMA', 'mesaj' => 'Merhaba', 'numaralar' => ['5550000001']], JSON_UNESCAPED_UNICODE),
]);
$cevap = json_decode(curl_exec($ch), true);
if (($cevap['durum'] ?? '') !== 'gonderildi') { /* hata: $cevap['hata'] */ }

Node.js

const cevap = await fetch('https://sms.etesio.com/api/v1/gonder', {
  method: 'POST',
  headers: { Authorization: 'Bearer ets_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ baslik: 'ORNEKFIRMA', mesaj: 'Merhaba', numaralar: ['5550000001'] }),
});
const veri = await cevap.json();   // veri.id, veri.durum, veri.dusulenKredi

Python

import requests
r = requests.post('https://sms.etesio.com/api/v1/gonder',
    headers={'Authorization': 'Bearer ets_…'},
    json={'baslik': 'ORNEKFIRMA', 'mesaj': 'Merhaba', 'numaralar': ['5550000001']})
print(r.status_code, r.json())

C#

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ets_…");
var govde = new StringContent("{\"baslik\":\"ORNEKFIRMA\",\"mesaj\":\"Merhaba\",\"numaralar\":[\"5550000001\"]}", Encoding.UTF8, "application/json");
var cevap = await http.PostAsync("https://sms.etesio.com/api/v1/gonder", govde);
Console.WriteLine(await cevap.Content.ReadAsStringAsync());