RESTful API Dökümanı

Yazılımsal olarak toplu SMS göndermek için gerekli dökümanlar.

KAYNAK KOD ÖRNEKLERİ

Çeşitli yazılım dilleri için hazırlamış olduğumuz kod örneklerini indirip hemen çalıştırabilirsiniz.


PHP ÖRNEK KODU İNDİR CSHARP ÖRNEK KODU İNDİR

GENEL BİLGİLER

Temel İstek Adresi:
https://panel.toplusms.tc/api/v1/

Tüm istekleri buraya yapıyoruz. Bu adresin sonuna yapılacak işleme göre parametreler ekleniyor. Örneğin SMS göndermek için https://panel.toplusms.tc/api/v1/sms/send/normal şeklinde kullanmamız gerekiyor.


Kullanıcı Doğrulaması:

Her istekte mutlaka HTTP Basic AUTH yöntemiyle USERNAME ve PASS bilgilerini göndermeniz gerekmektedir. USERNAME hesabınıza giriş yaptığınız kullanıcı adı bilgisidir, PASS ise MD5 algoritmasıyla hash'ini aldığımız şifrenizdir. Şifrenizi doğrudan göndermeniz bazı güvenlik problemleri oluşturduğundan dolayı MD5 hash'ini göndermeniz gerekmektedir.
Örneğin kullanıcı adınız 5551112233 ve şifreniz aabbcc112233 olduğunu farzedersek md5("aabbcc112233") değerini gönderiyoruz. Bu durumda sonuç şöyle olur:
Authorization: Basic YWRtaW46NDI5N2Y0NGIxMzk1NTIzNTI0NWIyNDk3Mzk5ZDdhOTM=
PHP'de CURL ile gönderim yaparken bu headerı oluşturmanıza gerek yoktur. Doğrudan kullanıcı adınız ve şifrenizin hash'ini yazmanız yeterlidir. Örneğin:
curl_setopt( $ch, CURLOPT_USERPWD, $username . ":" . md5($rawPassword) );


Standart BAŞARILI dönüş:

Her istekten bir status parametresi döner ve eğer başarılıysa bu parametre success değerine sahiptir. Örneğin:

{ 
   "status": "success"
}
								

Standart HATA dönüşü:

Tüm isteklerden HTTP STATUS 200 döner ama içerdiği JSON ifadesinde hata bilgileri dönebilir. Örneğin:

{ 
   "status": "error",
   "errorMessage": "Kullanıcı doğrulanamadı.",
   "errorCode": 3
}
								
							function makeApiCall( $method, $cmd, $postData, $username, $password ) {
   $ch = curl_init();

   curl_setopt( $ch, CURLOPT_URL, 'https://panel.toplusms.tc/api/v1/' . $cmd );
   curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 );
   curl_setopt( $ch, CURLOPT_VERBOSE, 1 );
   curl_setopt( $ch, CURLOPT_HEADER, 1 );
   curl_setopt( $ch, CURLOPT_POST, intval( $method == "post" ) );
   curl_setopt( $ch, CURLOPT_USERPWD, $username . ":" . $password );
   curl_setopt( $ch, CURLOPT_POSTFIELDS, $postData );
   curl_setopt( $ch, CURLOPT_TIMEOUT, 90 );
   $result = curl_exec( $ch );

   $header_size = curl_getinfo( $ch, CURLINFO_HEADER_SIZE );
   $header = substr( $result, 0, $header_size );
   $body = substr( $result, $header_size );

   curl_close( $ch );

   return array(
      "header" => $header,
      "body" => $body 
   );
}

						

SMS GÖNDERMEK

SMS Göndermek:
POST sms/send/normal

Parametreler:
caption: string

Başlık parametresidir. Büyük küçük harf duyarlıdır. Hesabınızda tanımlı olan başlıklardan herhangi birini kullanabilirsiniz.


validity: integer

Saat cinsinden mesajın geçerlilik süresi. Maximum 48 , minimum 1 olabilir. Bu değerlerin dışında bir değer girilirse veya hiç değer girilmezse 48 olarak kabul edilecektir.


message: string

Gönderilecek mesaj içeriğidir. Enter karakteri kabul edilmektedir.


senddate: string

İleri bir tarihte mesajın gönderilmesi için kullanılır. Boş bırakılırsa mesaj hemen gönderilir. Formatı MySQL standart tarih formatı olan Y-m-d H:i:s olmalıdır.


