Dökümantasyon

STH Portal SMS

Tanıtım

Kullanıcı kendi giriş kodu ve şifresi ile API üzerinden SMS atabilir. Eğer SMS iletim raporlarının otomatik olarak bildirilmesi isteniyorsa, iletim raporlarının HTTP protokolü üzerinden gönderileceği adres belirtilmelidir. Tüm API gönderim va bildirim raporlarının iletilmesi için JSON kullanılacaktır.

API ile gönderim

https://portal.FIRMA.com.tr/sms/api adresine şu biçimde SMS gönderimi yapılabilir:

{
                       "username":"KULLANICI_KODU",
                       "password":"SIFRE",
                       "header":"GONDEREN",
                       "action":"send_sms",
                       "phones":[
                          {
                             "phone":"TELEFON_NUMARASI1",
                             "api_id":"API_NO1"
                          },
                          {
                             "phone":"TELEFON_NUMARASI2",
                             "api_id":"API_NO2"
                          }
                       ],
                       "text":"Deneme Mesajidir."
                    }
                    

Parametre Açıklama Mecburi?
username API kullanıcı kodu Evet
password API şifresi Evet
header SMS başlığıdır, sizin için tanımlanan bir SMS başlığını ve DID'yi kullanabilirsiniz. 11 karakteri geçemez. Hayır
phones SMS'in gönderileceği telefon bilgilerinin listesi Evet
phone Telefon numarası Evet
api_id SMS iletim raporları iletilirken burada belirttiğiniz no ile geri dönüş yapılır. Bu sizin sisteminizde tanımlı numaradır. Belirtilmez ise otomatik bildirim yapılmaz. Hayır
append_cancel true olarak gönderilirse SMS mesajına otomatik olarak İPTAL SMS linkini ekler. Hayır
append_mersis true olarak gönderilirse SMS mesajına otomatik olarak hesaba tanımlı olan Mersis numarasını ekler. Hayır
send_after YYYY-MM-DD HH:mm:ss tipinde ileri bir tarih(UTC) gönderilirse SMS mesajını o zamandan sonra gönderir. Hayır
text SMS Mesajı içeriğidir.

Normal SMS


1 adet mesajın boyutu 160 karakterdir. İçerik uzunluğuna göre kontör hesabı şu şekildedir:
Karakter Sayısı Kontör
0-160 1
160-306 2
306-459 3
459-612 4
612-765 5
Not: 7 bit gsm alfabesi genişleme tablosunda yer alan şu karakterler çift karakter sayılırlar:
^ { } \ [ ] ~ | €

Türkçe SMS


Türkçe karakter içeren SMS'lerin için 1 adet kısa mesajın boyutu 155 karakterdir. Kontör hesabı şu şekildedir:
Karakter Sayısı Kontör
0-155 1
155-298 2
298-447 3
447-596 4
596-745 5
Not: 7 bit gsm alfabesi genişleme tablosundakiler ile Türkçe şu karakterler; çift karakter sayılırlar:
^ { } \ [ ] ~ | € Ş ş Ğ ğ ç ı İ

Unicode SMS


Rusça, arapça gibi özel karakterli dillerle mesaj göndermek için kullanılır. 1 adet mesajın boyutu 70 karakterdir. Kontör hesabı şu şekildedir:
Karakter Sayısı Kontör
0-70 1
70-134 2
134-201 3
201-268 4
268-335 5
Evet

Çoklu SMS Gönderimi

https://portal.FIRMA.com.tr/sms/api adresine yukarıdaki mesaj paketinin içine "sms_tbl" alanı eklenerek şu biçimde SMS gönderimi yapılabilir:

"smstbl":[
               [
                  "TELEFON_NUMARASI1",
                  "mesaj 1",
                  "api_id_1"
               ],
               [
                  "TELEFON_NUMARASI2",
                  "mesaj 2",
                  "api_id_2"
               ]
            ],
            "send_after":""
            

SMS Gönderim Cevabı

