Global Haberleşme API Kullanıcı Notları Yazar : Global Haberleşme Son Değiştirme Tarihi : 2015-02-14 Not: API Dökümanının en güncel halini kullanınız. En güncel halini http://uye.globalhaberlesme.com/uploads/api_user.pdf adresinden indirebilirsiniz. SMS Gönderimi hakkında genel bilgiler SMS göndermek için bilinmesi gereken genel konular başında sms uzunlukları ve kullanılabilir karakterler gelmektedir. SMS gönderirken kullanabileceğiniz karakterler aşağıdaki gibidir. Standart SMS gönderimi için izin verilen karakterler 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'R', 'S', 'T', 'U', 'V', 'Y', 'Z', 'Q', 'W', 'X', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'r', 's', 't', 'u', 'v', 'y', 'z', 'q', 'w', 'x', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '.', ',', '_', ' ', '?', '!', '(', ')', ';', ':', '@', ' ', '%', '-', '+', '/', "\n", '*', '\'', '&', '=' Türkçe SMS gönderimi için izin verilen karakterler
'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'R', 'S', 'T', 'U', 'V', 'Y', 'Z', 'Q', 'W', 'X', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'r', 's', 't', 'u', 'v', 'y', 'z', 'q', 'w', 'x', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '.', ',', '_', ' ', '?', '!', '(', ')', ';', ':', '@', ' ', '%', '-', '+', '/', "\n", '*', '\'', '&', '=', 'Ü', 'ü', 'Ö', 'ö', 'Ğ', 'ğ', 'Ç', 'ç', 'Ş', 'ş', 'ı', 'İ' Bu karakterler dışındakiler metin içerisinden silinecektir. Mesaj uzunlukları ise şu şekildedir. Standart ve Türkçe SMS'ler için kısa mesaj için karakter sayıları aşağıdaki gibidir. Standart SMS Türkçe SMS 160 Karakter 155 Karakter Bu karater sayıları üzerindeki metinler için uzun mesaj statüsünde hesaplamalar yapılır ve mesaj boyutuna göre kontör düşülecektir. JSON API Erişim Bilgileri API'ye erişmek için key ve secret bilgilerinizi olması gerekiyor. Bu bilgileri globalhaberlesme.com adresinden üye olarak ya da giriş yaparak öğrenebilirsiniz. API key ve secret bilgisinin bir örneğini aşağıda bulabilirsiniz. key : 8eaa3ca9e32334fa4527e9843598abf9 secret : a3ubxqmklzsgrsro3kb6yxwq3liwgbrmxbze5rchawsffdsgz2s1lylqqjkv3myv API için kullanılacak adres aşağıdaki gibidir ve döküman içerisinde API_BASE_URL olarak adlandırılacaktır. API_BASE_URL : api.globalhaberlesme.com Bu bilgiler ile API arayüzünden iletişim kurmak için isteğinize GET parametresi olarak eklemeniz yeterlidir. key ve secret bilgilerimizin doğruluğunu kontrol etmek için aşağıdaki komutu çalıştırıp sonuca bakalım $ curl "http://api_base_url/?key=8eaa3ca9e32334fa4527e9843598abf9\ &secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrmxbze5rchawsffdsgz2s1lylqqjkv3myv" Eğer bilgileri doğru ise "result":true yanıtını göreceksiniz. Eğer yanlış ise ya da geçersiz ise "result":"error","errors":
["error_code":"99","error_text":"auth Error!"] yanıtını alacaksınız. SMS Gönderimi API arayüzünden sms göndermek için aşağıdaki yolu izleyebilirsiniz. Bir numaraya sms gönderme Tek SMS göndermek için aşağıdaki POST verisini isteğiniz ile birlikte göndermelisiniz. İstek göndereceğiniz adres yolu /sms/send/single Post verisi: "numbers": "", "text": "", "originator": "", "time": "", "turkish_character": "", Bunun için örnek bir Curl sorgusu aşağıdaki gibidir. $ curl -XPOST --data 'data="numbers": "5554443322","text": "Mesaj Metni","originator": "TEST","time": "2014-11-10 12:00:00","turkish_character":"0"' "http://api_base_url/sms/send/single? key=8eaa3ca9e32334fa4527e9843598abf9&secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrm xbze5rchawsffdsgz2s1lylqqjkv3myv" Bu sorguyu çalıştırdığınızda ise aşağıdaki gibi bir yanıt alırsınız. "result":true,"message_id":"74","total_numbers_count":1,"turkcell_numbers_c ount":0,"vodafone_numbers_count":0,"avea_numbers_count":1,"total_credit":1 Eğer bir hata oluşursa hatalı yanıt şu şekilde olacaktır. "result":false,"errors":["error_code":"232","error_text":"originator is not valid!"] Bu hatada başlık bilgisi daha önceden kaydedilmemiş bir başlık ile sms gönderilmeye çalışılmıştır. ve hata ile karşılaşılmıştır. Gönderilecek verinin ve alınan cevabın düzgün hali aşağıdaki gibidir. Post verisi:
"numbers": "5554443322", "text": "Mesaj Metni", "originator": "GLOBALSMS", "time": "2014-11-10 12:00:00", "turkish_character": "0" Sonuç verisi: "result": true, "message_id": "74", "total_numbers_count": 1, "total_vodafone_count": 0, "total_turkcell_count": 0, "total_avea_count": 1, "total_credit": 1 Çoklu numaraya aynı sms'i gönderme Aynı api yolu ile daha fazla numaraya SMS gönderebilirsiniz. Bunun için tek yapmanız gereken numbers alanına birden fazla numara göndermektir. Aşağıdaki gibi bir veriyi POST verisi olarak gönderebilirsiniz. "numbers": ["5554443322", "5553334433", "5554433221"], "text": "Mesaj Metni", "originator": "GLOBALSMS", "time": "2014-11-10 12:00:00", "turkish_character": "0" Sonuç verisi olarak yine aynı sonuç dönecektir.
"result": true, "message_id": "75", "total_numbers_count": 3, "total_vodafone_count": 0, "total_turkcell_count": 0, "total_avea_count": 3, "total_credit": 3 Birden fazla sms'i aynı istekte göndermek Bunun için API arayüzünden /sms/send/multi yolunu kullanabilirsiniz. Bunun için sorgunuzun POST verisi aşağıdaki gibi olmalıdır. [ ], "numbers": "5554433221", "text": "Mesaj Metni 2", "originator": "GLOBALSMS", "time": "2014-11-10 12:00:00", "turkish_character": "0" "numbers": "5554443322", "text": "Mesaj Metni 1", "originator": "GLOBALSMS", "time": "2014-11-10 12:00:00", "turkish_character": "0" Bu istek için eğer bir hata oluşmaz ise aşağıdaki gibi bir cevap alacaksınız.
"result": true, "results":[ "result": true, "message_id": "76", "total_numbers_count": 1, "total_vodafone_count": 0, "total_turkcell_count": 0, "total_avea_count": 1, "total_credit": 1 ], [ "result": true, "message_id": "77", "total_numbers_count": 1, "total_vodafone_count": 0, "total_turkcell_count": 0, "total_avea_count": 1, "total_credit": 1 ] Başlıkları Listeleme Başlıkları listelemek için /originator/list yolunu kullanabilirsiniz. Bu istek size aşağıdaki gibi bir sonuç dönecektir. Kredi sorgulama ve Kullanıcı bilgilerine erişim Bu bilgiye erişmek için /user/info yoluna GET isteğinde bulunabilirsiniz. Bu API isteği size iki türlü cevap dönebilir. Eğer doğru key ve secret ile erişim sağladı iseniz aşağıdaki gibi bir cevap alırsınız.
"result":true, "data": "firstname":"", "lastname":"", "username":"", "email":"", "image":"", "credit":"" Eğer yanlış bilgiler ile çağırmaya çalışırsanız "result":"error", "errors":[ "error_code":"99", "error_text":"auth Error!" ] Böyle bir yanıt alırsınız. Rapor Sorgulama Son raporlarınızı sorgulamak için /sms/report/sent yolunu kullanabilirsiniz. Bu API yolu size son gönderdiğiniz 20 sms mesajının kaydını döndürecektir. Aşağıdaki örneğe bakarak dönecek sonuç hakkında daha fazla bilgiye ulaşabilirsiniz.
"result": true, "data": [ "id": "74", "created_datetime": "2014-11-10 11:37:44", "originator": "GLOBALSMS", "originator_id": "1", "total_num": "1", "pieces": "1", "total_sent": "0", "total_out": "0", "num_not_reached": "0", "num_waiting_for_time": "0", "text": "Mesaj Metni", "id": "73", "created_datetime": "2014-11-08 12:01:06", "originator": "GLOBALSMS", "originator_id": "1", "total_num": "3", "pieces": "1", "total_sent": "0", "total_out": "0", "num_not_reached": "0", "num_waiting_for_time": "0", "text": "ert",... "id": "75", "created_datetime": "2014-11-06 10:55:28", "originator": "GLOBALSMS", "originator_id": "1", "total_num": "1", "pieces": "1", "total_sent": "0", "total_out": "0", "num_not_reached": "0", "num_waiting_for_time": "0", "text": "Test Metni" ], "totals": "total_message": "73", "total_sms": "12150"
Eğer iki tarih arasındaki gönderilen SMS'lerin raporlarına ulaşılmak isteniyorsa bu durumda between_start ve between_end GET parametrelerini kullanabilirsiniz. Rapor sonuçlarını sayfalandırmak için limit ve start parametrelerini kullanabilirsiniz. limit parametresi bir sayfadaki görünecek mesaj miktarını start bulunduğunuz sayfadaki mesajın sırasını belirtecektir. Örneğin: limit =10 ve start = 20 iken 3. sayfada olursunuz. Bir sonraki sayfaya erişmek için limit = 10 ve start = 30 şeklinde sorgu yapmalısınız. Rapor Detayını inceleme Rapor detaylarına ulaşmak için ise rapor için /sms/report/:mesaj_id adresine GET sorgusu yapabilirsiniz. Bu sorgu size aşağıdaki gibi bir sonuç dönecektir. "result": true, "data": [ "id": "12123", "created_datetime": "2014-11-10 11:37:44", "gsm_no": "5554443322", "gsm_operator": "3", "sent_status": "1", "sent_datetime": "2014-11-10 11:37:45", "out_status": "1", "out_datetime": "2014-11-10 11:37:48", "report_message": "DELIVERED" ], "totals": "total_number": "1", "message_id": "1", "total_sent": 1, "num_reached": 1, "num_not_reached": 0, "num_waiting_for_time": 0, "paid_coin": 1 PHP Örnek Sınıfı ve Kullanımı Bunun için örnek bir PHP sınıfı oluşturduk. Bu sınıfı kullanarak API arayüzüne daha rahat ulaşabilirsiniz. Örnek PHP kütphanesini http://uye.globalhaberlesme.com/uploads/php_sample.zip adresinden indirebilirsiniz. Kütüphanenin kullanımı için örnek kodu aşağıda bulabilirsiniz.
$logger = new Log("logs/test.log"); $curl = new Curl(); $curl->setuseragent("globalhaberlesme_api"); // User Agent api'yi kullanabilmek için önemlidir. $smsapi = new SMSApi(); $smsapi->setcurl($curl); $smsapi->setlogger($logger); $smsapi->setapiurl("http://api_base_url/"); $smsapi->init("...api_key...", "...api_secret..."); print_r($smsapi->get('sms/report/sent')); $sms_data = json_encode(array( "numbers" => "5554443322", "originator" => "GLOBALSMS", "text" => "Test Mesaj", "time" => "now", "turkish_character" => "0" )); print_r($smsapi->post('sms/send/single', array( "data" => $sms_data ) )); $sms_data = json_encode(array( "numbers" => array("5554443322","5542212322"), "originator" => "GLOBALSMS", "text" => "Test Mesaj", "time" => "2014-12-12 12:12:12", "turkish_character" => "0" )); print_r($smsapi->post('sms/send/single', array( "data" => $sms_data ) )); XML API Erişim Bilgileri API'ye erişmek için key ve secret bilgilerinizi olması gerekiyor. Bu bilgileri globalhaberlesme.com adresinden üye olarak ya da giriş yaparak öğrenebilirsiniz. API key ve secret bilgisinin bir örneğini aşağıda bulabilirsiniz. key : 8eaa3ca9e32334fa4527e9843598abf9 secret : a3ubxqmklzsgrsro3kb6yxwq3liwgbrmxbze5rchawsffdsgz2s1lylqqjkv3myv
API için kullanılacak adres aşağıdaki gibidir ve döküman içerisinde API_BASE_URL olarak adlandırılacaktır. API_BASE_URL : api.globalhaberlesme.com Bu bilgiler ile API arayüzünden iletişim kurmak için isteğinize GET parametresi olarak eklemeniz yeterlidir. key ve secret bilgilerimizin doğruluğunu kontrol etmek için aşağıdaki komutu çalıştırıp sonuca bakalım $ curl "http://api_base_url/?key=8eaa3ca9e32334fa4527e9843598abf9\ &secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrmxbze5rchawsffdsgz2s1lylqqjkv3myv&typ e=xml" XML ile çalışma için JSON API'dan farklı kritik kısım adresinizi sonuna ekleyeceğiniz &type=xml kısmıdır. Eğer bilgileri doğru ise aşağıdaki gibi bir yanıt alacaksınız. <?xml version='1.0' encoding='utf-8'?> <response><result>1</result><user><firstname>global</firstname> <lastname>sms</lastname><username>globalsms</username> <email>...@gmail.com</email><image>...</image><credit>100</credit></user> </response> Eğer yanlış ise ya da geçersiz ise aşağıdaki yanıtı alacaksınız. <?xml version='1.0' encoding='utf-8'?> <response><result>error</result><element><errors><error_code>99</error_code> <error_text>yetki Hatası!</error_text></errors></element></response> XML ile SMS Gönderimi XML ile SMS göndermek için aşağıdaki gibi bir yöntem kullanabilirsiniz. curl -XPOST --data 'data=<?xml version="1.0" encoding="utf-8"?><message> <numbers><number>5445898755</number><number>5445678978</number></numbers> <text>mesaj Metni</text><originator>GLOBAL SMS</originator><time>now</time> <turkish_character>0</turkish_character></message>' "http://api_base_url/sms/send/single? key=8eaa3ca9e32334fa4527e9843598abf9&secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrm xbze5rchawsffdsgz2s1lylqqjkv3myv&type=xml"
Bu sorgunun cevabı aşağıdaki gibidir. <?xml version='1.0' encoding='utf-8'?> <response><result>1</result><message_id>13320</message_id> <total_numbers_count>2</total_numbers_count> <turkcell_numbers_count>0</turkcell_numbers_count> <vodafone_numbers_count>2</vodafone_numbers_count> <avea_numbers_count>0</avea_numbers_count><total_credit>2</total_credit> </response> Burada dikkat edilmesi gereken kısımlar mesaj data formatıdır ve datayı gönderirken data parametresi ile gönderiyoruz. Mesaj formatını aşağıdaki gibidir. <?xml version="1.0" encoding="utf-8"?> <message> <numbers> <number>5445898755</number> <number>5445678978</number> </numbers> <text>mesaj Metni</text> <originator>global SMS</originator> <time>now</time> <turkish_character>0</turkish_character> </message> URL ile SMS Gönderme Bu özelliği kullanmak için GET parametreleri ile göndermek istediğiniz SMS'in bilgilerini iletmelisiniz. Örneğin, http://api_base_url/sms/send/single? key=8eaa3ca9e32334fa4527e9843598abf9&secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrm xbze5rchawsffdsgz2s1lylqqjkv3myv&text=mesaj%20metni&numbers=5445898755,54456 78978&originator=GLOBAL%20SMS Bu mesaj için size cevabımız aşağıdaki gibi olacaktır. "result":true,"message_id":"24490","numbers": ["5445898755","5445678978"],"total_numbers_count":2,"turkcell_numbers_count" :0,"vodafone_numbers_count":2,"avea_numbers_count":0,"total_credit":2 Yukarıdaki URL adresi ile 5445898755,5445678978 numaralarına SMS gönderebilirsiniz. Sadece bir numaraya SMS göndermek için numbers parametresine sadece bir numara yazmanız yeterlidir. Örneğin:
http://api_base_url/sms/send/single? key=8eaa3ca9e32334fa4527e9843598abf9&secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrm xbze5rchawsffdsgz2s1lylqqjkv3myv&text=mesaj%20metni&numbers=5445678978&origi nator=global%20sms Eğer türkçe karakterli bir mesaj göndermek istiyorsanız. turkish_character parametresini 1 değeri ile göndermelisiniz. Yani : http://api_base_url/sms/send/single? key=8eaa3ca9e32334fa4527e9843598abf9&secret=a3ubxqmklzsgrsro3kb6yxwq3liwgbrm xbze5rchawsffdsgz2s1lylqqjkv3myv&text=test%20t%c3%bcrk%c3%a7e%20karakterli%2 0Mesaj&numbers=5445678978&originator=GLOBAL%20SMS&turkish_character=1 İleri tarihli bir SMS göndermek istiyorsanız time parametresinde tarihi göndermelisiniz. Bu parametredeki tarih formatı YYYY-MM-DD HH:II:SS şeklindedir. 10 Şubat 2015 10:15:10 tarihinde gönderilecek bir SMS için time parametresi 2015-02-10 10:15:10 değeri ile gönderilmedir. Genel Hata Kodları Hata kodları XML ya da JSON formatı için aynıdır. API kullanırken alabileceğiniz hata kodları aşağıdaki gibidir. Hata Kodu : 1 - Hata Metni : Anlık Hata Oluştu! Hata Kodu : 99 - Hata Metni : Yetki Hatası! Hata Kodu : 98 - Hata Metni : Yetkilendirme Hatası! Hata Kodu : 102 - Hata Metni : Post verinizi için kodlamanız hatalıdır.! Hata Kodu : 103 - Hata Metni : Desteklenmeyen veri! Hata Kodu : 104 - Hata Metni : Post verilerinizi kontrol edin. Hata Kodu : 105 - Hata Metni : Post data is not correct XML encoded! Hata Kodu : 106 - Hata Metni : This XML method is not supported yet! Hata Kodu : 107 - Hata Metni : Sonuç verisi hatalı kodlandı. Yönetici ile iletişime geçin! Hata Kodu : 221 - Hata Metni : Recipent alanını kontrol edin. Hata Kodu : 222 - Hata Metni : Recipent alanı boş ya da bu alana yazdığınız numara karalistede. Lütfen kontrol edin. Hata Kodu : 223 - Hata Metni : SMS mesaj hatası. Hata Kodu : 224 - Hata Metni : Gönderilen veriler Multi için uygun formatta değil. Hata Kodu : 231 - Hata Metni : Originatör (Başlık) kontrol ediniz. Hata Kodu : 232 - Hata Metni : Originatörünüz (Başlık) kabul edilmedi. Hata Kodu : 241 - Hata Metni : Mesajın zaman bölümünü doldurunuz. Hata Kodu : 242 - Hata Metni : Zaman bölümünü şu şekilde doldurun YYYY-mm-dd HH:ii:ss Hata Kodu : 251 - Hata Metni : Mesajınız kaydedilemedi
Teşekkürler. Hata Kodu : 252 - Hata Metni : Aynı içeriğe sahip bu kadar mesajı sık sık gönderemezsiniz. Bunun için toplu SMS göndermeyi kullanınız.! Hata Kodu : 261 - Hata Metni : Mesaj metninizi desteklemiyoruz. Hata Kodu : 262 - Hata Metni : Mesaj Metni boş gönderilemez. Hata Kodu : 271 - Hata Metni : Kontörünüz yetersiz. Hata Kodu : 272 - Hata Metni : Kontör kontrol hatası Hata Kodu : 280 - Hata Metni : Mesaj bulunamadı Hata Kodu : 285 - Hata Metni : Mesaj türü seçiniz. Hata Kodu : 301 - Hata Metni : API şifreniz onay için bekliyor. Hata Kodu : 302 - Hata Metni : API anahtarınızda hata oluştu. Hata Kodu : 302 - Hata Metni : API anahtar silme hatası. Hata Kodu : 303 - Hata Metni : API anahtarı silinemedi Hata Kodu : 401 - Hata Metni : Grup ismi verilmesi gerekir. Hata Kodu : 501 - Hata Metni : Başlık gereklidir. Hata Kodu : 502 - Hata Metni : Başlık en az 3 en fazla 11 karakter olmalı ve özel karakter içermemelidir. Hata Kodu : 601 - Hata Metni : Kulanıcı adı en az 3 karakter olmalı ve A-Z, a-z, 0-9 ve _ karakterlerini içerebilir. Hata Kodu : 602 - Hata Metni : Şifre en az 5 olmalıdır ve A-Z, a-z, 0-9 ve '*', '/', '!', '+', '%', '&', '', '', '(', ')', '?', '_', '-' karakterlerini içerebilir. Hata Kodu : 603 - Hata Metni : Şifreniz hatalı Hata Kodu : 604 - Hata Metni : Lütfen Adınızı ve soyadınızı yazınız. Hata Kodu : 605 - Hata Metni : Tc numarası 11 karakter olmalıdır. Hata Kodu : 606 - Hata Metni : Lütfen şehir seçiniz. Hata Kodu : 608 - Hata Metni : Lütfen cep telefonunuzu yazınız. Hata Kodu : 609 - Hata Metni : Lütfen e-posta adresinizi yazınız. Hata Kodu : 610 - Hata Metni : Bu kullanıcı adı ile daha önce kayıt olunmuş. Bilgileriniz kaydedilemedi lütfen tekrar deneyin. Hata Kodu : 611 - Hata Metni : API şifreniz oluşturulamadı. Hata Kodu : 620 - Hata Metni : E-Posta adresi gereklidir. Hata Kodu : 621 - Hata Metni : Şifreniz oluşturulamadı. Lütfen yönetici ile iletişime geçin. Hata Kodu : 622 - Hata Metni : Şifre değiştirme kodu bulunamadı! Hata Kodu : 623 - Hata Metni : Şifre değiştirme kodunuz eksik ya da yanlış. Hata Kodu : 624 - Hata Metni : Şifreniz boş olamaz ve birbiri ile aynı olmalıdır. Hata Kodu : 701 - Hata Metni : Telefon numarasını giriniz. Hata Kodu : 702 - Hata Metni : İletişim bilgileriniz kaydedilemedi. Hata Kodu : 703 - Hata Metni : Bu numara daha önceden kaydedilmiş.! Hata Kodu : 710 - Hata Metni : Herhangi bir dosya bulunamadı. Hata Kodu : 711 - Hata Metni : Dosya ismi gereklidir. Hata Kodu : 712 - Hata Metni : Dosya tipi gerekli. Dosya isminizi kontrol edin. Hata Kodu : 713 - Hata Metni : Dosya kaydedilemedi. Hata Kodu : 900 - Hata Metni : Kullanıcı adı ve şifre gerekiyor.