numbers: string

Numaralar 10 haneli olarak, virgül veya ENTER karakteriyle ayrılmış olarak gönderilmelidir.


encoding: string

Mesajın karakter kodlamasını belirtir. İngilizce karakterli mesaj için en , Türkçe karakterli mesaj için tr olmalıdır.


Dönüş Cevabı:

Eğer herhangi bir hatalı giriş veya kredi yetersizliği olmazsa gelecek olan veri tipi Content-Type: application/json; charset=UTF-8 şeklindedir ve JSON parametreleri aşağıdadır:


queueId: integer

Mesajın sistemde kayıtlı olan ID'si. Bu ID üzerinden rapor sorgulaması yapabilirsiniz.

							$postData = array();
$postData["caption"] = "TOPLUSMS.TC";
$postData["validity"] = 2;
$postData["message"] = "Örnek mesaj denemesidir.";
$postData["senddate"] = date("Y-m-d H:i:s");
$postData["numbers"] = "5551112233,5552223344,555334455";
$postData["encoding"] = "tr";

$apiResult = makeApiCall( "post", "sms/send/normal", $postData, $username, md5($password) );

echo "Headerlar: ";
print_r( $apiResult["header"] );

echo "JSON Cevap: ";
print_r( $apiResult["body"] );


						

RAPOR SORGULAMAK

Rapor Sorgulamak:
GET sms/reports/[queueId]

Parametreler:
queueId: int

Göndermiş olduğunuz mesajın ID'sidir.


Dönüş Cevabı:
{
    "status": "success",
    "queue": {
        "queue_id": "112233",
        "queue_user_id": "1122",
        "queue_status": "completed",
        "queue_message": "Bu örnek bir mesajdır.",
        "q_send_datetime": "2017-07-21 00:13:51",
        "q_total_credit": "2",
        "delivered_cnt": "2",
        "not_delivered_cnt": "0",
        "waiting_cnt": "0",
        "sent_cnt": "0",
        "total_numbers": "2",
        "st_title": "DEMO"
    },
    "numbers": [
        {
            "number": "5374937766",
            "status": "delivered",
            "sent_datetime": "2017-07-21 00:14:58",
            "updated_datetime": "2017-07-21 00:18:00"
        },
        {
            "number": "5538356060",
            "status": "delivered",
            "sent_datetime": "2017-07-21 00:14:58",
            "updated_datetime": "2017-07-21 00:18:00"
        }
    ]
}

							$apiResult = makeApiCall( "get", "sms/reports/112233", null, $username, md5($password) );

echo "Headerlar: ";
print_r( $apiResult["header"] );

echo "JSON Cevap: ";
print_r( $apiResult["body"] );

						

KREDİ SORGULAMAK

Kredi Sorgulamak:
GET user/profileDetails

Dönüş Cevabı:
{
    "status": "success",
    "id": "2345",
    "user_type": "registered_user",
    "username": "5551112233",
    "register_datetime": "2017-07-11 13:14:27",
    "active": "1",
    "firstname": "EMİR BUĞRA",
    "lastname": "KÖKSALAN",
    "birthyear": "1989",
    "tc_identity_no": "11112222333",
    "company_name": "İşletme Adı",
    "tax_office": "Karşıyaka VD",
    "tax_no": "555555555",
    "company_phone": "5551112233",
    "company_address": "işletme adresi",
    "email": "destek@nixarsoft.com",
    "cellphone": "5551112233",
    "invoice_address": "fatura adresi",
    "balance_money": "0",
    "balance_credit": "5555"
}

							$apiResult = makeApiCall( "get", "user/profileDetails", null, $username, md5($password) );

echo "JSON Cevap: ";
print_r( $apiResult["body"] );

						

URL ÜZERİNDEN İŞLEM YAPMAK

Daha hızlı ve basit bir yöntem olan URL üzerinden mesaj gönderimi, rapor sorgulama ve kredi sorgulama işlemlerini yapmak mümkün. PHP'de file_get_contents fonksiyonuyla işlem yapabilirsiniz. Dönüş bilgisi her zaman JSON'dır ve yukarıdaki çıktılarla aynıdır.

MESAJ GÖNDERİMİ

https://panel.toplusms.tc/api/v1/sms/send?apikey=[apikey]&encoding=[tr|en]&title=[title]&numbers=[numbers with comma]&message=[message]

