Изменения в версии 1.9.1

Документация по работе с услугой «Псевдо-подписки»
в системе СМС-Доступ
Информация по схеме предоставления сервиса
Версия PS 1.9.1 от 07.02.2014
Изменения в версии 1.9.1
- Добавлены новые коды ошибок 228 (Оператор не поддерживается) и 229 (По данному проекту
разрешена отправка СМС только на номера абонентов украинских операторов связи).
Изменения в версии 1.9
- Добавлен новый код ошибки 227 (Оператор не поддерживается).
Изменения в версии 1.8
- Добавлены новые коды ошибок 225 (По данному проекту разрешена отправка СМС только на номера
абонентов российских операторов связи) и 226 (Данный короткий номер не разрешен к использованию
на указанном проекте).
Изменения в версии 1.7
- Добавлен новый код ошибки 224, использование МТС шлюза для отправки СМС запрещено. Следует
обратиться в службу поддержки.
Изменения в версии 1.6
- В запросе на создание псевдо-подписки появились два новых параметра: <domain></domain> и
<description></ description >, обозначающие соответственно домен (сайт услуги) и описание (тематику)
услуги. Оба параметра после ввода будут иметь временный статус опциональных, однако следует
учесть, что по прошествии времени, выданного на внедрение корректировок (1-2 недели), в случае
отсутствия этих данных запрос на создание псевдо-подписки будет отвергаться с ошибкой (коды ошибок
указаны ниже в документе). Информация о переводе запросов в статус обязательных будет
предоставлена отдельно.
- Добавлена информация об условиях работы с оператором Теле2.
Важно: требования оператора Теле2 (описанные в разделе «Условия по работе с оператором Теле2»)
следует выполнить до 2-го сентября 2011-го года.
Изменения в версии 1.5
- Добавлен новый вариант ответа API-сервиса – 220: Operator Kievstar is not allowed, который обозначает
запрещение отправки СМС на номера абонентов оператора Киевстар (Украина). В случае получения
данного статуса производить повторную отправку запроса запрещено.
Изменения в версии 1.4
- Добавлен новый вариант ответа API-сервиса – 219:Abonent phone is blacklisted, который обозначает
блокировку номера абонента на нашей платформе. В случае получения данного статуса производить
повторную отправку запроса запрещено.
Изменения в версии 1.3
- Изменен формат ответа API-сервиса регистрации псевдо-подписок. Добавлен новый опциональный
параметр <smsid></smsid>, который будет содержать идентификатор отправленного смс-сообщения (в
случае успешности операции).
Изменения в версии 1.2
- В запросе на создание псевдо-подписки следует передавать новый параметр <abonentip></abonentip>.
Параметр должен содержать тот IP адрес, с которого абонент вводил номер телефона на сайте. С одного
IP адреса, указанного в данном параметре, принимается не более 50 запросов в течение 10 минут и не
более 200 запросов в течение 60 минут. Указанное изменение начнет действовать с 24.09.2010. Данное
ограничение необходимо для защиты от массовых мошеннических рассылок.
Изменения в версии 1.1
- Добавлено ограничение на количество запросов по одному номеру абонента. Не более 1-го запроса в
течение 15-ти минут и не более 3-х запросов в сутки. В случае срабатывания блокировки выдается код
216 (дополнительная информация указана в таблице кодов в разделе «API-запрос, синтаксис»).
Указанное изменение начнет действовать с 15:00 17.08.2010 (время Московское).
Оглавление
Принцип работы, общая информация .................................................................................................................2
API-запрос, синтаксис ............................................................................................................................................3
Дополнительно ......................................................................................................................................................5
Условия по работе с оператором Теле2 ..............................................................................................................6
Принцип работы, общая информация
«Псевдо-подписки» – услуга, работающая по всем операторам в системе СМС-Доступ на номерах РМИнвест и i-Free, позволяющая проводить периодическое списание средств с абонента в удобное для Вас
время. Схема работы с указанной услугой состоит из 3-х частей:
Часть 1, регистрация сессии по номеру абонента
Клиент
APIзапрос
Номер
абонента
СМСДоступ
Вы отправляете специальный запрос в сторону платформы СМС-Доступ, указывая следующие
параметры: телефон абонента, короткий номер, текст СМС. В момент успешной обработки API-запроса
на нашей платформе открывается сессия по указанному номеру абонента. Сессия регистрируется на
период времени установленный для Вашего аккаунта, по умолчанию 60 минут. В течение этого времени
весь трафик по коротким номерам для данного абонента будет перенаправляться на Ваш проект.
Часть 2, отправка нетарифицируемой СМС абоненту
СМСДоступ
Отправка
Абонент
СМС
Сразу после активации сессии мы производим отправку СМС в сторону абонента, с указанным Вами
текстом и с короткого номера, который был получен из API-запроса. При этом списания средств с
абонента в этот момент не происходит. Список коротких номеров, с которых возможна отправка СМС,
лимитирован и может быть уточнен в службе поддержки (по умолчанию, используются следующие
номера: 2858, 9151 компании РМ-Инвест и 4161 i-Free). Пример текста СМС: «Ответьте любым текстом
на это сообщение и получите доступ к услуге».
Часть 3, перенаправление трафика
Абонент
СМСзапрос
СМСДоступ
Клиент
В случае если абонент отвечает на отправленную нами СМС в течение периода действия сессии, запрос
перенаправляется Вам. Схема приема и обработки запроса в таком случае стандартна и аналогична
обработке обычной СМС по проекту.
API-запрос, синтаксис
Для регистрации сессии необходимо произвести XML-запрос по адресу:
http://api.smsdostup.ru/_subscription_pseudo.php
соответственно передав следующие параметры в запросе:
<?xml version="1.0" encoding="utf-8"?>
<request>
<projectid>123</projectid>
<phone>79123456789</phone>
<shortnumber>2858</shortnumber>
<smstext>Ответьте любым текстом на это сообщение и получите доступ к услуге</smstext>
<md5hash>c12aaa34eb5d6bff7a890e1ef2345678</md5hash>
<datetime>2010-06-10 13:00:00</datetime>
<smsid>1</smsid>
<abonentip>127.0.0.1</abonentip>
<domain>site.ru</domain>
<description>Знакомства</description>
</request>
Более подробное описание параметров указано в таблице ниже:
Параметр
projectid
Пример
Описание
123
phone
79123456789
shortnumber
2858
smstext
Ответьте любым текстом на это
сообщение и получите доступ к услуге
c12aaa34eb5d6bff7a890e1ef2345678
Идентификатор проекта в системе СМС-Доступ (см.
раздел «Список проектов» Вашего аккаунта)
Номер абонента, который будет участвовать в
подписке.
Короткий номер, который будет использоваться при
отправке СМС абоненту и на который Вы хотите
получить ответ.
Текст СМС, который будет отправлен абоненту в
кодировке utf-8
md5hash
datetime
smsid
2010-06-10 13:00:00
abonentip
127.0.0.1
domain
site.ru
description
Знакомства
Md5 полученный по формуле:
md5(projectid.phone.datetime.projectmd5)
где projectmd5 – md5 идентификатор Вашего проекта
в системе СМС-Доступ (см. редактирование проекта,
раздел «Список проектов» Вашего аккаунта).
Дата и время запроса, UTC
Опциональный параметр, указывающий на Ваш
внутренний идентификатор по данному запросу.
Будет передан в биллинг-запросе Вам, в случае если
абонент ответит на смс. Целочисленное значение.
Обязательный параметр, содержащий IP адрес, с
которого абонент вводил свой номер телефона при
создании подписки на Вашем сайте.
Обязательный параметр с доменом сайта услуги (без
http:// и без указания точного пути). Будет
использован при обработке жалоб и при отправке
СМС абонентам Теле2. Максимум 30 символов.
Кодировка
параметра
–
utf-8
(в
случае
использования доменов зоны .рф).
Обязательный параметр, содержащий описание
услуги сайта. Максимум 30 символов. Будет
использован при обработке жалоб и при отправке
СМС абонентам Теле2. Кодировка параметра – utf-8.
1
Ответ системы на такой запрос будет возвращен так же в виде XML:
<?xml version="1.0" encoding="utf-8"?>
<response>
<status>Статус принятия запроса</status>
<description>Код:описание статуса</description>
<smsid>Идентификатор СМС</smsid>
</response>
Status может принимать два значения: “ok” в случае успеха или “error” в случае ошибки. Description
будет содержать описание результата обработки. Smsid – опциональный параметр, который
возвращается только в случае успешности операции (status 200), параметр содержит целочисленное
значение. В таблице ниже указаны варианты для поля description.
Значение
Описание
200:Request saved
Запрос успешно обработан.
201:Empty data
Неверный запрос, отсутствуют XML данные
202:Invalid md5 hash
Отсутствует (либо указано некорректно) значение md5hash
203:Invalid datetime
Отсутствует (либо указано некорректно) значение datetime
204:Invalid project id
Отсутствует (либо указано некорректно) значение projectid
205:Invalid phone format
Отсутствует (либо указано некорректно) значение phone
206:Invalid shortnumber
Отсутствует (либо указано некорректно) значение shortnumber
207:Invalid sms text
Отсутствует (либо указано некорректно) значение smstext
208:Invalid project specified
Указан несуществующий проект
209:Wrong md5 hash
md5hash указан некорректно
210:User/project inactive
Аккаунт или проект неактивны
211:System error
Системная ошибка
212:Request declined
Запрос отклонен
213:Service temporarily unavailable
Сервис временно недоступен
214:Service unavailable
Услуга для Вашего аккаунта недоступна
215:Sender not allowed
Указанный отправитель не разрешен
216:Too many requests per phone
218:Invalid abonentip param
Слишком много запросов с использованием одного номера абонента.
Разрешено отправлять не более 1 запроса на телефон в течение 15 минут и не
более 3-х запросов в сутки.
Слишком много запросов с использованием одного IP абонента.
Разрешено отправлять не более 50 запросов в течение 10 минут и не более 200
запросов в течение 60 минут.
Некорректно указан IP абонента произведшего подписку.
219:Abonent phone is blacklisted
Номер абонента заблокирован на платформе. Рассылка СМС запрещена.
220:Operator Kievstar is not allowed
Рассылка на номера абонентов оператора Киевстар (Украина) запрещена
221:Missing domain
Не указан (либо указан некорректно) обязательный параметр domain (сайт
услуги)
Не указан (либо указан некорректно) обязательный параметр description
(описание услуги)
Системная ошибка
217:Too many requests per abonentip
222:Missing description
223:System error
224:MTS SMSC is not allowed to use
225:RU-abonents allowed only
226:Shortnumber is not allowed on this
project
227:Operator is not supported
Использование МТС шлюза для отправки СМС запрещено. Следует обратиться в
службу поддержки
По данному проекту разрешена отправка СМС только на номера абонентов
российских операторов связи
Данный короткий номер не разрешен к использованию на указанном проекте
Оператор не поддерживается
228:Operator is not allowed
Оператор не поддерживается
229:UA-abonents allowed only
По данному проекту разрешена отправка СМС только на номера абонентов
украинских операторов связи
Статус 200 обозначает успешность операции. Статусы 201-210, 212, 214-229 обозначают критичную
ошибку, повторять операцию в таком ситуации не следует. В случае получения статуса 211 или 213
разрешена переотправка запроса позднее.
Дополнительно
В момент прихода СМС на Ваш сервис происходит запрос в формате указанном в разделе
“Документация, примеры” > “Пример обработчика запросов”. При этом используется тип передачи
установленный для Вашего проекта. Для определения запросов отправленных по схеме псевдоподписок, дополнительно добавляется параметр:
_is_pseudosubs=1
для POST, или:
<ispseudosubs>true</ispseudosubs>
для XML. Остальные параметры передаются без изменений.
В случае если Вами в API-запросе при регистрации псевдо-подписке передавался опциональный
параметр smsid, значение этого поля будет передано в поле:
_pseudosubs_id=1
для POST запроса, или:
<pseudosubs_smsid>1</pseudosubs_smsid>
для XML.
Условия по работе с оператором Теле2
Для оператора Теле2 необходимо соблюдать обязательные условия и размещать в тексте СМС:
стоимость и название услуги (или домен). Данное требование может быть реализовано как со стороны
партнера, так и с нашей стороны. В последнем случае от клиента потребуется дополнительная передача
названия услуги (или домена) в запросе создания псевдо-подписки (параметр <domain> или параметр
<description>). Согласовать выполнение этого условия необходимо в обязательном порядке через тикет
систему. Требования оператора Теле2: дополнение СМС-текста названием услуги и стоимостью,
передача параметров услуги в запросе, согласование схемы работы в тикет-системе - следует
выполнить до 2-го сентября 2011.