HTTP API Teknik Dokümantasyonu

Giriş

1.      API ile çalışmaya başlamadan önce ilgili yazılım geliştirmeleri yaparken şu geçici hesabı kullanabilirsiniz : Kullanıcı adı : “test” Şifre : “test”. Bu geçici hesap ile yaptığınız işlemler tamamen sanal olarak yürütülür ve yine sanal geri dönüşler alınır.

2.      API ile çalışmaya başlamak için http://sms.digicell.com.tr adresinde yeni üyelik oluşturun, giriş yapın. Kullanıcı İşlemleri -> Api Ayarları -> Api Hesabı Oluştur yolunu izleyin. Kullanıcı adınız aynı olmakla birlikte şifre olarak API SECRET olarak belirtilen 32 karakterlik ifadeyi kullanın. (Web şifreniz ile API şifreniz farklı şeylerdir)

3.      SMS yollayabilmek için hesabınızda kredi yüklendiğinden ve mesaj başlığınızın (originator) onaylanmış olduğuna emin olun.

4.      API istekleri sunucularımızın 8080 numaralı portuna HTTP GET veya HTTP POST şeklinde gerçekleştirilir.

5.      HTTP POST yönteminde içerik XML olarak formatlanmaktadır.

6.      API isteklerinde istek sayısı olarak bir sınırlama yoktur.

7.      Destek ve sorularınız için info@digicell.com.tr e-posta adresinden iletişime geçebilirsiniz.

Kara Listeye Ekleme

(blacklist’e ekleme)

Örnek :

Giden Parametreler

Parametreler :

Dönüş Değerleri

•      Tüm dönüş kodları metinden oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

Başarısız Dönüşler :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

Kara Liste Sorgulama

(kara listedeki numaraların tümünü verir)

Örnek :

Giden Parametreler

Parametreler :

Dönüş Değerleri

•      Tüm dönüş kodları metinden oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

•      Başarılı dönüşlerde koddan sonra bir boşluk karakteri bırakılır ve | (pipe) işareti ile ayrılmış biçimde yasaklı telefon numaraları döner. Eğer tek yasaklı numara varsa, içerikte | işareti bulunmaz.

Başarısız Dönüşler :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

Dönüş Değerleri

•      Tüm dönüş kodları metinden oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

•      Başarılı dönüşlerde koddan sonra bir boşluk karakteri bırakılır ve | (pipe) işareti ile ayrılmış biçimde onaylanmış sms başlıkları döner. Eğer tek onaylanmış başlık varsa, içerikte | işareti bulunmaz.

Başarısız Dönüşler :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

Dönüş Değerleri

•      Tüm dönüş kodları 2 basamaklı sayılardan oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

•      Başarılı dönüşlerde koddan sonra bir boşluk karakteri bırakılır ve kredi miktarı döner.

Başarısız Dönüşler :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

SMS Yollama

•       1-N tipi mesajlaşma aynı mesaj metnini bir veya daha fazla numaraya yollamak amacıyla tercih edilir. N-N tipi mesajlaşmada ise her numaraya farklı mesaj metni gönderilebilir.

•       Aşağıda gri arkaplana sahip olan satırlar opsiyonel özellikleri ifade eder. Bu özellikler kullanılmayacaksa XML yapısından kaldırılmalıdır, sadece gerekli olduğunda eklenmelidir.

•      Son 2 dakika içinde aynı SMS'i göndermeye çalışırsanız hata alırsınız. (Sistem bunu engeller)

•      Boş SMS gönderilemez.

Örnek :

Giden Parametreler

•      Parametreler boş bırakılmamalıdır, aksi halde 89 yani WRONG_XML_FORMAT hatası ile karşılaşılır.

Parametreler :

Dönüş Değerleri

•      Tüm dönüş kodları 2 basamaklı sayılardan oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

•      Başarılı dönüşlerde koddan sonra bir boşluk karakteri bırakılır ve daha sonra bu gönderim ile ilgili iletim raporu sorgusunda kullanılacak olan özgün (unique) bir sayısal ifade döner. ( Kısaca buna dlrId diyoruz ) Gelecekte iletim raporu sorgulanacaksa bu ifadeyi kaydetmeniz ve sorgu sırasında parametre olarak göndermeniz gerekmektedir.

Başarısız Dönüşler 1 :

•       Normal şartlarda asla karşılaşmamanız gereken bir hata kodudur. Hatanın kaynağı sunucu veya istemci taraflı olabilir. Yoğun olarak bu hatayı alırsanız lütfen iletişime geçiniz.

