Документация API

Прием сообщений

Для того чтобы проект, подключенный к сервису, имел возможность получения сообщений, требуется организовать специальный пользовательский программный интерфейс (API), и разместить его на веб-сервере.

После поступления сообщения в адрес проекта, сервис направляет HTTP запрос типа POST на пользовательский API, указанный в настройках проекта, передавая ряд параметров:

projectmd5 — md5 хеш строки, полученной из конкатенации ряда других параметров: apikeymd5, sessionid, projectid, receiver, sender, fulltext. Данный параметр применяется для проведения процедуры авторизации сервиса на стороне API. Значение переменной apikeymd5 представляет собой md5 хэш от ключа API, указанного в конфигурации проекта. Его следует определить в API.

sessionid — Уникальное переменное значение, используемое для идентификации запроса. Значение этого параметра изменяется в каждом запросе.

projectid — Идентификатор зарегистрированного на сервисе проекта, в адрес которого было направлено сообщение.

receiver — Сервисный номер телефона, на который было отправлено распознанное сообщение отправителем. Номер представляется в международном формате, и начинается со знака +.

sender — Номер телефона отправителя, от имени которого было отправлено распознанное сообщение. Как и в предыдущем случае, номер начинается со знака +.

prefix — Префикс (ключевое слово) по которому было произведено распознавание сообщения. Префикс равен пустоте в том случае, если сообщение было принято проектом, использующим выделенный сервисный номер.

text — Текст в кодировке UTF-8, содержащий полученное сообщение, за исключением префикса. В случае если сообщение было принято проектом, использующим выделенный сервисный номер, значение данного параметра идентично параметру fulltext.

fulltext — Текст в кодировке UTF-8, содержащий полученное сообщение, включающее в себя префикс.

После поступления и обработки запросов, пользовательский API обязуется сообщить сервису об успехе операции, возвратив текст, содержащий специальный тег:

<SMS /> или <SMS></SMS>

Помимо этого, имеется возможность отправки ответного сообщения отправителю без использования дополнительного запроса к сервису. Для этого, пользовательский API должен возвращать текст сообщения, заключенный в специальные теги:

<SMS>Текст ответного сообщения</SMS>

Длина текста ответного сообщения ограничена 765 символами, в случае если сообщение содержит только латинские буквы, и 335 символами, если сообщение содержит кириллицу.

В том случае, если удовлетворительный ответ не был получен от пользовательского API, сервис будет пытаться отправить запрос снова еще 150 раз с интервалом в 10 минут, после чего сообщение удалится из очереди.

Протестировать работоспособность пользовательского API на прием возможно без отправки сообщения на сервисный номер. Для этого следует перейти в список зарегистрированных проектов и выбрать действие «проверить» для соответствующего проекта. В форме нужно указать номер телефона, от имени которого производится проверка. Текст сообщения указывать не обязательно.

Отметим, что в случае, если проверяется проект, использующий префикс, вводить его в поле текста сообщения не требуется. Префикс добавляется к тексту сообщения автоматически.

Ниже представлен пример реализации пользовательского API с использованием языка программирования PHP.

Пример пользовательского API на языке PHP
<?php

/*
    projectmd5  - md5 хэш запроса
    sessionid   - Идентификатор сессии
    projectid   - Идентификатор проекта
    receiver    - Сервисный номер
    sender      - Номер отправителя
    prefix      - Префикс проекта
    text        - Текст сообщения (без префикса)
    fulltext    - Полный текст сообщения
*/

// Хэш секретного ключа API
$apikeymd5 = '53f28c002c7e258540a2038300045804'; // md5('MyApiKey')

// Валидация данных
if (!isset($_POST['projectmd5']) 
    OR !isset($_POST['sessionid']) 
    OR !isset($_POST['projectid']) 
    OR !isset($_POST['receiver']) 
    OR !isset($_POST['sender']) 
    OR !isset($_POST['prefix']) 
    OR !isset($_POST['fulltext']) 
    OR !isset($_POST['text']))
{
    // Отправка ошибки валидации
    exit('Validation error');
}

