Ana içeriğe geç

SMS Gönderme API (send-sms)

send-sms endpoint'i tek bir istekle bir veya birden çok cep telefonuna SMS gönderir. İstek bir sipariş (order) olarak kabul edilir; başarılı yanıtta dönen orderId ile teslimat raporlarını takip edebilir, ileri tarihli siparişleri iptal edebilirsiniz. İstek başına yalnızca bir sipariş, sipariş başına bir sender (başlık) gönderilir.

Önemli ön koşul: Panel'de API erişimi

Bu endpoint'i çağırmadan önce panelinizde API kullanımına izin ver seçeneğinin aktif olması gerekir.

Ayar yeri: panel.iletimerkezi.com > Ayarlar > Güvenlik > Erişim İzinleri

Aktif değilse istek 401: Üyelik bilgileri hatalı ile döner. Detay: authentication.md

Endpoint

AlanDeğer
MethodPOST
URLhttps://api.iletimerkezi.com/v1/send-sms/json
Content-Typeapplication/json
AuthAPI Key + Hash (request.authentication)

Hız sınırları

send-sms endpoint'i iki farklı kullanım pattern'ini destekler ve her birinin ayrı bir sınırı vardır:

  • Anlık (transactional) gönderim: Hesap bazında saniyede 100 SMS'e kadar. OTP, giriş kodu, sipariş/teslimat bildirimi, randevu hatırlatma gibi kullanıcı başına tetiklenen ve gecikmeye duyarlı mesajlar için. Her tetiklemede ayrı istek atın; istek başına genellikle 1 alıcı. Sınır toplam SMS sayısı (alıcı) üzerindendir, istek sayısı değil: 5 alıcılı bir istek 5 SMS sayılır, dolayısıyla 5 alıcılı istek atıyorsanız saniyede en fazla 20 istek hedefleyin.
  • Toplu (bulk) gönderim: Tek istekte 50.000 alıcıya kadar (order.message.receipents.number dizisi). Kampanya, duyuru, kitle bildirimi için. Tek orderId altında tek sipariş açılır; teslimat raporu get-report ile alınır.

Daha büyük hacim gerekiyorsa:

  • 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 hata akışlarında exponential backoff kullanın; servis sağlığını korumak amacıyla anormal trafik geçici kısıtlanabilir.

Request

Şema

request
├─ authentication
│  ├─ key (string, zorunlu)
│  └─ hash (string, zorunlu)
└─ order
   ├─ sender (string, zorunlu), panelde onaylı sender ID, max 11 karakter
   ├─ iys (string, zorunlu), "1" veya "0"
   ├─ iysList (string, koşullu), iys=1 ise "BIREYSEL" veya "TACIR"
   ├─ sendDateTime (string, opsiyonel), ileri tarihli gönderim zamanı, format "dd/MM/yyyy HH:mm" (Türkiye yerel saati)
   └─ message
      ├─ text (string, zorunlu), SMS metni
      └─ receipents
         └─ number (string[], zorunlu), 905xxxxxxxxx, +905xxxxxxxxx, 5xxxxxxxxx kabul edilir

iys alanı her zaman zorunludur. Karar kuralı: mesajın amacı bir ürün veya hizmeti pazarlamak ise "1" (kampanya, promosyon, indirim, tebrik, anket); diğer her şey "0" (OTP, giriş kodu, şifre sıfırlama, sipariş/teslimat/ödeme bildirimi, randevu hatırlatma, hesap güncelleme, mevzuat tebliği). Transactional mesajlar 6563 sayılı Elektronik Ticaretin Düzenlenmesi Hakkında Kanun ve İYS uygulama kuralları çerçevesinde ticari elektronik ileti kapsamı dışındadır; önceden onay aranmaz (iys.org.tr/sss) ve iysList o durumda yok sayılır. KVKK kapsamındaki kişisel veri işleme yükümlülükleri ayrıca devam eder. Ticari mesajlarda iysList zorunlu (BIREYSEL veya TACIR); aksi halde yasal yaptırım söz konusudur. Sender "APITEST" ise iys her zaman "0" (test mode, mesaj metni sabit doğrulama metniyle değiştirilir).

Alan adı yazımı: Alan adı API'de geriye dönük uyumluluk için receipents (sic.) olarak korunur. recipients yazımı çalışmaz, otomatik düzeltilmez; doğru yazım recipients sanılarak gönderilirse alıcı listesi okunamaz ve 452 döner. Ayrıca alan message altındadır, order altında değil, eski örneklerde order.receipents görülebilir, doğrusu order.message.receipents'tir.

Yasal sorumluluk: API'nın bazı sürümlerinde iys ve iysList alanları gönderilmediğinde de istek 200 ile sonuçlanıp mesaj iletilebiliyor. Bu API tarafındaki bir tolerans; yasal yükümlülüğü kaldırmaz. Ticari içerik gönderirken iys: "1" ve uygun iysList (BIREYSEL veya TACIR) değerini her durumda gönderin, backend gerçek-zamanlı İYS sorgusu yapar ve izinsiz alıcıları düşürür. Bu alanları atlayarak ticari SMS göndermek 6563 sayılı kanun kapsamında alıcı başına idari para cezasına yol açar; sorumluluk send eden taraftadır.

Tam örnek

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "order": {
      "sender": "BASLIGINIZ",
      "iys": "0",
      "message": {
        "text": "Sipariş #1234 hazırlandı, kargoya verildi.",
        "receipents": {
          "number": ["905XXXXXXXXX"]
        }
      }
    }
  }
}

Birden fazla alıcı için aynı number dizisine ekleyin:

"receipents": {
  "number": ["905XXXXXXXXX", "905YYYYYYYYY", "905ZZZZZZZZZ"]
}

