XML Post API

SMS Gönderme işlemini, HTTP protokolünün POST metodunu kullanarak, XML formatında yapmak isterseniz aşağıdaki yönergeleri takip edebilirsiniz.

İstek yapılacak adres

POSThttps://api.iletimerkezi.com/v1/send-sms

İstek İçeriği (Body)

<request>
  <authentication>
    <key></key>
    <hash></hash>
  </authentication>
  <order>
    <sender></sender>
    <sendDateTime></sendDateTime>
    <iys>1</iys>
    <iysList>BIREYSEL</iysList>
    <message>
      <text><![CDATA[...]]></text>
      <receipents>
        <number></number>
        <number></number>
      </receipents>
    </message>
  </order>
</request>

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.

order

Gönderilecek olan SMS'ler bir sipariş olarak kabul edilir ve istek yapıldıktan sonra bu şekilde raporlanmaya başlanır. Sipariş bazen tek alıcı ve tek mesaj metni içerebileceği gibi birden fazla alıcıya ve birden fazla mesaj metnide içerebilir. order etiketi tekrarlanabilir bir etiket değildir. İstek başına yalnızca bir sipariş gönderilebilir. Alt etiketleri aşağıdaki gibidir:

sender: iletimerkezi.com yönetim panelinden tanımlanmış ve iletimerkezi.com tarafından onaylanmış, maksimum 11 karakterden oluşan başlık bilgisidir. Gönderilen mesaj, alıcıya bu parametre ile belirtilen başlık ile yollanır. İstek yapılırken gönderilmesi zorunludur.
sendDateTime: Mesajın gönderim tarihini ifade eder. İleri tarihli mesaj gönderimleri için kullanılır. Formatı GG/AA/YYYY SS:DD şeklindedir. İstek yapılırken gönderilmesi zorunlu değildir. Varsayılan değeri, istek yapılan zamandır.
iys: Mesajın, İleti Yönetim Sistemi (İYS) üzerinden sorgulanıp sorgulanmayacağını ifade eder. Eğer bu değeri 1(true) olarak gönderirseniz mesajlarınız İYS üzerinden sorgulanır, 0(false) olarak gönderirseniz sorgulanmaz. İstek yapılırken gönderilmesi zorunludur.

İpucu
Ticari mesaj gönderiyorsanız bu değer yasal olarak 1 olmalıdır. Aksi durumda cezai işlem uygulanabilir.
İYS hakkında detaylı bilgi için tıklayınız.
iysList: İleti Yönetim Sistemi (İYS) üzerinden sorgulanmasını istediğiniz listeyi ifade eder. iys değerini 1 olarak gönderdiyseniz yani mesajınızın İYS üzerinden sorgulanmasını istiyorsanız, iysList değerinin BIREYSEL veya TACIR olarak gönderilmesi zorunludur. iys değerini 0 olarak gönderiyorsanız bu alan dikkate alınmayacaktır.

message

Gönderilecek olan mesaj bilgisini içerir. Tek sipariş içinde farklı mesaj gönderilmek isteniyorsa message etiketi gönderilmek istenen farklı mesaj sayısı kadar tekrarlanmalıdır. Alt etiketleri aşağıdaki gibidir

text: Gönderilecek olan SMS metnini içerir. İstek yapılırken gönderilmesi zorunludur.

İpucu

Mesaj metniniz içinde XML'in yapısını bozucak karakterler içerebileceği için mesaj metninizi <![CDATA[...]]> içerisine yazmanızı öneriyoruz. Mesaj metniniz içerisinde yazılımınızı kullanan kullanıcılarınız tarafından belirlenen ifadeler olabileceği için <![CDATA[...]]> kullanımı mesajlarınızın sağlıklı iletilmesi için önemlidir.

receipents: Gönderilecek olan SMSlerin alıcılarını içerir. Alıcılar aşağıdaki etiket ile belirtilir:
- number: Alıcının cep telefonu numarasını içerir. 905xxxxxxxxx, +90 5xx xxx xx xx, 5xxxxxxxxx gibi formatlar kullanılabilir. İstek yapılırken gönderilmesi zorunludur. Belirtilen mesaj metni için birden fazla alıcı tanımlanacaksa bu etiket alıcı sayısı kadar tekrarlanmalıdır.

Sunucu yanıtı

<response>
  <status>
    <code></code>
    <message></message>
  </status>
  <order>
    <id></id>
  </order>
</response>

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.

order

