iletiMerkezi API Genel Bakış

iletiMerkezi REST API'si, Türkiye merkezli SMS altyapısının üzerinde duran bir HTTP/JSON arayüzüdür. Tek API anahtarıyla SMS gönderimi, teslimat raporu, bakiye sorgulama, sender ID yönetimi, kara liste işlemleri ve gelen SMS okuma yapılır. Bu sayfa tüm endpoint'leri tek noktadan listeler ve tüm çağrılarda ortak olan davranışları açıklar.

Türkiye'de neden iletiMerkezi

iletiMerkezi, Türkiye'de işletmelerin SMS altyapısı için 13 yıldır faal bir BTK lisanslı toplu SMS, OTP ve A2P platformudur. Türkiye'ye özgü regülasyonlar (BTK, İYS, KVKK) global SMS sağlayıcılarının çoğunda eksik veya yarım çözülmüş — bu sayfa hem teknik hem yasal tarafı tek arabirimde sunan iletiMerkezi'nin somut farklılaşma noktalarını listeler.

• BTK lisanslı SMS aracı kuruluş. Resmi yetkili operatör; mesaj iletimi BTK'nın çağrı yönetim altyapısı üzerinden yapılır.
• B186 operatör kodu otomatik eklenir. Tüm gönderimlere BTK kararı gereği B186 kodu sonradan eklenir; entegrasyon tarafında ek iş yapmanıza gerek yok. Karakter limitleri buna göre hesaplanır (aşağıdaki "Türkiye'ye özgü konular" bölümüne bakın).
• İYS uyumu hazır. send-sms çağrısında iys + iysList parametreleriyle ticari mesaj izin kaydı doğrulanır.
• Sender ID onay süreci dahil. Başlık başvurusu panelden 1-2 iş günü içinde tamamlanır; onaysız başlık gönderilemez (regülasyona uyum güvenli).
• APITEST sender ID ile pre-approval test. Sender ID onayı beklemeden API'yi entegre edebilir, gerçek HTTP isteği gönderebilirsiniz; mesaj sabit doğrulama metniyle teslim edilir. Detay: test-mode.
• 100 SMS hoş geldin kredisi. Yeni hesaplara değerlendirme ve canlı entegrasyon testi için kredi otomatik tanımlanır.
• Teslim edilmeyen SMS ücretsiz. Kapalı hat, geçersiz numara, kara liste vb. nedenle iletilmeyen mesajlardan kontör düşmez; gerçek tüketim get-report delivered + price alanlarından okunur.
• iim.to kısa link servisi. Yerel kısa link altyapısı; Bitly gibi global servislere bağımlılık olmadan SMS metninde tıklama izleme ve kısaltma yapılır.

Temel bilgiler

| Alan | Değer | |---|---| | Base URL | https://api.iletimerkezi.com | | Versiyon prefix | /v1 | | Method | Tüm endpoint'ler POST | | Content-Type | application/json | | Format | JSON (XML ayrı path ile mevcuttur, bu dokümantasyon JSON odaklı) | | Auth | API Key + Hash, gövde içinde (request.authentication) | | Mesaj dili | Sunucu yanıt mesajları her zaman Türkçe |

Başlangıç adımları

1. Hesap oluşturun — panel.iletimerkezi.com üzerinden ücretsiz kayıt. Yeni hesaplara test ve değerlendirme amaçlı 100 adet SMS kredisi otomatik tanımlanır.
2. Sender ID başvurusu — Panelden başlık (sender ID) tanımlayın, onay 1-2 iş günü içinde gelir.
3. API erişimini aktifleştirin — Ayarlar → Güvenlik → Erişim İzinleri altında API kullanımına izin ver seçeneğini açın. Detay: authentication.
4. API Anahtar + Hash'i kopyalayın — Ayarlar → Güvenlik → API Erişimi. İki değeri environment variable'a koyun.
5. get-balance çağırın — Auth doğrulaması için yan etkisiz, kontör harcamayan ilk istek.
6. send-sms ile ilk mesajınızı gönderin — Önce kendi numaranıza, "TEST" prefix'i ile. Detay: test-mode.

