SMS API (Краткая спецификация SMS-платформы А1агрегатор)

При получении запроса от абонента, платформа А1 вызывает URI вашего скрипта-обработчика.

Пример:

http://www.my_site.ru/sms.php?date=2008-03-28+17%3A13%3A33&msg=prefix+%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5&msg_trans=prefix+soobschenie&operator_id=120&country_id=45909&user_id=79099080375&smsid=5094&cost=0.015&cost_rur=0.54&test=1&num=1121&retry=1&try=2&ran=7& skey=098f6bcd4621d373cade4e832627b4f6&sign=ceec8c15aea1bbe12379f35ffeae38ae

Здесь:

1. date – дата и время сообщения в системе a1agregator.ru. В данном примере 2008-03-28+17%3A13%3A33 – это 28 марта 2008 года в 17:13:33
2. country_id - идентификатор страны
3. msg – сообщение, которое отправил абонент, в примере «prefix сообщение» (prefix+%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5)
4. msg_trans – транслитерация сообщения, в примере «prefix soobschenie»
5. operator_id – числовой идентификатор оператора, в примере 120 (Билайн)
6. user_id – телефон абонента, отправившего смс, в примере 7909908037
7. smsid – идентификатор сообщения в системе а1агрегатор, в примере 5094
8. cost_rur – сумма, которая зачисляется на счет партнера в рублях, в примере 0.54
9. cost – параметр, определяющий сумму, которая зачисляется на счет партнера в usd, переведенная по курсу последней выплаты, в примере 0.015. Этот параметр носит только информативный характер. Сумма за эту смс при выплате в WMZ будет скорректирована по курсу WM на день выплаты.
10. test – необязательный параметр, приходит только при тестовой смс. Если он равен единице значит смс тестовая.
11. num – короткий номер, на который абонент отправлял запрос, в примере 1121
12. retry – параметр повтора смс, если равен единице значит смс повторная. При повторной смс все другие параметры дублируют первую непрошедшую смс.
13. try – Порядковый номер попытки отправки смс сообщения через разные прокси сервера. SMS можно также считать повторной SMS с параметрами retry =1 или try<>1.
14. ran – параметр надежности абонентского номера - цифра от 1 до 10, которая показывает степень доверия и обеспеченности деньгами к абон. номеру. 1-4 - ненадежные, 5-7 - средние, 8-10 - надежные. В примере 7
15. skey – это последовательность символов, которая кодируется по алгоритму MD5, передается в случаи использования параметра «Секретный ключ», в примере передается слово test. Применяется в целях дополнительной безопасности. Указывать секретный ключ необязательно.
16. sign – это последовательность символов, которая кодируется по алгоритму MD5, передается всегда. Последовательность получается путем последовательного соединения параметров:

• date
• msg_trans
• operator_id
• user_id
• smsid
• cost_rur
• ran
• test
• num
• country_id
• key (ключ, который вы вводите в настройках сервиса)

Применяется в целях повышения безопасности.

smsid – используется в ответе, обязательный для ответа параметр.

Все остальные параметры необязательны для ответа и являются информационными

Информационные параметры вы можете использовать при создании сервиса.

Пример формата ответа:

smsid: 5094
status: reply

Usluga oplachena.

1. smsid – идентификатор сессии, он передается в http-запросе от платформы a1agregator.ru при вызове вашего скрипта-обработчика.
2. status – статус обработанного сообщения. Может принимать значение reply или ignore. В первом случае платформа MP считает запрос обработанным и перенаправляет принятый ответ сервиса абоненту. Во втором случаи ответ не перенаправляется.
3. Пустая строка
4. Ответ для абонента. Для обозначения новой строки используйте вертикальную черту «|». Внимание: некоторые ОСС и некоторые модели мобильных телефонов могут неправильно воспринимать знак новой строки.

Пример скрипта на PHP:

<?
$smsid = $_GET['smsid'];
echo "smsid:$smsid\n";	
echo "status:reply\n";
echo "\n";
echo "Usluga oplachena.\n";
?>

Пример скрипта на PHP(с использованием параметра skey):

<?
$smsid = $_GET['smsid'];
$skey = $_GET['skey'];
$secretkey = "test";
if (md5($secretkey) != $skey) header("HTTP/1.0 404 Not Found");
echo "smsid:$smsid\n";	
echo "status:reply\n";
echo "\n";
echo "Usluga oplachena.\n";
?>

Пример структуры БД

  CREATE TABLE `inbox` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `date` datetime NOT NULL COMMENT 'дата получения sms',
  `msg` varchar(255) NOT NULL COMMENT 'сообщение абонента',
  `msg_trans` varchar(255) NOT NULL COMMENT 'транслитерированное сообщение',
  `operator_id` int(10) unsigned NOT NULL COMMENT 'id оператора',
  `user_id` bigint(20) unsigned NOT NULL COMMENT 'номер абонента',
  `smsid` int(10) unsigned NOT NULL COMMENT 'id смс',
  `cost_rur` float(15,4) unsigned NOT NULL COMMENT 'сумма в рублях',
  `cost` float(15,4) unsigned NOT NULL COMMENT 'информационный параметр (по курсу последней выплаты)',
  `test` tinyint(1) unsigned NOT NULL COMMENT '1 - тестовая смс',
  `num` varchar(20) NOT NULL COMMENT 'короткий номер',
  `skey` char(32) NOT NULL COMMENT 'секретный ключ md5',
  `sign` char(32) NOT NULL COMMENT 'md5 от параметров',
  `ran` tinyint(1) unsigned NOT NULL,
  `answer` text NOT NULL COMMENT 'ответ сервиса без заголовка',
  PRIMARY KEY  (`id`),
  UNIQUE KEY `smsid` (`smsid`))

Для описания типа исходящего используется опциональный заголовок: content-type. Для поля content-type по умолчанию принимается значение ‘text/plain’, и при разработке обычных SMS-сервисов его можно не указывать.

Тип ‘flash-msg’ схож с типом ‘text/plain’. Его отличие от ‘text/plain’ заключается в том, что такое сообщение после получения телефоном абонента будет автоматически выведено на экран и не будет сохранено в его памяти.

Ограничения: Для корректного отображения на экране телефона текст сообщения должен умещаться в одно СМС.

Еще одним допустимым значением для поля content-type является ‘wap-push’. Это значение применяется для отправки абоненту

WAP-ссылок на какие-либо ресурсы, например на контент. При этом тело секции должно содержать ссылку в формате:

<url>#<описание_ссылки>

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

Пример:

<?php
echo "smsid:$smsid\n";
echo "status:reply\n";
echo "content-type:wap-push\n";
echo "\n";
echo "wap.yoursite.com#Super site";
?>

Для того чтобы сообщение было направлено на определенный порт телефона, который, например, прослушивается java-приложением, следует воспользоваться типом ‘app-port-long’. При этом тело секции должно выглядеть следующим образом:

<порт_получателя>[:<порт_отправителя>]#<текст>

<порт_отправителя> является необязательным параметром, если он опущен, будет использован порт 16000. <текст> - это данные, которые будут переданы в <порт_получателя> как есть.

Если приведенных типов недостаточно, и требуется послать сообщение с использованием определенного UDH, например EMS-сообщение, то следует воспользоваться типом ‘ems’. В данном случае тело секции должно содержать последовательность байт (UDH+текст), представленную в виде строки шестнадцатеричных цифр. Эта строка будет преобразована в байты и отправлена с флагом UDH.

Ограничение: длина данных после преобразования в байтовую последовательность не должна превышать 140 байтов.