Response

Başarılı (200)

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "order": {
      "id": "312891245"
    }
  }
}

Alanlar:

  • response.status.code (integer): HTTP durum koduna paralel iç durum kodu
  • response.status.message (string): Türkçe açıklama
  • response.order.id (string): Siparişe atanan eşsiz numerik ID. Teslimat raporu (get-report) ve ileri tarih siparişlerinin iptali için bu ID kullanılır.

Hata yanıtları

401: Üyelik bilgileri hatalı

API Anahtar/Hash doğrulanamadı veya panel toggle kapalı. Detay: authentication.md.

451: Tekrar eden sipariş

Aynı sender + alıcı + mesaj metni kombinasyonu kısa süre içinde yeniden gönderildi (idempotency koruması). Mesaj metnini değiştirin veya bir önceki siparişin durumunu get-report ile kontrol edin.

452: Mesaj alıcıları hatalı

receipents.number boş, geçersiz formatta veya alanı tamamen eksik. En yaygın sebep: receipents'in yanlış yere (order.receipents gibi) yerleştirilmiş olması. Doğru konum: order.message.receipents.

466: Hatalı numara

receipents.number içindeki bir veya daha fazla numara geçerli format dışında (Türkiye operatör prefix'i 5XX değil veya hane sayısı uyumsuz). Numara format'ları: 905XXXXXXXXX, +905XXXXXXXXX, 5XXXXXXXXX. Yurt dışı numara için panelden Yurt Dışı modunu aktive edin.

Diğer hata kodları

400, 402, 450, 453, 454, 457, 466, 468, 469, 470 kodları için tam tablo: error-codes.md.

Kod örnekleri

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/send-sms/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "order": {
        "sender": "BASLIGINIZ",
        "iys": "0",
        "message": {
          "text": "Sipariş hazırlandı, kargoya verildi.",
          "receipents": { "number": ["905XXXXXXXXX"] }
        }
      }
    }
  }'

Common Pitfalls

  • receipents yerini şaşırma. Pattern order.message.receipents.number[]'dir, order.receipents değil. Eski örneklerde yanlış yer görülür; 452 alıyorsanız ilk kontrol edilecek nokta budur.
  • iys zorunlu, default'u yok. Alanı atlarsanız istek geçmez. Karar kuralı tek cümle: mesajın amacı ürün/hizmet pazarlamak ise "1" + iysList; diğer her şey (OTP, bildirim, hatırlatma, hesap işlemi, mevzuat tebliği) "0". Transactional mesajlar 6563 sayılı Elektronik Ticaret Kanunu kapsamında ticari ileti sayılmaz; önceden ticari onay aranmaz. KVKK kişisel veri yükümlülükleri ayrıca devam eder. APITEST sender kullanıyorsan iys = "0" zorunlu.
  • Sender panelde onaylı olmalı. eMarka Test gibi başlıklar panel onayı gerektirir; onaylı listeyi get-sender endpoint'i ile çekebilirsiniz. Onayı beklerken sender değerini "APITEST" yaparak HTTP entegrasyonunu test edebilirsiniz (mesaj metni sabit bir test metniyle değiştirilir, akış tam çalışır). Detay: test-mode.
  • Tekrar eden siparişe dikkat. Aynı sender + numara + text kısa zaman aralığında gönderilirse 451 döner. İdempotent kullanımda mesaj sonuna unique bir referans (sipariş ID, timestamp) ekleyin.
  • Numara formatı esnek ama tutarlı kullanın. 905XXXXXXXXX, +905XXXXXXXXX, 5XXXXXXXXX kabul edilir. Tek bir formatta kalmak hata ayıklamayı kolaylaştırır; tercihen 905XXXXXXXXX (12 hane).
  • Yurt dışı numara için yurt dışı modu gerekir. Türkiye dışı country code (+49, +44 vb.) ile gönderim yapmak için panelden Ayarlar > SMS > Yurt Dışı modunu aktifleştirin. Aktivasyon kontör bakiyesini TL bakiyeye çevirir; sonra bu modda kalırsınız. Detay: overview.
  • Bakiyeyi öncesi/sonrası karşılaştırın. Test ortamında get-balance ile her gönderim öncesi ve sonrası bakiyeyi loglayın. Mesaj uzunluğu (eMarka karakter limitleri B186 prefix sebebiyle: İngilizce 155/153, Türkçe 150/148, Unicode 65/63), karakter modu (sendDateTime ile ileri tarihli sipariş, çok-parçalı mesaj) gibi etkenler kontör tüketimini etkiler. Detay: overview.
  • Maksimum 7 parça / ~1071 karakter. Tek mesaj 7 parçayı geçemez. Daha uzun içerik ya kısaltılmalı ya da iim.to kısa link ile dağıtılmalı.
  • Teslim edilmeyen SMS ücretsizdir. Kapalı hat, geçersiz numara veya kara liste sebebiyle teslim edilmeyen mesajlar için kontör harcanmaz. get-report delivered ve price alanlarından gerçek tüketim okunur.
  • Sender ID 11 karakter sınırı. Maksimum 11 karakter; alfanumerik. Boşluk hesaba katılır.
  • Mesaj metni karakter ekonomisi. Uzun URL'leri ham olarak yapıştırırsanız ilk SMS karakter sınırına (155 / 150 / 65) hızla çarparsınız. iletiMerkezi panelinden iim.to/... kısa linki oluşturup mesaja yapıştırın; tıklama raporları ve otomatik çıkış (opt-out) akışı da bu link üzerinden işler. Kısa link şu an panelden yönetilir, ayrı API endpoint'i yoktur.

Related

Son güncelleme: 2026-05-05 · English version