// Проверка хэша
if (md5($apikeymd5
    .$_POST['sessionid']
    .$_POST['projectid']
    .$_POST['receiver']
    .$_POST['sender']
    .$_POST['fulltext']) != $_POST['projectmd5'])
{
    // Отправка ошибки хэша
    exit('Hash error');
}

// Обработка сообщения
$response = process($_POST['sender'], $_POST['prefix'], $_POST['text']);

// Отправка ответного сообщения
exit($response);


// Функция обработки сообщения
function process($sender, $prefix, $text)
{
    // Ответное сообщение
    return '<SMS>Текст ответного сообщения</SMS>';
}

?>

Отправка сообщений

Для того чтобы осуществлять отправку сообщений через сервис, следует отправить HTTP запрос типа POST на адрес программного интерфейса сервиса: http://sms.hsdn.org/api.sme.

Отправляемый запрос в своем теле должен содержать ряд параметров, позволяющих авторизоваться на сервисе и доставить сообщение до адресата. В запросе должны передаваться следующие параметры:

login — Логин пользователя, зарегистрированного на сервисе.

passwordhash — md5 хэш пароля зарегистрированного пользователя.

receiver — Сервисный номер телефона, используемый для отправки сообщения. В случае, если у пользователя имеется выделенный номер, отправка сообщения допускается и от его имени. Номер указывается в международном формате, и начинается со знака +.

recipient — Номер телефона получателя сообщения. Как и в предыдущем случае, номер указывается в международном формате, и начинается со знака +. Стоит отметить, что отправка сообщений разрешена только на номера, принадлежащие российским операторам.

flash — Устанавливает, отправлять ли сообщение в формате Flash-SMS. Flash-SMS — это сообщение, сразу отображаемое при получении на экране телефона. Для включения данного формата, значение параметра должно быть 1.

text — Текст отправляемого сообщения. Длина текста ограничена 765 символами, в случае если сообщение содержит только латинские буквы, и 335 символами, если сообщение содержит кириллицу.

Текст сообщения должен быть передан в кодировке UTF-8, в противном случае интерфейсом будет возвращена ошибка с кодом 21.

После отправки запроса происходит его проверка, после чего программный интерфейс сервиса вернет код состояния операции. В случае, если был возвращен код 20, операция отправки сообщения считается успешной. В других случаях интерфейс возвращает коды, соответствующие ошибкам, описанным ниже:

10 — запрос типа POST не получен
11 — ошибка авторизации на сервисе
21 — критическая ошибка отправки сообщения
22 — превышено число отправляемых сообщений
30 — не передан параметр recipient или содержит пустоту
31 — неверный формат номера телефона, указанного в параметре recipient
32 — номер телефона, указанный в параметре recipient, не является допустимым
40 — не передан параметр receiver или содержит пустоту
41 — неверный формат номера телефона, указанного в параметре receiver
42 — сервисный номер, указанный в параметре receiver, не является верным
50 — не передан параметр text или содержит пустоту
51 — длина текста, указанного в параметре text, превышает допустимую

Количество отправляемых запросов не должно превышать 10 за 1 минуту. В случае превышения допустимого количества отправленных сообщений, интерфейс возвратит ошибку с кодом 22.

Ниже представлен пример реализации отправки запроса на программный интерфейс сервиса с использованием языка программирования PHP.

Пример отправки сообщения через API сервиса на языке PHP
<?php

// Адрес API сервиса
$apiaddress = 'http://sms.hsdn.org/api.sme';

$postdata = array
(
    // Логин
    'login' => 'myusername',

    // Хэш пароля
    'passwordhash' => '48503dfd58720bd5ff35c102065a52d7', // md5('MyPassword')

    // Сервисный номер
    'receiver' => '+70000000000',

    // Номер получателя
    'recipient' => '+79012345678',

    // Текст сообщения
    'text' => urlencode('SMS сообщение')
);

// Инициализация CURL
$ch = curl_init();

// Установка опций CURL
curl_setopt($ch, CURLOPT_URL, $apiaddress);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

// Отправка запроса
$status = curl_exec($ch);

// Закрытие CURL
curl_close($ch);

// Проверка результата отправки
if ($status != 20)
{
    // Ошибка отправки
    exit('Send error: '.$status);
}

// Отправка успешна
exit('Send OK');

?>