Сам справлюсь (sms-шлюз, sms-транспорт, API)


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

Техническое описание

Данная услуга, по сути, является СМС-шлюзом, что позволяет программисту на стороне партнера создать собственный скрипт обработки смс сообщений. В случае использования данной услуги, наш сервер выступает в роли транзитного, что позволяет партнеру отправлять собственное сообщение в ответном смс пользователю. Суть работы услуги заключается в том, что все смс сообщения приходящие на наш сервер передаются на скрипт партнера вместе со всеми сопутствующими данными, а возвращаемый скриптом партнера текст, отсылается в виде смс сообщения обратно пользователю. Название услуги обусловлено тем, что весь алгоритм обработки сообщений должен создать программист партнера сам, что достаточно трудоемко и требует специальной подготовки и знаний одного из скриптовых языков.

В рамках смс биллинга используются префиксы партнеров.
Префикс – это и есть тот текст, который абонент должен отправить в смс. В результате того, что одни и те же короткие номера используются разными компаниями, существуют префиксы идентифицирующие компании-провайдеры услуг. Такие префиксы называются корневыми. Нашему биллингу присвоены следующие корневые префиксы: ptw, 012, 914 и 915. В ходе подключения других стран этот набор, возможно, будет дополняться.
Таким образом, чтобы смс попало на нашу платформу необходимо, что бы тело смс содержало корневой префикс, а для того чтобы мы смогли идентифицировать партнера, так же необходим префикс партнера.

Префиксы партнеров могут быть длиной от одного символа и больше. С учетом корневого префикса (3 символа), длина текста смс сообщения (с учетом длины префикса партнера) будет от 4 символов и больше. Получение префикса, возможно после согласования с администрацией. Необходимо письменно обратиться в тех.поддрежку с указанием проекта, необходимых стран и коротких номеров.

Сфера применения

Обработка заявок на какие-либо услуги (ответ по контактной информации посетителя в СМС);
Формирование на своем сайте ответных СМС;
Изменение на досках объявлений аватара, статуса объявления, его рейтинга и цвета;
Размещение на досках платных объявлений;
Прикрепление на досках объявлений тем на определенный срок, доступ в VIP-раздел;
В разделах знакомств - VIP-статус анкеты, поднятие ее рейтинга;
Отправка подарков другим пользователям сервисов знакомств, получение доступа к их закрытой информации;
В тематических разделах постановка оценок фотографиям, размещение их на главной странице;
Заказ столиков в клубах, ресторанах, бронь билетов в кино и т.д.;
Оплата в он-лайн играх оружия, статуса, валют и т.д.;
Пополнение средств виртуальных счетов;
Оплата услуг по размещению рекламы на своем сайте;
Получение паролей, генерируемых на стороне Партнера;

Описание протокола и передаваемые параметры

Работа строится следующим образом: партнер размещает у себя на сайте информацию о том, какой текст смс необходимо отправить абоненту и на какой номер. Текст смс будет зависеть от корневого префикса номера и выглядеть например так: 218<префикс партнера> для номеров с корневым префиксом 218. Префикс партнера может быть как числовым так и буквенным - по желанию партнера.
В некоторых странах существует дополнительный префикс, например RRR, GET, dx. Дополнительный префикс пишется перед корневым префиксом платформы. Т.е. вот так: RRR 915, GET 915, dx012. Следует помнить, что дополнительный префикс передается на сервер партнера отдельно от тела смс - в отдельном параметре. Это удобно при организации работы обработчика партнера.

Если нужно в теле смс передать какие либо дополнительные параметры, например ID пользователя, то данную информацию нужно отделить от статического идентификатора например символом "*" , "-", "+" или каким либо еще. Тогда, если например нужно передать ID пользователя равным 123, префикс партнера 3, а разделитель "+", то текст смс будет вида 2183+123.