SMS gönderimine, gönderilen SMS içeriği için cevap dönülür. Cevap şuna benzer olacaktır:

    {
       "data":{
          "invalid_phones":[
               {"api_id": API_NO, "error": "Invalid Phone", "phone": "ABC"}
          ],
          "plan_remaining_units":1298.0,
          "plan_sms_units":1.0,
          "receiver_count":1,
          "request_id":744,
          "tariff_cost":0.0,
          "tariff_sms_units":0,
          "tr_enabled":false
       },
       "message":"Kaydedildi.",
       "success":true
    }
Parametre Açıklama
invalid_phones Geçersiz telefonların listesidir. Her telefon için api_id, telefon numarası ve hata mesajını döner.
plan_remaining_units SMS paketlerinde kalan kontör toplamı
receiver_count Kabul edilen toplam geçerli telefon sayısı
request_id Bu gönderim için sistemin atadığı no
tariff_sms_units SMS kontörünüzün yeterli olmadığı durumlarda tarifenize göre hesabınızdan düşülen SMS kontörü.
tariff_cost SMS kontörünüzün yeterli olmadığı durumlarda tarifenize göre hesabınızdan düşülen SMS ederi.
tr_enabled Türkçe SMS aktif mi?
message Hata mesajı içeriği
success Bu gönderim için başarı durumu, eğer hiç geçerli telefon olmaz ise veya eksik parametre varsa "false", eğer kabul edildi ise "true" döner.

SMS İletim Raporu

Yukarıda API ile SMS gönderilince sistem size SMS'in kabul edilip edilmediğini dönecektir. Fakat, SMS'in son kullanıcıya ulaşıp ulaşmadığının da size anında rapor edilebilmesi için bize bir tane ulaşabileceğimiz URL vermeniz gerekmektedir. SMS ulaştı bilgisi bize ilgili operatör tarafından gelince biz de sizin bu URL'i çağırarak sonuç bildirimlerini yapacağız. Belirteceğiniz bu web adresine aşağıdaki şekilde SMS iletim raporu gönderilir:

    [
                   {
                      "status":10,
                      "delivery_time":"2014-02-14T14:08:23.328992+02:00",
                      "cause":"Başarılı",
                      "message_id":338479,
                      "api_id":"9999"
                   },
                   {
                      "status":11,
                      "delivery_time":"2014-02-14T14:08:23.328992+02:00",
                      "cause":"Böyle bir abone yok",
                      "message_id":338439,
                      "api_id":"9939"
                   }
                ]
            
Parametre Açıklama
delivery_time Operatörün iletim tarihi, ISO formatında.(%Y-%m-%dT%H:%M:%S.%f%z)
message_id Mesajın sistemdeki no'su
api_id Mesajı gönderirken her telefon için belirttiğiniz no.
status Durum kodu.
Durum Kodu Açıklama
0 Henüz gönderilmedi
1 Gönderiliyor
2 Operatöre teslim edildi
3 Geçersiz SMS.(SMS parametreleri eksik)
5 Telefon numarası geçersiz.
10 SMS iletildi.
11 SMS iletilemedi.
12 Duplike SMS.
13 Telefon numarası DND listesinde

PHP Kod Örneği

<?php
function sendSMS($header, $message, $phones)
{
    $sms_msg = array(
        'header' => $header,
        'username' => 'USERNAME',
        'password' => 'PASSWORD',
        'action' => 'send_sms',
        'text' => $message,
        'phones' => $phones
    );

    $ch = curl_init('https://portal.FIRMA.com.tr/sms/api');
    curl_setopt_array($ch, array(
        CURLOPT_POST => TRUE,
        CURLOPT_RETURNTRANSFER => TRUE,
        CURLOPT_HTTPHEADER => array(
            'Content-Type: application/json'
        ),
        CURLOPT_POSTFIELDS => json_encode($sms_msg)
    ));
    $response = curl_exec($ch);
    if ($response === FALSE) {
        return array(
            false,
            'Can not send message, service not avaiable'
        );
    }
    $rdata = json_decode($response, TRUE);
    if (!$rdata['success']) {
        return array(
            false,
            $rdata['message']
        );
    }
    $res = array(
        "credits" => 0,
        "units" => 0
    );
    // To get sms credits, to get balance call get_balance api
    if ($rdata['data']['tariff_cost'] == 0) {
        $res['credits'] = (int) $rdata['data']['plan_remaining_units'];
    }
    $res['units'] = (int) $rdata['data']['plan_sms_units'] + (int) $rdata['data']['tariff_sms_units'];
    return array(
        true,
        $res
    );
}

