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

| Alan | Değer | |---|---| | Method | POST | | URL | https://api.iletimerkezi.com/v1/send-sms/json | | Content-Type | application/json | | Auth | API Key + Hash (request.authentication) |

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 tarih, format "GG/AA/YYYY SS:DD"
   └─ message
      ├─ text (string, zorunlu)         — SMS metni
      └─ receipents
         └─ number (string[], zorunlu)  — 905xxxxxxxxx, +905xxxxxxxxx, 5xxxxxxxxx kabul edilir

iys alanı her zaman zorunludur. Ticari (kampanya, reklam, tebrik) mesajlar için "1" ve uygun iysList değeri (BIREYSEL ya da TACIR) gönderilmelidir; aksi halde yasal yaptırım uygulanabilir. Bilgilendirme, onay/OTP, abonelik, teslimat gibi mevzuat dışı/transactional mesajlarda "0" gönderilir, iysList yok sayılır.

receipents (sic.) alanı message altındadır, order altında değil. Eski örneklerde order.receipents görülebilir, doğrusu order.message.receipents'tir.

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.

Diğer hata kodları

400, 402, 450, 453, 454, 457, 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. Ticari mesajlarda "1" + iysList zorunlu; aksi halde yasal yaptırım söz konusudur.
  • 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-04-29 · English version