JSON Post API

Kısa numaranıza gelen mesajların listesini, HTTP protokolünün POST metodunu kullanarak, JSON formatında almak için, aşağıdaki yönergeleri takip edebilirsiniz.

Alıcılarınıza çıkış (opt-out) kanalı sunabilmeniz için ortak bir kısa numara (7889) kullanılır. Alıcı, bu numaraya EMARKA RET biçiminde bir mesaj gönderir. Mesajdaki EMARKA ifadesi anahtar kelimenizdir ve mesajın hangi müşteriye ait olduğunu belirler; RET ifadesi ise komuttur ve ne yapılacağını belirler. Komutlarınızı iletiMerkezi panelinizden tanımlayabilirsiniz.

Herhangi bir komut tanımlanmamışsa veya alıcının yazdığı kelime tanımlı komutlarınızdan biri değilse varsayılan olarak çıkış senaryosu çalışır: numara engelli numara listenize eklenir ve alıcıya onay SMS'i gönderilir. Bir kelimeyi panelden "sadece kaydet" (RECORD_ONLY) olarak tanımlarsanız, o kelimede çıkış işlemi yapılmaz, mesaj yalnızca kaydedilir.

Anahtar kelimenin mesajın başında yer alması gerekmez; mesajın herhangi bir yerinde geçmesi yeterlidir. Kısa numaraya gelen her mesaj, komuttan bağımsız olarak hesabınıza 0,80 TL olarak faturalanır. Bu uç, kısa numaraya gelen mesajları kendi sisteminize aktarmanızı sağlar.

İstek yapılacak adres

POSThttps://api.iletimerkezi.com/v1/get-inbox/json

Dikkat

Adresteki format eki, gönderdiğiniz isteğin gövde biçimiyle eşleşmelidir. JSON gövde gönderiyorsanız adresin sonundaki /json ekini mutlaka kullanın. Bu ek olmadan JSON gönderirseniz sunucu gövdeyi XML olarak çözümlemeye çalışır, ayrıştıramaz ve isteğinizi 401 ile reddeder.

İstek İçeriği (Body)

{
  "request": {
    "authentication": {
      "key": "",
      "hash": ""
    },
    "inbox": {
      "page": "",
      "rowCount": "",
      "filter": {
        "start": "",
        "end": "",
        "gsm": ""
      }
    }
  }
}

Tanımlar

Sunucuya yapılacak olan istek request etiketi ile sarmalanmalıdır. Bu etiketin alt etiketlerinin tanımları aşağıdaki gibidir:

authentication

İstek yapılan işleme dair yetki alabilmek için gönderilmesi gereken kullanıcı bilgileridir. Alt etiketleri aşağıdaki gibidir:

key: iletimerkezi.com panelinize giriş yaptıktan sonra ayarlar bölümünden oluşturabileceğiniz API Anahtar bu alana yazılmalıdır. İstek yapılırken gönderilmesi zorunludur.
hash: iletimerkezi.com panelinize giriş yaptıktan sonra ayarlar bölümünden oluşturabileceğiniz API Anahtar ve Gizli Anahtar kullanılarak oluşturulmuş hash bu alana yazılmalıdır. İstek yapılırken gönderilmesi zorunludur.

inbox

Gelen mesaj listesi için gerekli olan sayfalandırma ve filtre parametrelerini içerir.

page: Sonuç sayfasını ifade eder. İstek yapılırken gönderilmesi zorunlu değildir. Varsayılan değeri 1'dir. En az 1 olmalıdır.
rowCount: Bir sonuç sayfasındaki mesaj adedini belirtir. İstek yapılırken gönderilmesi zorunlu değildir. Varsayılan değeri 30'dur. 1 ile 1000 arasında bir değer olmalıdır; 1000'den büyük bir değer gönderirseniz 1000'e sabitlenir. Daha fazla kayıt varsa page etiketindeki değer arttırılarak yeni bir istek yapılmalıdır.
filter: Sonuçları filtrelemek için kullanılır. İstek yapılırken gönderilmesi zorunlu değildir.
- start: Listelenecek mesajların başlangıç tarihini ifade eder. Y-m-d H:i:s (2026-08-01 00:00:00) formatında olmalıdır. end etiketi ile birlikte gönderilmelidir.
- end: Listelenecek mesajların bitiş tarihini ifade eder. Y-m-d H:i:s (2026-08-17 23:59:59) formatında olmalıdır. start etiketi ile birlikte gönderilmelidir ve start değerinden küçük olamaz.
- gsm: Sonuçları tek bir gönderici numarasına göre filtreler. İstek yapılırken gönderilmesi zorunlu değildir. Serbest biçimde gönderilebilir (05354101234, +905354101234).