Başarısız Dönüşler 2 :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

SMS Yollama (HTTP GET)

•      Zorunlu olmadıkça bu yöntemi tercih etmeyiniz.

•      Bu yöntem en temel özellikleri ile HTTP GET metoduyla SMS gönderebilmek için kullanılır. Tek numaraya tek SMS gönderebilirsiniz.

•      Bu özellik bazı özel cihazlardan SMS gönderebilmesi amacıyla sonradan eklenmiştir. Bu yöntem SMS göndermeyle ilgili tüm özellikleri içermez. Dolayısıyla ihtiyacınızı karşılamıyorsa bir üst başlıktaki orjinal yöntemi kullanınız.

•      Son 2 dakika içinde aynı SMS'i göndermeye çalışırsanız hata alırsınız. (Sistem bunu engeller)

•      Boş SMS gönderilemez.

Örnek :

Giden Parametreler

•      Parametreler boş bırakılmamalıdır, aksi halde 83 yani MISSING_GET_PARAMS hatası ile karşılaşılır.

Parametreler :

Dönüş Değerleri

•      Tüm dönüş kodları 2 basamaklı sayılardan oluşur.

•      Başarısız dönüş olduğunda sadece kodun kendisini geri döner.

•      Başarılı dönüşlerde koddan sonra bir boşluk karakteri bırakılır ve daha sonra bu gönderim ile ilgili iletim raporu sorgusunda kullanılacak olan özgün (unique) bir sayısal ifade döner. ( Kısaca buna dlrId diyoruz ) Gelecekte iletim raporu sorgulanacaksa bu ifadeyi kaydetmeniz ve sorgu sırasında parametre olarak göndermeniz gerekmektedir.

Başarısız Dönüşler 1 :

•       Normal şartlarda asla karşılaşmamanız gereken bir hata kodudur. Hatanın kaynağı sunucu veya istemci taraflı olabilir. Yoğun olarak bu hatayı alırsanız lütfen iletişime geçiniz.

Başarısız Dönüşler 2 :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Başarılı Dönüşler :

İletim Raporu (DLR) Sorgulama

•      SMS gönderimi yapıldıktan hemen sonra DLR isteği yaparsanız hata alabilirsiniz. Sistem mesajı göndermekle ilgileniyor olabilir ve DLR raporunu oluşturacak olan veriler henüz hazır olmayabilir.

•      DLR isteğini, ilk olarak SMS gönderiminden sonraki 90. veya 180. saniyede yapmanızı tavsiye ederiz. (Sistem ilk olarak 60. saniyede DLR içeriğini güncelleyen bir görevi başlatır. 48 saat içinde başlarda daha sık olmak üzere sonlara doğru daha da seyrekleşen bir kural üstünden DLR içeriği güncellenmektedir)

•      Eğer belirttiğiniz tüm numaralara SMS ulaşmış ise DLR raporu 48 saat dolmadan önce tamamlanabilir, yani son halini alabilir. Bunu başarılı dönüş koduna bakarak anlayabilirsiniz.

•      Eğer gönderim listenizdeki numaralardan en az biri 48 saat boyunca kapalı kalmış ise DLR raporunun son halini alması toplamda 48 saat + 10 dakika gibi bir zaman alır. Bu 48 saat boyunca, DLR raporunun henüz son halini almadığı bilgisini başarılı dönüş koduna bakarak anlayabilirsiniz.

Örnek :

Giden Parametreler

Parametreler :

Dönüş Değerleri

•      Tüm dönüş kodları 2 basamaklı sayılardan oluşur.

•      Başarısız dönüş veya bilgilendirme dönüşü olduğunda sadece kodun kendisini geri döner.

•       Başarılı dönüşlerde, dönüş kodu sonrasında birbirinden “|” karakteri ile ayrılmış bloklar döner. Bu bloklar GSM no ve SMS iletim durumu bilgisini içerir. (Detaylar sayfa sonunda)

Başarısız Dönüşler 1 :

•       Normal şartlarda asla karşılaşmamanız gereken bir hata kodudur. Hatanın kaynağı sunucu veya istemci taraflı olabilir. Yoğun olarak bu hatayı alırsanız lütfen iletişime geçiniz.

Başarısız Dönüşler 2 :

•      Aşağıdaki hata kodları isteği yapan tarafın düzeltmesi gereken durumları belirtir.

Bilgilendirme Dönüşleri :

Başarılı Dönüşler :

SMS İletim Durum Kodları :

SMS Karakter Seti ve Boy Hesaplamaları

