Global Haberleşme API Kullanıcı Notları
Author : Global HaberleşmeVersion : 0.1
SMS Gönderimi hakkında genel bilgilerSMS göndermek için bilinmesi gereken genel konular başında sms uzunlukları vekullanılabilir karakterler gelmektedir. SMS gönderirken kullanabileceğiniz karakterleraş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 160 Karakter Türkçe SMS 155 Karakter
Bu karater sayıları üzerindeki metinler için uzun mesaj statüsünde hesaplamalar yapılır vemesaj boyutuna göre kontör düşülecektir.
API Erişim BilgileriAPI'ye erişmek için key ve secret bilgilerinizi olması gerekiyor. Bu bilgileriglobalhaberlesme.com adresinden üye olarak ya da giriş yaparak öğrenebilirsiniz. API key vesecret bilgisinin bir örneğini aşağıda bulabilirsiniz.
key : 8eaa3ca9e32334fa4527e9843598abf9secret : a3uBxqMKlzSgrSrO3KB6YXWQ3lIwGBRmxbZE5rcHawSfFDsGZ2s1lyLQqJKv3MYv
Bu bilgiler ile API arayüzünden iletişim kurmak için isteğinize GET parametresi olarakeklemeniz yeterlidir. key ve secret bilgilerimizin doğruluğunu kontrol etmek için aşağıdakikomutu çalıştırıp sonuca bakalım
curl "http://sms_api/?key=6750ee46da09310b8e668fe3f785e7d4\&secret=a3uBxqMKlzFgrSrO3KB6YXWQ2lIwGBRmcbZE5rcHawSfFDsGZ2s1lyLQqJKv3MYv"
$ 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 dageç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. İstekgö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=a3uBxqMKlzSgrSrO3KB6YXWQ3lIwGBRmxbZE5rcHawSfFDsGZ2s1lyLQqJKv3MYv"
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_count":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": "TEST", "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ızgereken numbers alanına birden fazla numara göndermektir. Aşağıdaki gibi bir veriyi POSTverisi olarak gönderebilirsiniz.
{ "numbers": ["5554443322", "5553334433", "5554433221"], "text": "Mesaj Metni", "originator": "TEST", "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çinsorgunuzun POST verisi aşağıdaki gibi olmalıdır.
[ { "numbers": "5554433221", "text": "Mesaj Metni 2", "originator": "TEST", "time": "2014-11-10 12:00:00", "turkish_character": "0" }, { "numbers": "5554443322", "text": "Mesaj Metni 1", "originator": "TEST", "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ğıdakigibi 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 sizeiki türlü cevap dönebilir. Eğer doğru key ve secret ile erişim sağladı iseniz aşağıdaki gibi bircevap 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 yolusize son gönderdiğiniz 20 sms mesajının kaydını döndürecektir. Aşağıdaki örneğe bakarakdönecek sonuç hakkında daha fazla bilgiye ulaşabilirsiniz.
{ "result": true, "data": [ { "id": "74", "created_datetime": "2014-11-10 11:37:44", "originator": "TEST", "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": "TEST", "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": "TEST", "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" }}
Rapor Detayını inceleme
Rapor detaylarına ulaşmak için ise rapor için
{ "result": true, "data": [ { "id": "12123", "created_datetime": "2014-11-10 11:37:44", "gsm_no": "5554443322", "gsm_operator": "3", "sent_status": "0", "sent_datetime": null, "out_status": "0", "out_datetime": null, "report_message": null } ], "totals": { "total_number": "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 rahatulaşabilirsiniz.
<?php
/** * Curl * * Basicly PHP-Curl wrapper for BasicMVC. * This class provides this interface: * * setUseragent( string $useragent ) * getUserAgent( string $useragent ) * get( string $url, array $data ) * post( string $url, array $data ) * * @package BasicLib * @author Haydar KULEKCI <[email protected]> * @version 0.1 */class Curl{
/** * User Agent information of the request * * @var string */ private $useragent = "";
/** * Setting the useragent information * * @param string $useragent */ public function setUseragent($useragent) { $this->useragent = $useragent; }
/** * Getting the useragent information * */ public function getUserAgent() { return $this->useragent; }
/** * HTTP GET Request with PHP-Curl * * @param string $url * @param array $data * @param string => errors are json formatted string */ public function get($url, $data = array()) { $url = $this->buildURL($url, $data); $resp = ""; try { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_USERAGENT => $this->useragent ));
$resp = curl_exec($curl); if (curl_errno($curl)) { return json_encode(array("error" => "Curl Error : " . curl_errno($curl))); } curl_close($curl);
} catch (Exception $e){ return json_encode(array('error' => "Curl Exception Error")); } return $resp; }
/** * HTTP POST Request with PHP-Curl * * @param string $url * @param array $data * @param string => errors are json formatted string */ public function post($url, $data = array()) { $resp = ""; try { $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $url, CURLOPT_USERAGENT => $this->useragent, CURLOPT_POST => 1, CURLOPT_ENCODING => "UTF-8", CURLOPT_POSTFIELDS => http_build_query($data) ));
$resp = curl_exec($curl); if (curl_errno($curl)) { return json_encode(array("error" => "Curl Error : " . curl_errno($curl))); } curl_close($curl); } catch (Exception $e){ return json_encode(array('error' => "Curl Exception Error")); } return $resp; }
/** * Build a HTTP Request Url for PHP-Curl * * @param string $url * @param array $data * @param string */ public function buildURL($url, $data = array()) { return $url . (empty($data) ? '' : '?' . http_build_query($data)); }
}
class Log { private $filename;
public function __construct($filename) { $this->filename = $filename; }
public function write($message) { $file = DIR_LOGS . $this->filename; $handle = fopen($file, 'a+'); fwrite($handle, date('Y-m-d G:i:s') . ' - ' . $message . "\n"); fclose($handle); }}
class SMSApi{ protected $api_url = "";
protected $secret = ""; protected $key = "";
protected $curl = null; protected $log = null;
protected $json_errors = array( JSON_ERROR_NONE => ' - No errors', JSON_ERROR_DEPTH => ' - Maximum stack depth exceeded', JSON_ERROR_STATE_MISMATCH => ' - Underflow or the modes mismatch', JSON_ERROR_CTRL_CHAR => ' - Unexpected control character found', JSON_ERROR_SYNTAX => ' - Syntax error, malformed JSON', JSON_ERROR_UTF8 => ' - Malformed UTF-8 characters, possibly incorrectly encoded' );
public function setCurl($curl) { $this->curl = $curl; }
public function setLogger($log) { $this->log = $log; }
public function init($key, $secret) { if (trim($key) == "" ||trim($secret) == "") { return false; } else { $this->key = $key; $this->secret = $secret; } }
public function reset() { $this->numbers = array(); $this->text = ""; $this->originator = ""; $this->time = "now"; }
public function setApiUrl($url) { $this->api_url = $url; }
public function get($url, $params = array(), $useragent = "global_sms") { $params = array_merge( $params, array( "key" => $this->key, "secret" => $this->secret ) );
$data = $this->curl->get($this->api_url . $url, $params); if ($this->log) { $this->log->write("Curl GET - to : " . $url . " with : " . json_encode($params), \Slim\Log::INFO); } $result = array();
$result = json_decode($data, true); $error = json_last_error(); if ($error) { if ($this->log) { $this->log->write("Curl GET JSON PARSE ERROR - " . $this->json_errors[$error]. " - " . $data, \Slim\Log::ERROR); } $result = array(); }
return $result; }
public function post($url, $params = array(), $useragent = "global_sms") {
$url = $this->curl->buildURL($this->api_url . $url, array( "key" => $this->key, "secret" => $this->secret ));
$data = $this->curl->post($url, $params); if ($this->log) { $this->log->write("Curl POST - to : " . $url . " with : " . json_encode($params), \Slim\Log::INFO); } $result = array();
$result = json_decode($data, true); $error = json_last_error(); if ($error) { if ($this->log) { $this->log->write("Curl POST JSON PARSE ERROR - " . $this->json_errors[$error] . " - " . $data, \Slim\Log::ERROR); } $result = array(); }
return $result;
}
function status() { if ($this->secret && $this->key) { return true; } return false; }
function getToken($username, $password) { $data = $this->curl->get(API_BASE_URL . "get/token", array( "username" => $username, "password" => $password ) );
$result = json_decode($data, true);
if (isset($result['secret']) && $result['secret']) { $this->secret = $result['secret']; } else { $this->secret = null; }
if (isset($result['key']) && $result['key']) { $this->key = $result['key']; } else { $this->key = null; }
return array("secret" => $this->secret, "key" => $this->key); }
function token_status($data = array()) { if (isset($data['error']) && $data['error']) { if (isset($data['error_code']) && ($data['error_code'] < 100 && $data['error_code'] >= 90)) return true; else return false; } else { return false; } }}
Kullanımı için örnek kodu aşağıda bulabilirsiniz
$logger = new Log("logs/test.log");$curl = new Curl();
$smsapi = new SMSApi();$smsapi->setCurl($curl);$smsapi->setLogger($logger);$smsapi->setApiUrl("http://API_BASE_URL/");$smsapi->init("8ea01da9e69134fa4527e9831e98abf9", "PmL3w7dXnlGl3PX0eRY13lyaJ3GfgoDojN7bTCeycYS0o1lStha5YKmzfGjdDE0q");
print_r($smsapi->get('sms/report/sent'));
$sms_data = json_encode(array( "numbers" => "5554443322", "originator" => "INFOSMS", "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" => "INFOSMS", "text" => "Test Mesaj", "time" => "2014-12-12 12:12:12", "turkish_character" => "0" ));
print_r($smsapi->post('sms/send/single', array( "data" => $sms_data )));
Teşekkürler.
Recommended