Not

start ve end etiketleri birlikte gönderilmelidir. Yalnızca biri gönderilirse istek 458 hatası ile reddedilir. İkisi de gönderilmezse tarih filtresi uygulanmaz.

Sunucu yanıtı

{
  "response": {
    "status": {
      "code": "",
      "message": ""
    },
    "inbox": {
      "count": "",
      "messages": [
        {
          "id": "",
          "shortCode": "",
          "from": "",
          "keyword": "",
          "command": "",
          "action": "",
          "message": "",
          "price": "",
          "receivedAt": ""
        }
      ]
    }
  }
}

Tanımlar

Sunucudan gelen yanıt her zaman response etiketi ile sarmalanmıştır. Bu etiketin alt etiketlerinin tanımı aşağıdaki gibidir:

status

İşlem durumu ile ilgili bilgi içerir. Bu etiket ile döndürülen değerler aynı zamanda HTTP yanıtının başlık bilgisine bakılarak da elde edilebilir. Bu etiket, yapılan her istekte standart olarak döndürülür. Alt etiketleri aşağıdaki gibidir

code: İşlem durumunu belirten numerik değerdir.
message: İşlem durumu hakkında bilgi mesajı içerir.

inbox

Kısa numaranıza gelen mesajların listesini ifade eder. Alt etiketleri aşağıdaki gibidir.

count: Filtrenize uyan toplam kayıt sayısını ifade eder. Sorguladığınız sayfadaki kayıt sayısı değildir.

messages: Gelen mesaj kayıtlarını içeren listedir. Sorgulanan sayfadaki mesaj sayısı kadar eleman içerir.

messages

id: Mesaj kaydını ifade eden eşsiz değerdir.
shortCode: Mesajın gönderildiği kısa numaradır (7889).
from: Mesajı gönderen alıcının cep telefonu numarasıdır. E.164 biçiminde (+905354101234) döner.
keyword: Mesajda eşleşen anahtar kelimedir (örneğin EMARKA).
command: Mesajda eşleşen komuttur (örneğin BILGI). Herhangi bir komut eşleşmediyse null döner. Boş metin ("") değil, null döndüğü için istemci tarafında bu alanı kontrol ederken null denetimi yapmalısınız.

action: Mesaj için çalışan senaryoyu belirtir. Alabileceği değerler aşağıdaki gibidir:

Değer	Açıklama
UNSUBSCRIBE	Çıkış senaryosu çalışmıştır. Numara engelli numara listenize eklenmiş ve alıcıya onay SMS'i gönderilmiştir.
RECORD_ONLY	Yalnızca kayıt senaryosu çalışmıştır. Mesaj kaydedilmiş, çıkış işlemi yapılmamıştır.

message: Alıcının gönderdiği mesajın tam metnidir.
price: Bu mesaj için hesabınızdan kesilen ücrettir. Ondalık sayı olarak döner (0.8). Bakiyeniz yetersizse 0 döner.
receivedAt: Mesajın alındığı tarih ve saat bilgisidir. Y-m-d H:i:s (2026-08-16 20:20:20) formatında döner.

Not

command ve action alanları, bu özellik devreye alınmadan önce kaydedilmiş eski mesajlarda boş döner.

Hata Kodları

Eğer istek sonucu olumsuz ise sunucu tarafından size dönücek hata kodları ve mesajlar aşağıdaki gibidir.

Hata Kodu	Mesaj	Açıklama
400	İstek çözümlenemedi	POST ettiğiniz JSON'in yapısındaki hatadan kaynaklanır. Bu hatalar genellikle, yanlış yazılan JSON etiketi, düzgün kapatılmayan XML etiketi veya CDATA kullanılmadan JSON'in yapısını bozabilecek bir karakterin kullanımından kaynaklanır.
401	Üyelik bilgileri hatalı	POST ettiğiniz JSON'in authentication etiketi içerisinde göndermiş olduğunuz bilgileri doğrulayamadığımızda bu hatayı veriyoruz, eğer hesabınızda sabit IP tanımladıysanız ve farklı bir IP üzerinden istek yapıyorsanız yine bu hatayı alırsınız.
458	Tarih aralığı hatalı.	Gönderdiğiniz tarih formatı veya tarih aralığınız 10 günden daha fazla.
466	Hatalı numara	İstek içeriğindeki numara hatalı ise bu hatayı alırsınız.

