Руccкий

Интерфейс программирования приложений (SMS API)

Endpoints

Первое, что вы должны знать, это куда направить Ваш API запрос. My-Cool-SMS принимает GET, POST и JSON запросы через порт 80 или SSL через порт 443. Вы можете подключиться к следующим адресам соответственно.

HTTP

API endpoint для HTTP запросов:
http://www.my-cool-sms.com/api-socket.php

HTTPS

Если Вам требуется безопасное соединение вы можете использовать API с помощью SSL, 443 порт.
API endpoint для HTTPS запросов:
https://www.my-cool-sms.com/api-socket.php

API компоненты

У My-Cool-SMS есть два вида компонентов. Фунции и callbacks.

Функции

Функции используются для запроса отправки сообщений SMS, поиска Вашего ​​баланса или получения отчетов о доставке. Функция может быть запущена с помощью структуры HTTP запроса, как описано ниже.

Callbacks

Callback (функция обратного выызова) - это запрос, посланный от My-Cool-SMS на ваш сервер. Функция callback запускается в режиме реального времени, когда такие имеют место такие события, как получение SMS или новый отчет о доставке и передается обратно на URL сервера для обработки.

Структура запроса

Вы можете отправлять запросы через HTTP POST, GET или JSON. Хотя My-Cool-SMS не остановливает Вас от использования POST или GET, мы настоятельно рекомендуем использовать JSON запросы. JSON это легкий формат обмена данными, который легко читается и пишется и легко анализируется и создается для языка программирования вашего выбора.
Прежде всего, JSON очень устойчив при отправке Unicode SMS сообщений и не требует для реализации сложного кодирования и декодирования UCS2. Если Вам когда-либо приходилось работать с Unicode, UCS2 или GSM7 кодированием и декодированием кросс-сервера, вы наверняка знаете, что это счастье, когда есть возможность этого избежать. Вы можете узнать больше о JSON здесь.

Реквизиты входа в систему и переключатели функций

Запрос к My-Cool-SMS API должен всегда содержать Ваше имя пользователя, пароль и переключатель функций, который говорит API, что вы хотите сделать.

JSON

Давайте посмотрим на пример JSON, который вы будете использовать при поиске Вашего баланса:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

Один и тот же запрос с POST и GET будет выглядеть так:
username=xxx&password=yyyy&function=getBalance

Обязательные и произвольные параметры

В то время как имя пользователя, пароль и параметры функций требуются всегда, каждая функция может иметь обязательные и необязательные параметры, которые, возможно, также будет нужно указывать.
Запрашивая отчет о доставке, например, укажите для какого SMS Вы его запрашиваете. Для этого вы просто добавляете дополнительный параметр, в данном случае "ID".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Структура ответа

API запрос всегда возвращает объект JSON. Каждый ответ содержит параметр успеха, который указывает, может ли запрос быть обработан успешно или нет. Вы должны обрабатывать ответ в соответствии с тем, как настроен параметр, "верно" или "неверно" .

Успешный ответ

Успешный запрос к функции getDeliveryReport вернет объект JSON, вроде следующего:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Каждая функция имеет различные параметры ответа. Вы можете просмотреть подробные детали здесь.

Неправильный ответ

Скажем, у вас есть опечатка в параметре пароля. В этом случае API вернет объект JSON со следующей структурой:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
Вы можете ожидать трехзначный ErrorCode (код ошибки) и описание, которое поможет вам определить, проблему, когда параметр успеха "неверный".

Обработка ответов

Прочитайте ответы

Ответ API всегда отправляется в формате JSON. Все, что нужно сделать это преобразовать данные ответа в объект. Это достаточно просто, так как прктически каждый язык программирования предлагает собственные методы как это сделать.
Чтобы найти больше информации о JSON для языка программирования вашего выбора: прокрутите немного вниз эту страницу.
Вам нужно сделать примерно следующее с PHP, чтобы обработать ответ API:
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...

// Now simply convert the response into a PHP object
$oResponse = json_decode($response);

//$oResponse is now an object

if($oResponse->success) {
    //Great. It worked!
    echo($oResponse->smsid);
    echo($oResponse->status);
} else {
    //Oops. something went wrong.
    echo($oResponse->errorcode);
    echo($oResponse->description);
}

Обработка callbacks

Прочитайте вводные данные

Callbacks не сильно отличаются от ответов на функции, и вы можете конвертировать их в объект, как указано выше. Одинственное, что Вам нужно будет знать, это, как работать с HTTP Raw Request Input. Callback не отправляется ни через GET, ни через POST, а только, как HTTP Raw Data, о чем вы можете прочитать далее.
Вам нужно сделать примерно следующее с PHP, чтобы обработать callback запрос:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
В Java примерно то же самое:
InputStream body = request.getInputStream();
Имейте в виду, что какой язык программирования вы бы ни использовали, вы можете прочитать вводные данные лишь один раз. Сохраняйте данные где-то еще для обработки.

Примеры PHP

Функция: sendSms

Давайте посмотрим, как фактически выглядит код для отправки SMS. Вам нужно использовать API с наименьшим количетвом трок кода, насколько это возможно. Итак, как бы это работало?
<?php

$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

?>
Довольно хорошо? Если это все, что вам нужно, просто скачайте стартовый комплект PHP SMS, посмотрите на комментарии в коде, запустите send-sms.php и вы готовы.

Стартовый комплект PHP SMS

Загрузить стартовый комплект PHP SMS
Стартовый комплект содержит готовые к использованию кода для вызова API функций и обработки

Для технарей

Если вы разбираетесь в технологиях вы можете посмотреть на класс, который обрабатывает запрос:
<?php

class MyCoolSMS {

    function __construct() {
    
        $this->username = 'xxx'; //your username here...
        $this->password = 'yyy'; //your password here...
        $this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
    }

    public function sendSms($number, $message, $senderid='MyNumber') {
    	
        return($this->request(json_encode(array(
            'username' => $this->username,
            'password' => $this->password,
            'function' => 'sendSms',
            'number' => $number,
            'senderid' => $senderid,
            'message' => $message
        ))));
        
    }
    
    public function getDeliveryReport() {}
    
    public function getBalance() {}
    
    //add more functions as you please...
    
    private function request($oRequest) {
    
        $oCurl = curl_init($this->endpoint);
        curl_setopt($oCurl, CURLOPT_POST, 1);
        curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
        curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
        
        if(curl_errno($oCurl) == 0) {
            $oResponse = json_decode(curl_exec($oCurl));
            if(!is_object($oResponse)) {
                $oResponse = $this->getError('001', 'Bad Response');
            }
        } else {
            $oResponse = $this->getError(curl_error($oCurl));
        }		
    
        curl_close($oCurl);
        
        return $oResponse;
    
    }
	
    private function getError($error = '000', $description = NULL) {

        return json_encode(array(
            'success' => false,
            'error' => $error,
            'description' => $description,
        ));
        
    }

}

?>
Сохранить, вышеуказанный код в файле с именем MyCoolSMS.class.php и начать использовать его следующим образом:
<?php

require_once('MyCoolSMS.class.php');

$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

if($oResponse->success) {
    //Great, it worked!
    print_r($oResponse);
} else {
    //Oops, Something went wrong...
    print_r($oResponse);
}

?>

Вы готовы к старту!

Давайте посмотрим на функцию API и документацию callback.
Мы что-то пропустили? У Вас есть вопросы? У Вас есть совет или что-то, что мы могли бы здесь добавить? Если так, свяжитесь с нами!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Português
繁体中文