•      Bu bölümde bir SMS metninin kaç SMS olarak ücretlendirileceği, yani kaç boy olacağı ile ilgili hesaplamalara değinilecektir. Ayrıca gönderimine izin verilen karakterler hakkında da bilgi sahibi olacaksınız.

•       Sistemimiz max 6 boy SMS kabul etmektedir. Mesaj içeriği 6 boydan fazla ise otomatik olarak sondaki karakterlerden gereken kadarı silinerek mesaj 6 boy'a indirgenir.

•      Sistemimiz yollanacak olan her mesaj için boy hesabını otomatik olarak yapar, hesaplanan bu değerleri web arayüzünden görebilirsiniz.

Karakter Sınıfları :

•      İlk olarak kullanılan karakterlere bakılarak mesajın Türkçe mi yoksa İngilizce mi olduğu belirlenir. En az 1 adet Türkçe karakter kullanılmış ise mesaj Türkçe olur, aksi halde İngilizce olacaktır.

•      Eğer mesajı ingilizce mesaj olarak göndermek istiyorsanız aşağıdaki tabloda Türkçe olarak belirtilen karakterleri mesaj içeriğinden kaldırmanız veya İngilizce karakter sınıfından benzer karakterler ile yer değiştirdikten sonra mesajı yollamanız gerekmektedir.

•      Mesaj içeriğindeki Türkçe karakterlerin bazıları 1, bazıları ise 2 karakter yer kaplar. İlgili bilgiler aşağıdaki tabloda belirtilmiştir.

•       Bu aşamada mesajın İngilizce veya Türkçe mesaj olması ile birlikte mesajın kaç karakter olduğu hesaplanır. Dikkat ediniz, örneğin SMS içeriğindeki 'ğ' 2 karakter olarak hesaplanır.

Boyların Hesaplanması :

•      Mesajın dili ve karakter sayısı dikkate alınak boy aşağıdaki tablo yardımıyla belirlenebilir. Dikkat ederseniz İngilizce mesajlar Türkçe mesajlara göre birkaç karakter daha fazla bilgi taşıyabilmektedir.

•      Tablodaki değerler aralık belirtir. Başlangıç ve bitiş değerleri de o aralığa dahildir.

Mesaj Yollanmadan Önce Yaptığımız İçerik Dönüşümleri :

•      İlk olarak şunlar yer değiştirir : | => I, ^ => ', € => E, { => (, [ => (, } => ), ] => ), \ => /

•      Sonrasında, mesaj içeriğinde aşağıdaki karakterler dışında bir karaktere rastlanırsa ilgili karakter ' ' (yani boşluk karakteri) olarak kabul edilir ve mesaj öyle yollanır :

ABCDEFGĞHIİJKLMNOPRSŞTUVYZÖÜQWXÇ abcçdefgğhıijklmnoprsştuvyzöüqwx@*:!$_#()+-;,<>=./'?"%&0123456789

Örnek Kaynak Kodlar

•      Fonksiyon : Kredi Sorgulama

•      Programlama Dili : Java

•      Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

public void kredi(){

HttpURLConnection uc = null;

try{

URL url = new URL("http://api.sms.digicell.com.tr:8080/api/credit/v1?username=test&password=test");

uc = (HttpURLConnection)url.openConnection();

uc.setRequestMethod("GET");

uc.setReadTimeout(5*1000);

uc.setConnectTimeout(5*1000);

uc.connect();

int resCode = uc.getResponseCode();

System.out.println("HTTP "+resCode);

int readed;

char[] buffer = new char[4*1024];

StringBuffer sb = new StringBuffer();

BufferedReader in = new BufferedReader(new InputStreamReader(uc.getInputStream(), "UTF-8"));

while( (readed = in.read(buffer)) > 0 ){

sb.append(buffer, 0, readed);

}

in.close();

String ret = sb.toString();

System.out.println("["+ret+"]");

}catch(Exception ex){

ex.printStackTrace();

}finally{

try{ uc.disconnect(); }catch(Exception ex){} uc = null;

}

}

•       Fonksiyon : SMS Gönderme

•       Programlama Dili : Java

•       Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