sendSMS("HEADER", "Test Mesajı", array(
    array(
        "phone" => "9054........."
    )
));

?>

Python Kod Örneği

# -*- coding: utf-8 -*-
# -----------------
# Eurotel Web Framework
# -----------------

from json import loads, dumps
import logging
import httplib
from urlparse import urlparse

SMS_TIMEOUT = 30
SMS_USER = "USERNAME"
SMS_PASSWORD = "PASSWORD"
SMS_HEADER = "HEADER"
SMS_URL = "https://portal.roitel.com.tr/sms/api"
LOG_FILE = "/tmp/sms.log"
LOG_LEVEL = logging.DEBUG
logging.basicConfig(format="%(asctime)s;%(levelname)s;%(message)s", filename=LOG_FILE, level=LOG_LEVEL)


def api_send_sms(phones, text):
    msg = text.encode('utf-8')

    data = {
        "username": SMS_USER,
        "password": SMS_PASSWORD,
        "header": SMS_HEADER,
        "action": "send_sms",
        "phones": phones,
        "text": msg
    }
    try:
        prs = urlparse(SMS_URL)
        conn = httplib.HTTPSConnection(prs.netloc, timeout=SMS_TIMEOUT)
        conn.request(method="POST",
                     url=prs.path,
                     body=dumps(data),
                     headers={'Content-Type': 'application/json; charset=UTF-8'})
        response = conn.getresponse()
        if response.status != 200:
            result = False
            logging.error("Can not access %s for sending SMS to %s, error code: %s, reason:%s" % (
                SMS_URL, phone, response.status, response.reason
            ))
        else:
            answer_raw = response.read()
            logging.debug("Result for SMS to %s response %s" % (phone, answer_raw))
            answer = loads(answer_raw)
            if answer['success']:
                logging.info("SMS Sent to %s successfully" % phone)
                result = True
            else:
                result = False
                logging.error("SMS is not accepted to phone %s, message:%s" % (phone, answer['message']))
    except:
        result = False
        logging.exception("Can not send sms to %s", phone)
    return result


if __name__ == '__main__':
    phones = [{"phone": "9054......"}]
    api_send_sms(phones, "Deneme mesajıdır.")

.NET Kod Örneği

using System;
using System.Collections.Generic;
using System.Net;
using System.IO;
using System.Web.Script.Serialization;

namespace RoiSMSClient
{
    class PhoneItem{
        public string phone { get; set; }
        public string api_id { get; set; }
    }

    class SMSMessage{
        public string username { get; set;}
        public string password { get; set;}
        public string header { get; set;}
        public string action { get; set;}
        public string text { get; set;}
        public List<PhoneItem> phones { get; set; }
    }

    class MainClass
    {
        public static void Main (string[] args)
        {
            Console.WriteLine("Connecting");
            var httpWebRequest = (HttpWebRequest)WebRequest.Create("https://portal.FIRMA.com.tr/sms/api ");
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "POST";

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                string json = new JavaScriptSerializer().Serialize(new SMSMessage()
                {
                    username = "your_portal_username",
                    password = "your_portal_password",
                    header = "your_header_or_phone_number",
                    action = "send_sms",
                    phones = new List<PhoneItem>(){
                        new PhoneItem(){ phone = "target_phone_number", api_id = "123"}
                    },
                    text = "Deneme"
                });

                streamWriter.Write(json);
                streamWriter.Flush();
                streamWriter.Close();

                var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
                using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
                {
                    var result = streamReader.ReadToEnd();
                    Console.WriteLine(result);
                }
            }
        }
    }
}

Detaylı bilgi mi istiyorsunuz?

Bize lütfen destek hattımızdan ulaşın