Örnek İstek

{
  "request": {
    "authentication": {
      "key": "507caf2e1fcdb5eea9786332ca2d8785",
      "hash": "0db4e316db72c519ba08121985f6ddf479809053d555c"
    },
    "inbox": {
      "page": 1,
      "rowCount": 30,
      "filter": {
        "start": "2026-08-01 00:00:00",
        "end": "2026-08-17 23:59:59",
        "gsm": "05354101234"
      }
    }
  }
}

Örnek İstek (Filtresiz)

{
  "request": {
    "authentication": {
      "key": "507caf2e1fcdb5eea9786332ca2d8785",
      "hash": "0db4e316db72c519ba08121985f6ddf479809053d555c"
    },
    "inbox": {
      "page": 1,
      "rowCount": 30
    }
  }
}

Örnek Başarılı Yanıt

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "inbox": {
      "count": 2,
      "messages": [
        {
          "id": 25,
          "shortCode": "7889",
          "from": "+90505702xxxx",
          "keyword": "TESTPRX",
          "command": null,
          "action": "UNSUBSCRIBE",
          "message": "TESTPRX RET",
          "price": 0.8,
          "receivedAt": "2026-08-16 20:20:20"
        },
        {
          "id": 26,
          "shortCode": "7889",
          "from": "+90505702xxxx",
          "keyword": "TESTPRX",
          "command": null,
          "action": "RECORD_ONLY",
          "message": "TESTPRX BILGI",
          "price": 0.8,
          "receivedAt": "2026-08-16 20:20:20"
        }
      ]
    }
  }
}

Örnek Hatalı Yanıt

{
  "response": {
    "status": {
      "code": 458,
      "message": "Tarih aralığı hatalı."
    }
  }
}

Sık Yapılan Hatalar

Format ekini unutmak: JSON gövde gönderirken adresin sonuna /json eklenmelidir. Eklenmezse sunucu gövdeyi XML olarak çözümlemeye çalışır ve isteğiniz 401 ile reddedilir.
Tarih filtresini eksik göndermek: start ve end birlikte gönderilmelidir; yalnız biri gönderilirse veya end değeri start değerinden küçükse 458 hatası döner.
from alanını kısa numara sanmak: from mesajı gönderen alıcının numarasıdır. Kısa numara shortCode alanında döner.
price değerinin 0 olmasını ücretsiz sanmak: price değerinin 0 olması mesajın ücretsiz olduğu anlamına gelmez; mesaj alındığı sırada hesap bakiyenizin yetersiz olduğunu gösterir.
command alanını boş metin sanmak: Komut eşleşmediğinde bu alan boş metin ("") değil null döner. Alanı doğrudan metin olarak işleyen istemcilerde null denetimi yapılmalıdır.
Eski kayıtlarda boş alan beklememek: command ve action alanları, özellik devreye alınmadan önce kaydedilmiş mesajlarda boş döner.
count değerini sayfadaki kayıt sayısı sanmak: count filtrenize uyan toplam kayıt sayısıdır; sayfalama için bu değeri rowCount ile birlikte değerlendirin.

İstek yapılacak adres​

İstek İçeriği (Body)​

Tanımlar​

authentication​

inbox​

Sunucu yanıtı​

Tanımlar​

status​

inbox​

messages​

Hata Kodları​

Örnek İstek​

Örnek İstek (Filtresiz)​

Örnek Başarılı Yanıt​

Örnek Hatalı Yanıt​

Sık Yapılan Hatalar​

İstek yapılacak adres

İstek İçeriği (Body)

Tanımlar

authentication

inbox

Sunucu yanıtı

Tanımlar

status

inbox

messages

Hata Kodları

Örnek İstek

Örnek İstek (Filtresiz)

Örnek Başarılı Yanıt

Örnek Hatalı Yanıt

Sık Yapılan Hatalar