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.
İpucuTicari mesaj gönderiyorsanız bu değer yasal olarak 1 olmalıdır. Aksi durumda cezai işlem uygulanabilir.
-
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.
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.
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>