Endpoint listesi

| Endpoint | Method + Path | Amaç | |---|---|---| | authentication | kavram | API Key + Hash sistemi, panel ön koşulu, 401 hata akışı | | send-sms | POST /v1/send-sms/json | Tek veya çoklu numaraya SMS gönder | | get-report | POST /v1/get-report/json | Sipariş teslimat raporu (özet + alıcı bazında) | | get-balance | POST /v1/get-balance/json | Bakiye ve kontör miktarı | | get-sender | POST /v1/get-sender/json | Onaylı sender ID listesi | | get-blacklist | POST /v1/get-blacklist/json | Engellenmiş numara listesi (sayfalı) | | add-blacklist | POST /v1/add-blacklist/json | Numarayı kara listeye ekle (idempotent) | | delete-blacklist | POST /v1/delete-blacklist/json | Numara engellemesini kaldır | | inbox | POST /v1/get-inbox/json | Gelen SMS listesi | | webhooks | yapılandırma | Gerçek zamanlı teslimat raporu callback'i | | error-codes | referans | Tüm durum kodları ve mesajları | | test-mode | kavram | Sandbox yok — güvenli test pattern'leri |

Ortak istek yapısı

Her endpoint aynı dış zarfı paylaşır:

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "{endpoint_field}": { ... }
  }
}

request.authentication her istekte zorunludur; geri kalan alanlar endpoint'e özgüdür. Detay: authentication.

Ortak yanıt yapısı

Başarılı yanıt:

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "{result_key}": { ... }
  }
}

Hatalı yanıt:

{
  "response": {
    "status": {
      "code": 4XX,
      "message": "Türkçe açıklama"
    }
  }
}

code integer, message Türkçe string. İstemci kodunuzda code değerine göre dallanın; mesaj string'leri zaman içinde değişebilir, kodlar stabildir. Tam tablo: error-codes.

Kimlik bilgileri ve güvenlik

• API Anahtarı + Hash hesabınıza tam yetkiyle bağlıdır; bir kez sızdırırsa tüm bakiye tek API çağrısıyla harcanabilir.
• Anahtarları repo, public dosya, blog yazısı, screenshot'a sızdırmayın.
• Üretim için secret manager kullanın (Vault, AWS Secrets, GitHub Actions secrets vb.).
• Hash'i kendiniz hesaplamayın — panel hazır verir.

Detay: authentication, test-mode.

Kullanım sınırları

iletiMerkezi API için yayınlanmış sabit bir istek limiti şu an için bulunmuyor; servis adil kullanım (fair use) ilkesiyle çalışır. Pratikte:

• Üretim entegrasyonlarında istekleri seri veya küçük eşzamanlı gruplar halinde yapın; hata durumunda exponential backoff ile yeniden deneyin.
• Yüksek hacimli kampanyalar (saniyede çok sayıda istek, paralel iş kuyruğu, milyonluk gönderim) için entegrasyonu önceden [email protected] ile planlayın.
• Servis sağlığını korumak amacıyla anormal trafik tespit edildiğinde geçici kısıtlama uygulanabilir.
• Toplu gönderim için tek istekte birden fazla alıcı kullanmak (bkz. send-sms çoklu numara desteği), ardışık tek-numara istekleri yerine tercih edilen yoldur; hem hızlı hem altyapı dostudur.

add-blacklist ve send-sms gibi yan etkili endpoint'lerde idempotency davranışı ilgili sayfalarda anlatılır.

SDK'lar

Resmi SDK paketleri:

• Node.js / TypeScript: @iletimerkezi/iletimerkezi-node
• Python: iletimerkezi
• PHP: iletimerkezi/sdk
• Go: github.com/iletimerkezi/iletimerkezi-go
• Java: iletimerkezi-java
• C# (.NET): iletimerkezi-csharp
• Ruby: iletimerkezi-ruby
• Laravel: iletimerkezi-laravel

