документація API
прийом повідомлень
Для того щоб проект, підключений до сервісу, мав можливість отримання повідомлень, потрібно організувати спеціальний призначений для користувача програмний інтерфейс (API), і розмістити його на веб-сервері.
sessionid - Унікальне змінне значення, яке використовується для ідентифікації запиту. Значення цього параметра змінюється в кожному запиті.
prefix - Префікс (ключове слово) по якому було вироблено розпізнавання повідомлення. Префікс дорівнює порожнечі в тому випадку, якщо повідомлення було прийнято проектом, що використовують виділений сервісний номер.
text - Текст в кодуванні UTF-8. містить отримане повідомлення, за винятком префікса. У разі якщо повідомлення було прийнято проектом, що використовують виділений сервісний номер, значення даного параметра ідентично параметру fulltext.
fulltext - Текст в кодуванні UTF-8. містить отримане повідомлення, що включає в себе префікс.
Після надходження і обробки запитів, призначений для користувача API зобов'язується повідомити сервісу про успіх операції, повернувши текст, що містить спеціальний тег:
Крім цього, є можливість відправки листа у відповідь відправнику без використання додаткового запиту до сервісу. Для цього, призначений для користувача API повинен повертати текст повідомлення, укладений в спеціальні теги:
Довжина тексту листа у відповідь обмежена 765 символами, в разі якщо повідомлення містить тільки латинські букви, і 335 символами, якщо повідомлення містить кирилицю.
У тому випадку, якщо задовільний відповідь не була отримана від призначеного для користувача API, сервіс буде намагатися відправити запит знову ще 150 разів з інтервалом в 10 хвилин, після чого повідомлення віддалиться з черги.
Відзначимо, що в разі, якщо перевіряється проект, який використовує префікс, вводити його в поле тексту повідомлення з відповіді. Префікс додається до тексту повідомлення автоматично.
Нижче представлений приклад реалізації користувацького API з використанням мови програмування PHP.
Приклад API користувача на мові 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 '
>
Відправлення повідомлень
login - Логін користувача, зареєстрованого на сервісі.
passwordhash - md5 хеш пароля зареєстрованого користувача.
text - Текст повідомлення, що відправляється. Довжина тексту обмежена 765 символами, в разі якщо повідомлення містить тільки латинські букви, і 335 символами, якщо повідомлення містить кирилицю.
Текст повідомлення повинен бути переданий в кодуванні UTF-8. в іншому випадку інтерфейсом буде повернуто помилку з кодом 21.
Після відправлення запиту відбувається його перевірка, після чого програмний інтерфейс сервісу поверне код стану операції. У разі, якщо був повернутий код 20. операція відправки повідомлення вважається успішною. В інших випадках інтерфейс повертає коди, відповідні помилок, описаним нижче:
Кількість відправлених запитів не повинно перевищувати 10 за 1 хвилину. У разі перевищення допустимої кількості відправлених повідомлень, інтерфейс поверне помилку з кодом 22.
Нижче представлений приклад реалізації відправки запиту на програмний інтерфейс сервісу з використанням мови програмування PHP.
Приклад відправки повідомлення через API сервісу на мові PHP
$ 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');