--- title: "iletiMerkezi API Genel Bakış" description: "iletiMerkezi REST API'sinin tüm endpoint'leri, ortak istek/yanıt yapısı, kimlik doğrulama, kullanım sınırları ve başlangıç adımları." slug: /docs/api/overview locale: tr audience: developer last_updated: 2026-05-05 auth: api-key-and-hash related: [authentication, send-sms, get-report, error-codes, test-mode] alternates: tr: https://www.iletimerkezi.com/docs/api/overview en: https://www.iletimerkezi.com/en/docs/api/overview toplusmsapi: https://toplusmsapi.com a2psmsapi: https://a2psmsapi.com/en --- # 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](./test-mode.md). - **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`](./get-report.md) `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](./authentication.md). 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](./test-mode.md). ## Endpoint listesi | Endpoint | Method + Path | Amaç | |---|---|---| | [authentication](./authentication.md) | _kavram_ | API Key + Hash sistemi, panel ön koşulu, 401 hata akışı | | [send-sms](./send-sms.md) | `POST /v1/send-sms/json` | Tek veya çoklu numaraya SMS gönder | | [cancel-order](./cancel-order.md) | `POST /v1/cancel-order/json` | İleri tarihli siparişi operatöre verilmeden iptal et | | [get-report](./get-report.md) | `POST /v1/get-report/json` | Tek sipariş teslimat raporu (özet + alıcı bazında) | | [get-reports](./get-reports.md) | `POST /v1/get-reports/json` | Tarih aralığında sipariş özet listesi (mesaj bazında detay yok) | | [get-balance](./get-balance.md) | `POST /v1/get-balance/json` | Bakiye ve kontör miktarı | | [get-sender](./get-sender.md) | `POST /v1/get-sender/json` | Onaylı sender ID listesi | | [get-blacklist](./get-blacklist.md) | `POST /v1/get-blacklist/json` | Engellenmiş numara listesi (sayfalı) | | [add-blacklist](./add-blacklist.md) | `POST /v1/add-blacklist/json` | Numarayı kara listeye ekle (idempotent) | | [delete-blacklist](./delete-blacklist.md) | `POST /v1/delete-blacklist/json` | Numara engellemesini kaldır | | [iys-register](./iys-register.md) | `POST /v1/consent/create/json` | İYS izin kaydı (tek istekte 1-5000) | | [iys-check](./iys-check.md) | `POST /v1/consent/show/json` | İYS izin durumu sorgulama (tekil) | | [webhooks](./webhooks.md) | _yapılandırma_ | Gerçek zamanlı teslimat raporu callback'i | | [error-codes](./error-codes.md) | _referans_ | Tüm durum kodları ve mesajları | | [test-mode](./test-mode.md) | _kavram_ | Sandbox yok, güvenli test pattern'leri | ## Ortak istek yapısı Her endpoint aynı dış zarfı paylaşır: ```json { "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](./authentication.md). ## Ortak yanıt yapısı Başarılı yanıt: ```json { "response": { "status": { "code": 200, "message": "İşlem başarılı" }, "{result_key}": { ... } } } ``` Hatalı yanıt: ```json { "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](./error-codes.md). ## 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](./authentication.md), [test-mode](./test-mode.md). ## Kullanım sınırları [`send-sms`](./send-sms.md) 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`](./send-sms.md) ç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 `destek@emarka.com.tr` 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](https://www.npmjs.com/package/@iletimerkezi/iletimerkezi-node), [GitHub](https://github.com/iletimerkezi/iletimerkezi-node)) - **PHP:** Packagist `iletimerkezi/iletimerkezi-php` ([Packagist](https://packagist.org/packages/iletimerkezi/iletimerkezi-php), [GitHub](https://github.com/iletimerkezi/iletimerkezi-php)) 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: `destek@emarka.com.tr`. 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](/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](./send-sms.md). - **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`](https://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](https://www.iletimerkezi.com/kisa-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`](./get-report.md) 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`](https://github.com/iletimerkezi/apidocs-website/issues) repo'sunda issue açın. Canlı API ground truth alınır. - Ekstra destek: `destek@emarka.com.tr`. ## Related - [Kimlik doğrulama (authentication)](./authentication.md) - [SMS gönderme (send-sms)](./send-sms.md) - [Test ve geliştirme (test-mode)](./test-mode.md) - [Hata kodları tablosu (error-codes)](./error-codes.md)