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

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

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ı

send-sms endpoint'i için iki ayrı sınır vardır:

• Anlık (transactional) gönderim: Hesap bazında saniyede 100 SMS'e kadar. Tipik kullanım: OTP, giriş kodu, sipariş/teslimat bildirimi, randevu hatırlatma; kullanıcı başına tetiklenen, tek-tek mesajlar.
• Toplu (bulk) gönderim: Tek istekte 50.000 alıcıya kadar (order.message.receipents.number dizisi). Tipik kullanım: kampanya, duyuru, kitle bildirimi. Tek sipariş tek orderId altında izlenir.

Pratik kurallar:

• 50.000'in üzerindeki alıcı listelerini istemcide parçalayın (chunkSize=50000) ve ardışık send-sms çağrıları yapın; her çağrı ayrı bir orderId üretir.
• Sürekli olarak saniyede 100 transactional SMS'i aşan ihtiyaçlar için entegrasyonu önceden [email protected] ile planlayın; özel kapasite tahsis edilebilir.
• Üretim entegrasyonlarında hatalar için exponential backoff kullanın; servis sağlığını korumak amacıyla anormal trafik geçici kısıtlanabilir.
• Toplu gönderim için tek istekte birden fazla alıcı kullanmak, ardışık tek-numara istekleri yerine tercih edilen yoldur; hem hızlı hem altyapı dostudur.

Diğer endpoint'ler (rapor, bakiye, kara liste, İYS sorgu) için yayınlanmış sabit istek limiti yoktur; adil kullanım (fair use) ilkesi geçerlidir. add-blacklist ve send-sms gibi yan etkili endpoint'lerde idempotency davranışı ilgili sayfalarda anlatılır.

SDK'lar

Paket registry'lerinde yayında olan resmi SDK'lar:

• Node.js / TypeScript: npm @iletimerkezi/iletimerkezi-node (npm, GitHub)
• PHP: Packagist iletimerkezi/iletimerkezi-php (Packagist, GitHub)

Diğer diller için (Python, Go, Java, C#, Ruby, Laravel) GitHub'da kaynak kod mevcuttur ancak henüz paket registry yayını yoktur, entegrasyon için doğrudan REST API kullanın veya iletişime geçin: [email protected].

LLM tabanlı geliştirme akışları için: MCP server (@iletimerkezi/mcp-server) Claude Code, Cursor, Gemini CLI gibi istemcilerden 11 SMS aracını tek konuşmadan yönetir. Detay: /docs/mcp.

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.

  Karakter modu hesap düzeyinde panelden ayarlanır. Default mod İngilizce (GSM-7)'dir; Türkçe karakter veya Unicode (emoji, diğer alfabeler) gönderebilmek için önce panelden Evrensel Dil Desteği'nin ilgili modunu aktive etmeniz gerekir: panel.iletimerkezi.com/settings/sms/encoding. Ayar yapılmadan Türkçe veya Unicode karakter içeren mesaj gönderildiğinde karakter dönüşümü uygulanır (ör. ş > s, emoji düşer). Ayar etkinleştirildikten sonra mesaj içeriği otomatik olarak ilgili moda yerleşir: yalnızca Türkçe karakter varsa Türkçe moduna (150/148), emoji veya diğer Unicode varsa UCS-2'ye (65/63).

• 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-05-05 · English version