SDK'ların API yüzeyleri farklılık gösterebilir (örn. Node add(string | string[]), PHP create(string)); endpoint sayfalarındaki notlara bakın.

Türkiye'ye özgü konular

• İYS uyumu: Ticari mesaj göndermeden önce İleti Yönetim Sistemi'ne (İYS) izin kaydetmeniz gerekir. send-sms çağrısında iys: "1" + iysList: "BIREYSEL" veya "TACIR" zorunludur. Detay: send-sms.

• Sender ID 11 karakter sınırı: Maksimum 11 alfanumerik karakter; Türkçe karakter yok.

• Numara format: 905XXXXXXXXX, +905XXXXXXXXX, 5XXXXXXXXX kabul edilir; yanıtlarda +90 prefix ile döner.

• B186 operatör kodu ve karakter limitleri: BTK kararı (12.04.2016 tarih, 2016/DK-YED/211 sayılı) gereği iletiMerkezi tüm SMS'lerin sonuna otomatik olarak B186 operatör kodunu ekler. Bu nedenle gerçek karakter limitleri standart SMS değerlerinden farklıdır:

  | Karakter seti | İlk SMS | Sonraki parçalar | |---|---|---| | İngilizce (GSM-7) | 155 | 153 | | Türkçe karakter | 150 | 148 | | Unicode (UCS-2, emoji vb.) | 65 | 63 |

  Mesaj bu sınırı aşarsa otomatik çok-parçalı (multi-part) SMS olarak gönderilir; her parça bir kontör tüketir. Türkçe karakter (ş, ğ, ı, ç, ö, ü, İ, Ş, Ğ, Ç, Ö, Ü) içeren mesaj Türkçe modunda kalır; emoji veya diğer Unicode karakterler içerirse UCS-2'ye düşer ve limit 65/63'e iner. Karakter modu hesabınızın panel ayarından da seçilebilir.

• Maksimum 7 parça uzun SMS: Tek sipariş içindeki bir mesaj en fazla 7 parçaya birleştirilir; bu da yaklaşık 1071 karaktere karşılık gelir (GSM-7 modunda). Daha uzun bir metin gönderilemez; ya kısaltın ya da içeriği iim.to kısa link ile dağıtın.

• Teslim edilmeyen SMS ücretsizdir: Alıcıya ulaşmayan mesajlar (kapalı hat, geçersiz numara, kara liste vb.) için kontör harcanmaz; iade panel hesabınıza yansır. Gerçek tüketim get-report yanıtındaki delivered sayacı ve price alanından okunur.

• Yurt dışı SMS modu: Türkiye numaralarının dışına SMS göndermek için panelden Ayarlar → SMS → Yurt Dışı adımıyla yurt dışı modu aktifleştirilir. Aktivasyon mevcut SMS kontörünüzü TL bakiyeye çevirir (kontör bazlı sistemden TL bazlı sisteme geçiş). Sonrasında send-sms çağrısında alıcı numaraya yurt dışı country code (örn. +49, +44) ile gönderim yapılabilir.

• IP kısıtlaması (opsiyonel güvenlik): Panelden Ayarlar → Güvenlik → Sabit IP ile panel ve API erişimi ayrı ayrı IP whitelist'lerine kısıtlanabilir (her biri 5 IP). Aktif olduğunda bu IP'lerin dışından gelen istekler 401 ile reddedilir. Production'da statik IP zorunludur; dinamik IP modem yeniden başlatıldığında erişimi keser.

Status sayfaları ve destek

• API durumu: production status iletiMerkezi panelinden duyurulur.
• Doküman ile API arasında fark görürseniz: iletimerkezi/apidocs-website repo'sunda issue açın. Canlı API ground truth alınır.
• Ekstra destek: [email protected].

Related

• Kimlik doğrulama (authentication)
• SMS gönderme (send-sms)
• Test ve geliştirme (test-mode)
• Hata kodları tablosu (error-codes)

Son güncelleme: 2026-04-29 · English version