После того как абонент отправляет смс, оно, через оператора, попадает на нашу систему. Мы определяем партнера и далее это смс вместе передается методом POST на указанный партнером URL.

Передаваемые параметры

sms_id - уникальный идентификатор смс сообщения;
sms_body - текст сообщения абонента;
site_service_id - id услуги под которым создана услуга "Сам справлюсь" в личном кабинете;
user_num - номер телефона абонента вида 380949965236;
num - короткий номер, на который абонент отправил смс;
cpref - дополнительный префикс. Параметр пустой если данный короткий номер не содержит дополнительного префикса. Сдержит номер дополнительный префикс или нет можно узнать из XML файла либо на станице Тарифов;
operator_id - идентификатор оператора;
operator_name - имя оператора;
sms_price - стоимость смс сообщения для абонента c НДС;
sms_currency - кодовое обозначение валюты, в которой передано значение параметра price, в соответствии с международным стандартом ISO-4217 Примеры обозначений: RUB, USD, UAH, т.д.;
partner_cost - доход партнера.
partner_currency - валюта дохода партнера;
secret_word - этот параметр посылается как функция md5('Секретное слово'), где 'Секретное слово' - это некая комбинация символов указанная партнером у себя в личном кабинете.
secret_key - это контрольное значение, вычисленное на основе основных параметров, а также значения secret_word. Служит для проверки валидности запроса. Формула вычисления контрольного значения:
secret_key = md5(sms_id + sms_body + site_service_id + operator_id + num + sms_price + 'Секретное слово').В этом выражении знак "+" означает операцию конкатенации.

Если в течение 30 сек наша платформа не получила ответ от сервера партнера, абоненту отсылается сообщение о недоступности сервера партнера.

Параметры ответа

После передачи параметров, система ожидает ответ от сервера партнера в формате:
sms_id:уникальный идентификатор смс сообщения "\n";
response:ответ партнера в формате UTF-8 "\n";
error:0 либо 1; - параметр, который указывает, что абонент, отославший смс, допустил ошибку в сообщении - например неправильно указал код покупаемого продукта. Параметр принимает значение "1" - если в поле response пересылается сообщение об ошибке. Если параметру будет присвоен "0", то сообщение считается обычным ответом. Указание "error=1" сообщению об ошибке является обязательным условием.
Допустимое кол-во символов в ответе партнера 70 Кириллица либо 160 Латиница.

Пример формирования ответа в обработчике на PHP:
<?php
echo "sms_id:$_POST['sms_id']\n";
echo "response:Текст ответа\n";
echo "error:0";
?>

После обработки и отправки партнером ответного сообщения абоненту, партнеру формируется сообщение со статусом доставки, которое может быть «1» (если сообщение доставлено и оплачено) или «0» (если не доставлено или у абонента недостаточно денег на счету). Данную проверку производит оператор на своей стороне. В случае если у абонента недостаточно денег на счету, сообщение ему не доставляется оператором. В замен отправленного смс, оператор посылает абоненту свое стандартное смс с текстом "У вас не достаточно денег на счету", либо абоненту вообще не передается ни каких сообщений.

Параметры статуса доставки и оплаты

sms_id - уникальный идентификатор смс;
status - результат оплаты смс абонентом. Принимает значение 1, если сообщение доставлено и оплачено, или 0 - если не оплачено либо не доставлено;
user_num - номер телефона абонента вида 380949965236;
site_service_id - id услуги под которым создана услуга "Сам справлюсь" в личном кабинете.

Партнер обязан проверять статус т.к. если, к примеру, пришло сообщение с параметром status=0, то услуга не должна быть предоставлена абоненту, т.к. смс не оплачена и партнеру не будет начислен партнерский заработок. При разработке алгоритма, следует проверять status и предусмотреть алгоритм "отката" услуги если смс не оплачено.
ВАЖНО: отвечать на этот запрос - не нужно. Информация в запросе исключительно для вас. Наш обработчик уже не будет ждать от вас никаких ответов.