---
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-04-29
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 |
| [get-report](./get-report.md) | `POST /v1/get-report/json` | Sipariş teslimat raporu (özet + alıcı bazında) |
| [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 |
| [inbox](./inbox.md) | `POST /v1/get-inbox/json` | Gelen SMS listesi |
| [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ı

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 `destek@emarka.com.tr` 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](./send-sms.md) ç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`](https://github.com/iletimerkezi/iletimerkezi-node)
- **Python:** [`iletimerkezi`](https://github.com/iletimerkezi/iletimerkezi-python)
- **PHP:** [`iletimerkezi/sdk`](https://github.com/iletimerkezi/iletimerkezi-php)
- **Go:** [`github.com/iletimerkezi/iletimerkezi-go`](https://github.com/iletimerkezi/iletimerkezi-go)
- **Java:** [`iletimerkezi-java`](https://github.com/iletimerkezi/iletimerkezi-java)
- **C# (.NET):** [`iletimerkezi-csharp`](https://github.com/iletimerkezi/iletimerkezi-csharp)
- **Ruby:** [`iletimerkezi-ruby`](https://github.com/iletimerkezi/iletimerkezi-ruby)
- **Laravel:** [`iletimerkezi-laravel`](https://github.com/iletimerkezi/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](./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. 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](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)