Ana içeriğe geç

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)

Eğer API Anahtarı kullanılarak işlem yapıyorsanız isteğin içeriği:
<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(header) 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.

codemessageAçıklama
401Üyelik bilgileri hatalıkey, hash etiketleri ile 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.
402Bakiye yetersizEğer hesabınızdaki bakiye bu siparişi göndermeye yetmiyorsa bu hatayı veriyoruz.
450Gönderilen başlık kullanıma uygun değilsender 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.
451Tekrar 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.
452Mesaj alıcıları hatalıreceipents etiketi altında 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.
453Sipariş 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.
454Mesaj metni boştext etiketi ile göndermiş olduğunuz mesaj metni herhangi bir değer içermiyorsa mesajınız gönderilmez ve bu hata mesajı döner.
457Mesaj 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.

Ö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>