public void send(){

HttpURLConnection uc = null;

try{

URL url = new URL("http://api.sms.digicell.com.tr:8080/api/smspost/v1");

uc = (HttpURLConnection)url.openConnection(); uc.setRequestMethod("POST");

uc.setDoInput(true);

uc.setDoOutput(true);

uc.setRequestProperty("Content-Type", "text/xml; charset=UTF-8");

uc.setRequestProperty("Content-Encoding", "UTF-8"); uc.setReadTimeout(5*1000);

uc.setConnectTimeout(5*1000);

uc.connect();

OutputStreamWriter out = new OutputStreamWriter(uc.getOutputStream(), "UTF-8"); out.write(""

+  "<sms>"

+  "<username>test</username>"

+  "<password>test</password>"

+  "<header>BAŞLIK</header>"

+  "<validity>2880</validity>"

+  "<message>"

+  "<gsm>"

+  "<no>905559998877</no>"

+  "</gsm>"

+  "<msg><![CDATA[-test-message-]]></msg>"

+  "</message>"

+  "</sms>");

out.flush();

out.close();

int resCode = uc.getResponseCode();

System.out.println("HTTP "+resCode);

int readed;

char[] buffer = new char[4*1024];

StringBuffer sb = new StringBuffer();

BufferedReader in = new BufferedReader(new InputStreamReader(uc.getInputStream(), "UTF-8"));

while( (readed = in.read(buffer)) > 0 ){

sb.append(buffer, 0, readed);

}

in.close();

String ret = sb.toString();

System.out.println("["+ret+"]");

}catch(Exception ex){

ex.printStackTrace();

}finally{

try{ uc.disconnect(); }catch(Exception ex){} uc = null;

}

}

•       Fonksiyon : SMS Gönderme (HTTP GET)

•      Programlama Dili : Java

•      Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

public void kredi(){

HttpURLConnection uc = null;

try{

URL url = new URL(" http://api.sms.digicell.com.tr:8080/api/smsget/v1?

username=test&password=test&header=BAŞLIK&gsm=905559998877&message=MESAJ%20TEST ");

uc = (HttpURLConnection)url.openConnection();

uc.setRequestMethod("GET");

uc.setReadTimeout(5*1000);

uc.setConnectTimeout(5*1000);

uc.connect();

int resCode = uc.getResponseCode();

System.out.println("HTTP "+resCode);

int readed;

char[] buffer = new char[4*1024];

StringBuffer sb = new StringBuffer();

BufferedReader in = new BufferedReader(new InputStreamReader(uc.getInputStream(), "UTF-8"));

while( (readed = in.read(buffer)) > 0 ){

sb.append(buffer, 0, readed);

}

in.close();

String ret = sb.toString();

System.out.println("["+ret+"]");

}catch(Exception ex){

ex.printStackTrace();

}finally{

try{ uc.disconnect(); }catch(Exception ex){} uc = null;

}                 

}

•       Fonksiyon : Kredi Sorgulama

•      Programlama Dili : PHP (curl eklentisi ile birlikte)

•      Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

<?php

$postUrl = "http://api.sms.digicell.com.tr:8080/api/credit/v1?username=test&password=test";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $postUrl);

curl_setopt($ch, CURLOPT_TIMEOUT, 5);

curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);

$response = curl_exec($ch);

curl_close($ch);

echo '['.$response.']'."\n";

?>

•       Fonksiyon : SMS Gönderme

•      Programlama Dili : PHP (curl eklentisi ile birlikte)

•      Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

<?php

$postUrl = "http://api.sms.digicell.com.tr:8080/api/smspost/v1";

$postData = "".

"<sms>".

"<username>test</username>".

"<password>test</password>".

"<header>BAŞLIK</header>".

"<validity>2880</validity>".

"<message>".

"<gsm>".

"<no>905559998877</no>".

"</gsm>".

"<msg><![CDATA[-test-message-]]></msg>".

"</message>".

"</sms>";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $postUrl);

curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_TIMEOUT, 5);

curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);

curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-Type: text/xml; charset=UTF-8"));

$response = curl_exec($ch);

curl_close($ch);

echo '['.$response.']'."\n";

?>

•       Fonksiyon : SMS Gönderme (HTTP GET)

•      Programlama Dili : PHP (curl eklentisi ile birlikte)

•      Lütfen kaynak kodu kullandığınız editörde yeniden formatlayınız. Kodlarda gereksiz gördüğünüz yerleri daha sonra silebilirsiniz.

<?php

$postUrl = "http://api.sms.digicell.com.tr:8080/api/smsget/v1? username=test&password=test&header=BAŞLIK&gsm=905559998877&message=MESAJ%20TEST";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $postUrl);

curl_setopt($ch, CURLOPT_TIMEOUT, 5);

curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);

$response = curl_exec($ch);

curl_close($ch);

echo '['.$response.']'."\n";

?>