Parametreler:
apikey: string

Panelde Ayarlar / API Bilgileri menüsünde bulunan API key bilgisi.

encoding: string

Türkçe karakterli mesaj için tr, ingilizce karakterli mesaj için en yazmalısınız.

title: string

Onaylanan başlığınızı yazmalısınız. Başlıklar büyük küçük harf duyarlıdır.

numbers: string

Numaraları buraya yazmalısınız. Numaraların formatı önemli değildir, sistem 10 haneli formata çevirir. Numaraların arasında virgül olmalıdırı. Örneğin 537 493 7766,0(555)111 22 33, 535 121 23 23 şeklinde gönderebilirsiniz.

message: string

Mesajınızı buraya yazmalısınız.


Dönüş Cevabı:
{
    "queueId": 112233
}

							$apiResult = file_get_contents("https://panel.toplusms.tc/api/v1/sms/send?apikey=mysecretapikey&encoding=tr&title=DEMO&numbers=5374937766&message=Örnek mesaj içeriğidir.");

$apiResult = json_decode( $apiResult );


						

RAPOR SORGULAMA

https://panel.toplusms.tc/api/v1/sms/reports/[queueId]?apikey=[apikey]

Parametreler:
queueId: integer

Mesaj gönderdikten sonra dönen queueId bilgisini buraya yazmalısınız.

apikey: string

Panelde Ayarlar / API Bilgileri menüsünde bulunan API key bilgisi.


Dönüş Cevabı:
{
    "status": "success",
    "queue": {
        "queue_id": "112233",
        "queue_user_id": "1234",
        "queue_status": "completed",
        "queue_message": "Bu örnek bir mesajdır",
        "q_send_datetime": "2018-09-29 17:46:00",
        "q_total_credit": "2",
        "delivered_cnt": "2",
        "not_delivered_cnt": "0",
        "waiting_cnt": "0",
        "sent_cnt": "0",
        "total_numbers": "2",
        "st_title": "DEMO"
    },
    "numbers": [{
        "number": "5374937766",
        "status": "delivered",
        "sent_datetime": "2018-09-29 17:46:02",
        "updated_datetime": "2018-09-29 17:47:03"
    }, {
        "number": "5538356060",
        "status": "delivered",
        "sent_datetime": "2018-09-29 17:46:02",
        "updated_datetime": "2018-09-29 17:47:03"
    }]
}

							$apiResult = file_get_contents("https://panel.toplusms.tc/api/v1/sms/send?apikey=mysecretapikey&encoding=tr&title=DEMO&numbers=5374937766&message=Örnek mesaj içeriğidir.");

$apiResult = json_decode( $apiResult );


						

KREDİ SORGULAMA

https://panel.toplusms.tc/api/v1/user/profileDetails?apikey=[apikey]

Parametreler:
apikey: string

Panelde Ayarlar / API Bilgileri menüsünde bulunan API key bilgisi.


Dönüş Cevabı:
{
    "status": "success",
    "id": "2",
    "top_id": "1",
    "user_type": "customer",
    "username": "5374937766",
    "register_datetime": "2016-10-06 16:56:07",
    "active": "1",
    "firstname": "EMİR BUĞRA",
    "lastname": "KÖKSALAN",
    "birthyear": "1989",
    "tc_identity_no": "xxxxxxxx",
    "province": "izmir",
    "district": "karşıyaka",
    "company_name": "Nixarsoft",
    "tax_office": "Karşıyaka VD",
    "tax_no": "13123123",
    "company_phone": "5374937766",
    "company_address": "xxxxxxxx",
    "email": "destek@toplusms.tc",
    "cellphone": "5374937766",
    "invoice_address": "xxxxxxxx",
    "api_key": "xxxxxxxxxxxxxxxxxxxx",
    "credit_type": "money",
    "money_per_credit": "0",
    "balance_credit": "12345",
    "affiliate_parent_id": "2",
    "balance_money": "0"
}

							$apiResult = file_get_contents("https://panel.toplusms.tc/api/v1/user/profileDetails?apikey=mysecretapikey");

$apiResult = json_decode( $apiResult );

// KREDİYİ ALMAK İÇİN balance_credit BİLGİSİNİ ALMANIZ GEREKİYOR.
$credit = $apiResult->balance_credit;