====== Услуга смс:транзит ====== ===== Общая информация ===== Услуга **смс:транзит** — это решение, которое позволяет владельцу сайта самостоятельно определить абсолютно все аспекты работы своей системы. Сама по себе услуга крайне проста, но в силу своей мощности и открытости требует от владельца самостоятельной реализации всех необходимых элементов на своей стороне. Предел возможностей услуги в данном случае ограничен только его техническими возможностями и фантазией. Используя **смс:транзит** как отправную точку, владелец получает все ресурсы для разработки своего собственного SMS-сервиса любой направленности, будь то система разграничения доступа, чат или служба распространения мобильного контента. Владелец сам решает, как обрабатывать приходящие ему сообщения и какой текст отправлять в ответ. **Услуга подключается индивидуально.** Для подачи заявки на подключение необходимо обратиться к менеджеру по ICQ 570342641 или на электронный адрес sales@smscoin.com. В письме необходимо указать следующие данные: * адрес сайта, на который планируется установить **смс:транзит**; * подробное описание прокета; * предполагаемый оборот (совокупную стоимость SMS-сообщений, которые будут отправлены на Ваш сервис его пользователями). В течение двух рабочих дней наш менеджер отправляет ответное письмо на указанный электронный адрес с разрешением на подключение данной услуги или отказом и дальнейшими указаниями для ее подключения. ===== Алгоритм работы ===== - Сетевой ресурс, использующий услугу **смс:транзит**, на этапе оплаты выводит инструкцию по отправке SMS. ((Внешний вид формы может различаться в зависимости от реализации)), которая включает в себя: * короткий номер, на который необходимо отправить SMS; * текст SMS-сообщения, состоящий из: * префикса; * идентификатора **смс:транзита** (ID смс:транзит); * дополнительных данных, определяемых владельцем сетевого ресурса. * стоимость SMS, которая в зависимости от страны может как включать, так и не включать НДС; * указание о дополнительных налогах и сборах, которые могут быть установлены в выбранной стране; * дополнительная информация: правила составления текста SMS, условия ответственности, информация о технической поддержке и пр. - Отправленное пользователем SMS через оператора (и агрегатора) поступает на наш сервер. Этому SMS-сообщению присваивается уникальный идентификатор сообщения **msgid**. - Согласно тексту SMS определяется соответствующий **смс:транзит** и проверяется: * статус оплаты принятого SMS оператором сотовой связи; * если **смс:транзит** использует **фиксированный тариф**, то проверяется соответствие стоимости принятого SMS и стоимости, установленной в настройках услуги - она не должна быть оплачена по меньшему тарифу (при этом по большему допускается). - Наш сервер с помощью HTTP-запроса вызывает обработчик по URL-адресу, указанному в настройках в поле **Result URL**, и передает ему необходимые [[#Реализация обработчика Result URL|данные]], которые владелец сервиса обрабатывает в соответствии с реализованной у него логикой. Если обработчик по URL-адресу оказывается недоступен (HTTP-статус обращения отличается от 200 OK), запрос будет повторен еще дважды. При этом, уже после первой неудачной попытки на технический электронный адрес владельца (см. настройки Профиля в Панели Управления) отправляется письмо с данными запроса, а пользователь получает заранее заготовленный для таких случаев ответ (см. параметр **Ответ** в настройках услуги). - Обработчик сообщений **Result URL** возвращает текст ответа, который через оператора сотовой связи (и через агрегатора) отправляется пользователю в виде ответного SMS-сообщения. - Для стран работающих с системой MT-биллинга наш сервер с помощью HTTP-запроса дополнительно вызывает обработчик статуса сообщения **Status URL** и передает ему [[#Реализация обработчика Status URL|данные]] о статусе сообщения. Владелец должен предоставлять услугу только если получен статус delivered. ===== Добавление услуги и настройка ===== Добавление услуги **смс:транзит** производится только по согласованию с менеджерами Финансового отдела. Настройка услуги производится в Панели Управления -> Услуги -> смс:транзит. После добавления услуги необходимо на сетевом ресурсе разместить клиентский код скрипта, взаимодействующий с нашим сервером и реализующий [[#Реализация услуги смс:транзит|соответствующую]] логику. Чтобы подключить к аккаунту новый **смс:транзит**, необходимо нажать "Добавить" и заполнить предлагаемую форму. При настройке параметров **смс:транзита** следует учитывать следующие особенности: - **Стоимость**\\ Выбирается тариф (по стране/оператору) равный или больший заданной стоимости. Если стоимость выше любого тарифа в одной или нескольких странах (операторах), то они исключаются из списка доступных (из [[#Тарифная сетка|тарифной сетки]]). Если стоимость превышает тарифы во всех странах, то выдается пустой список (пустая [[#Тарифная сетка|тарифная сетка]]). - **Result URL**\\ Адрес обработчика, начинающийся с http://, на который нашим сервером передаются [[#Данные, передаваемые на обработчик|данные]] согласно [[#Реализация услуги смс:транзит|реализации услуги **смс:транзит**]]. - **Status URL**\\ Адрес обработчика, начинающийся с http://, на который наш сервер передает статус SMS-сообщений (для стран, работающих по системе MT-биллинга). - **Секретный код**\\ Необходим для защиты данных, передаваемых на обработчики. Задается произвольным набором символов в кодировке UTF-8 длиной, не превышающей 32 символа. - **Ответ**\\ Если не задана строка в **Result URL**, здесь можно задать текст, который будет отправляться пользователю в ответном SMS-сообщении. Если не заданы оба параметра **Result URL** и **Ответ**, то пользователю будет отправлен текст по умолчанию:"your sms processed/ vash sms obrabotan" ==== Лимит отправленных SMS-сообщений ==== Для услуги **смс:транзит** реализована также возможность установки лимита на количество отправленных SMS-сообщений. SMS-сообщения, отправленные сверх лимита, будут рассматриваться как фродовые.\\ Существуют 2 вида лимитов: - По количеству SMS с одного и того же номера. - По сумме в USD. Можно использовать только один из них. Для каждого вида лимита имеется 2 параметра: - Ограничение в день. - Ограничение в месяц. Можно использовать оба параметра одновременно, либо только один из них. В случае превышения лимита пользователь получает SMS-сообщение You exceeded limit of SMS! Текст сообщения постоянный и не может быть изменен. Для включения лимита необходимо отправить запрос к Александру Бережному (alex@smscoin.com) письмо с описанием причины его включения, а также с указанием ID аккаунта клиента и ID услуги **смс:транзит**. ===== Реализация услуги смс:транзит ===== Для реализации услуги **смс:транзит** можно выделить как минимум три необходимые части: * [[#Реализация страницы, инициирующей процесс отправки SMS|Страница]] (одна или несколько, либо генерируемая динамически), предлагающая некоторую услугу и инициирующая процесс отправки SMS пользователем сайта. Например, выводящая инструкцию по отправке SMS. * [[#Реализация обработчика Result URL|Обработчик]], на который наш сервер передает данные каждого принятого нами SMS-сообщения. Адрес этого обработчика указывается в Панели Управления в настройках услуги в параметре **Result URL**. * [[#Реализация обработчика Status URL|Обработчик]], на который наш сервер передает статус принятого нами SMS-сообщения в системах MT-биллинга. Адрес этого обработчика также указывается в Панели Управления в настройках услуги в параметре **Status URL**. Далее подробно описаны детали реализации каждой из этих частей. ==== Реализация страницы, инициирующей процесс отправки SMS ==== Для того чтобы сообщение было ассоциировано с услугой, оно должно иметь вид <префикс> <идентификатор транзита> <текст сообщения> и быть отправлено на соответствующий короткий номер. Задача по предоставлению пользователю всей необходимой информации для отправки сообщения ложится на плечи владельца ресурса, т.е. аналогично реализации [[agregator:smscoin:smskey#Смс:ключ с удаленным обработчиком|**смс:ключа** с удаленным обработчиком]]. В услуге **смс:транзит** можно принимать сообщения как по всем тарифам, доступным в каждой из стран (динамическая тарификация), так и указать фиксированный тариф в настройках услуги. * **фиксированный тариф** - если в настройках услуги указана стоимость SMS-сообщения отличная от 0, услуга работает аналогично услуге [[agregator:smscoin:smskey|**смс:ключ**]]. * **динамическая тарификация** - если в настройках сервиса не указана стоимость отправляемого пользователем SMS-сообщения или указан ноль, услуга работает со всеми доступными в каждой стране тарифами. При таком использовании сервиса обработчик **Result URL** должен учитывать стоимость присланного пользователем сообщения. При этом стоит обращать внимание, что она варьируется от оператора к оператору и от страны к стране. Необходимо учесть также случай, когда пользователь физически не может отправить сообщение необходимой стоимости, поскольку в его стране подобный тариф не поддерживается. В большинстве стран для каждого тарифа существует свой номер для отправки сообщений, т.е. фактически стоимость сообщения определяется в зависимости от номера, на который оно послано. Но существуют также страны, в которых отправка происходит на один номер, а тарификация производится на основании префикса в тексте SMS-сообщения. ==== Реализация обработчика Result URL ==== Обработчик сообщений **Result URL** принимает следующие параметры: ^ Параметр ^ Тип ^ Описание ^ |country | char(2) |Двухбуквенный код страны | |shortcode | int |Номер, на который было отправлено сообщение | |provider | char(16) |Оператор сотовой связи | |prefix | char(16) |Префикс полученного сообщения | |cost_local | float |Стоимость полученного сообщения в местных денежных единицах | |cost_usd | float |Стоимость полученного сообщения в USD | |phone | char(32) |Номер, с которого было отправлено сообщение, включая код страны;\\ для некоторых стран вместо актуального номера передается некий уникальный идентификатор абонента в системе | |msgid | char(32) |Уникальный идентификатор принятого SMS-сообщения | |sid | int |Идентификатор используемого сервиса в нашей системе | |content | char(128) |Текст сообщения | |sign | char(32) |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ secret_code, country, shortcode, provider, prefix, cost_local, cost_usd, phone, msgid, sid и content (в указанном порядке),\\ где secret_code - секретный ключ Вашего смс:транзита | |billing | char(2) |Тип биллинга MO или MT | |mcc | int(3) |Мобильный код страны | |mnc | int(3) |Мобильный код оператора | |profit | float |Ваш процент от стоимости SMS в USD (параметр cost_usd) | Обработчик должен возвращать HTTP-статус 200 OK и строку ответа, которая будет отправлена пользователю. Ответы в формате текст@@@ссылка (например, example@@@http://example.com) при отправке пользователю автоматически преобразуются в WAP-ссылки (работает только в России, Украине, Казахстане, Израиле и Литве). Строка @@@ является зарезервированной, и не должна использоваться в обычных ответах. ==== Реализация обработчика **Status URL** ==== Обработчик статуса сообщения (Status URL) принимает следующие параметры: ^ Параметр ^ Тип ^ Описание ^ |msgid | char(32) |Уникальный идентификатор принятого SMS-сообщения. Совпадает с msgid в [[#Реализация обработчика Result URL|Result URL]] | |phone | char(32) |Номер, с которого было отправлено сообщение, включая код страны;\\ для некоторых стран вместо актуального номера передается некий уникальный идентификатор абонента в системе | |status | char(16) |Статус сообщения (см. ниже) | |sign | char(32) |MD5-хэш строки, состоящей из соединенных через двойное двоеточие ("::") параметров\\ secret_code, msgid, phone и status (в указанном порядке),\\ где secret_code - секретный ключ Вашего смс:транзита | === Статусы сообщений === Для стран, работающих с системой MO-биллинга (billing=MO в Result URL), сообщение считаться оплаченным, а скрипт подтверждения статуса вызывается только в случае присвоения сообщению статуса **fraud**, т. е. если оплата не была подтверждена (подробнее см. выше). Для стран, работающих с системой MT-биллинга (billing=MT в Result URL), сообщение не может считаться обработанным, пока не известен его статус. Статус сообщения может принимать следующие значения: ^ Статус ^ Описание ^ |delivered |Сообщение доставлено и оплачено | |rejected |Пользователь отказался от оплаты | |failed |Сообщение не было доставлено | |fraud |Оплата сообщения не подтверждена или была отменена.\\ Как правило, это происходит в результате попыток мошенничества со стороны абонента\\ либо в результате нарушения пользовательского соглашения владельцем сервиса. | | Дополнительно для Израиля || |unconfirmed |Пользователь не подтвердил оплату | |timeout |Ответ не был получен за отведенное сервером время | __**Замечание**__ К сожалению, даже после получения статуса delivered, он может быть изменен на другой! Это случается не часто, но иногда операторы сотовой связи преподносят нам подобного рода сюрпризы. ===== Тарифная сетка ===== Тарифную сетку для услуги **смс:транзит** можно получить по следующим адресам: Динамическая тарификация в формате XML: http://service.smscoin.com/xml2/transit/идентификатор транзита/all/ в формате JSON: http://service.smscoin.com/json/transit/идентификатор транзита/all/ Фиксированная (статическая) тарификация в формате XML: http://service.smscoin.com/xml2/transit/идентификатор транзита/ в формате JSON: http://service.smscoin.com/json/transit/идентификатор транзита/ ===== Готовые скрипты ===== ^ Ссылка ^ Описание ^ |[[http://smscoin.com/mediabank/examples/smstransit_php.zip]] |PHP-версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smstransit_perl.zip]] |Perl версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smstransit_aspx.zip]] |ASP.NET версия стандартного скрипта | |[[http://smscoin.com/mediabank/examples/smstransit_xml.zip]] |PHP-версия скрипта с тарифной сеткой в формате XML | |[[http://smscoin.com/mediabank/examples/smstransit_php.zip]] |PHP-версия скрипта с тарифной сеткой в формате JSON |