İşlem başarılı olarak tamamlandıysa oluşturulan sipariş bilgisini içerir. İşlem başarısızsa bu etiket döndürülmez. order etiketi tekrarlanabilir bir etiket değildir. İstek başına yalnızca bir sipariş gönderilebilir. Alt etiketi aşağıdaki gibidir:

id: Siparişi ifade eden eşsiz numerik değerdir. Size dönen bu id değeri ile, siparişinizin son durumunu kontrol edebilirsiniz. Eğer siparişiniz ileri bir tarihte gönderilecek bir sipariş ise id değeri ile siparişinizi iptal edebilirsiniz.

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.
402	Bakiye yetersiz	Eğer hesabınızdaki bakiye bu siparişi göndermeye yetmiyorsa bu hatayı veriyoruz.
450	Gönderilen başlık kullanıma uygun değil	sender etiketi ile göndermiş olduğunuz değer eğer hesabınızda onaylı değilse bu hatayı alırsınız, hesabınızda tanımlı olduğu şekilde göndermeniz gerekmektedir. Genellikle bu hatanın alınmasına sebep olan değişiklikler, küçük-büyük harf farkları veya ektra boşluk değerlerinin gönderilmesidir.
451	Tekrar eden sipariş	Eğer aynı mesaj metnini, aynı alıcılara 10dk içinde tekrar göndermek isterseniz sistem bu hatayı size döner, hem spam olmaması hemde yanlışlıkla aynı kişilere aynı mesajların iletilmemesi için. Böyle bir gönderim ihtiyacınız varsa mesaj metninin içine o anki saat ve dakikayı yazarak mesaj metnini farklılaştırabilirsiniz.
452	Mesaj alıcıları hatalı	receipents etiketi ile göndermiş olduğunuz telefon numaraları eksik veya doğrulanamıyor ise bu hatayı veriyoruz. Aynı zamanda eğer mesaj atmak istediğiniz cep telefonu numarasının doğru olduğuna eminseniz, cep telefonu numarası eğer numara engelleme listenize eklediyseniz yine bu hatayı alabilirsiniz.
453	Sipariş boyutu aşıldı	text etiketi ile göndermiş olduğunuz mesaj metni karakter kodlamanıza göre yedi(7) SMS uzunluğundan daha fazla ise bu hata geri döner.
454	Mesaj metni boş	text parametresinde göndermiş olduğunuz mesaj metni herhangi bir değer içermiyorsa mesajınız gönderilmez ve bu hata mesajı döner.
457	Mesaj gönderim tarihinin formatı hatalı	sendDateTime etiketi ile göndermiş olduğunuz tarih formatı hatalı ise bu hata döner. Tarih formatı, GG/AA/YYYY SS:DD (Örnek 20/01/2022 13:45) şeklindedir.
468	IYS üzerinden sorgulama yapılıp, yapılmayacağını ayarlamalısınız.	IYS üzerinden sorgulama yapılıp, yapılmayacağını ayarlamalısınız.
469	IYS listenizi seçmelisiniz, BIREYSEL veya TACIR.	IYS listenizi seçmelisiniz, BIREYSEL veya TACIR.
470	IYS kodunuzu ayarlamalısınız.	IYS kodunuzu ayarlamalısınız.

Örnek İstek

<?xml version="1.0" encoding="UTF-8" ?>
<request>
  <authentication>
    <key>demo</key>
    <hash>demo</hash>
  </authentication>
  <order>
    <sender>APITEST</sender>
    <sendDateTime>23/04/2022 09:00</sendDateTime>
    <message>
      <text><![CDATA[Test mesaji.]]></text>
      <receipents>
        <number>5301234567</number>
        <number>5301234568</number>
      </receipents>
    </message>
    <message>
      <text><![CDATA[Demo mesaji.]]></text>
      <receipents>
        <number>5301234569</number>
        <number>5301234560</number>
      </receipents>
    </message>
  </order>
</request>

Örnek Başarılı Yanıt

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code></code>
    <message></message>
  </status>
  <order>
    <id></id>
  </order>
</response>

Örnek Hatalı Yanıt

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>
    <code>400</code>
    <message>İstek çözümlenemedi</message>
  </status>
</response>

İstek yapılacak adres​

İstek İçeriği (Body)​

Tanımlar​

authentication​

order​

message​

Sunucu yanıtı​

Tanımlar​

status​

order​

Hata Kodları​

Örnek İstek​

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

Örnek Hatalı Yanıt​

İstek yapılacak adres

İstek İçeriği (Body)

Tanımlar

authentication

order

message

Sunucu yanıtı

Tanımlar

status

order

Hata Kodları

Örnek İstek

Örnek Başarılı Yanıt

Örnek Hatalı Yanıt