Протокол интеграция HTTP (XML) для взаимодействия с SMS сервисом

ВНИМАНИЕ

Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. При регистрации Вам присваивается логин, и тестовое имя отправителя SMS Info, которое будет автоматически удалено, после того как Вы запросите новое имя.

Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.

Общие положения

Серверная платформа Stream Telecom и клиент компании (далее ЗАКАЗЧИК) обмениваются HTTP запросами, используя язык разметки XML, данные включаются в тело запроса.

Подключение, основанное на инкапсуляции передаваемых данных в XML конверты поверх протокола HTTP 1.1. Обмен данными построен по схеме запрос/ответ с использованием метода POST и не требует постоянного TCP/IP соединения.

Кодировка XML документов UTF-8

Передаваемый XML документ не должен содержать переводов строки.

Переводы строк в самих данных должны быть заменены на “/n”.

Заголовки отправляемых данных должны содержать:

Content-type: text/xml; charset=utf-8

Точка доступа

Запросы ЗАКАЗЧИКА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL, для каждого метода указывается свой путь

ПРОВЕРКА КОРРЕКТНОСТИ ЗАПРОСОВ

Корректность формирования запросов и ответов можно проверить по адресу:

https://gateway.api.sc/test_post.php

Документация по интеграции Stream Telecom XML.pdf

Функции

Адрес сервера:

https://gateway.api.sc/xml/

Запрос (XML-документ)

<?xml version="1.0" encoding="utf-8" ?>

<request>

<security>

<login value="login" />

<password value="password" />

</security>

<message>

<sender>sender</sender>

<text>text</text>

<abonent phone="phone" number_sms="number_sms" phone_id="phone_id"

time_send="time_send" validity_period=”validity”/>

<abonent phone="phone" number_sms="number_sms" phone_id="phone_id"

time_send="time_send" validity_period=”validity”/>

<abonent phone="phone" number_sms="number_sms" phone_id="phone_id"

time_send="time_send" validity_period=”validity”/>

</message>

</request>

Наименование поля

Описание

login

Логин присвоенный ЗАКАЗЧИКУ. Тип данных: string

password

Пароль для api (задается в личном кабинете во вкладке Настройки API) Тип данных: string

text

Текст сообщения, поддерживаемые кодировки UTF-8. Тип данных: string

phone

Мобильные телефонные номера получателей сообщения, в международном формате (до 1000 номеров в одном запросе): код страны + код сети + номер телефона. Пример: 7903123456. Тип данных: string

number_sms

Номер сообщения в пределах отправляемого XML документа. Обязательный параметр при пакетной отправке.

Тип данных: integer.

phone_id

Идентификатор телефона. Необязательный параметр, позволяет избежать повторной отправки. Если раннее уже было отправлено SMS с id, то повторная отправка не производится, а возвращается номер ранее отправленного SMS. Тип данных: integer.

time_send

Дата и время отправки по локальному времени пользователя (задается в профиле пользователя – закладка Настройки) в формате

YYYY-MM-DD HH:MM

Напр: 2001-12-31 12:34

Если не задано, то SMS отправляется сразу же.

validity

Дата и время отправки по локальному времени пользователя (задается в профиле пользователя – закладка Настройки), после которого смс не должна доставляться в формате:

YYYY-MM-DD HH:MM (срок жизни смс)

где, YYYY-год, MM-месяц, DD-день, HH-часы, MM-минуты.

Максимальный срок жизни 24 часа.

sender

Адрес отправителя сообщения. До 11 латинских символов. Тип данных: string

 Примечания

Передаваемое значение в адресе отправителя, должно в точности соответствовать ранее зарегистрированному. Если установлена функция динамической смены адреса, то значение может быть любым. В тестовом периоде SMS Info

name_deliver

Название рассылки (название присваивается для удобства поиска в статистике) Тип данных: string

 Примечания

Название рассылки задается в виде get параметра при обращении на сервер.
Пример: https://gateway.api.sc/xml/?name_deliver=title

Ответ

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>

<response>

<error>error</error>

</response>

В случае отправки правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>

<response>

<information number_sms="number_sms" id_sms="ID_SMS"

parts="parts">Status</information>

<information number_sms="number_sms" id_sms="ID_SMS"

parts="parts">Status</information>

<information number_sms="number_sms" id_sms="ID_SMS"

parts="parts">Status</information>

</response>

Наименование поля

Описание

error

Описание ошибки при обработке XML пакета. Возможные значения и описание указаны в приложении 1.

ID_SMS

Идентификатор SMS сообщения. Используется для проверки статуса SMS. Если в процессе отправки SMS произошла ошибка, то id_sms не передается

number_sms

Номер сообщения, указанный при отправке запроса на отправку

Status

Статус обработки корректного XML запроса на отправку SMS

Возможные значения:

  1. Send – сообщение принято к отправке
  2. Прочие значения перечислены в Приложении 1.

Адрес сервера:

https://gateway.api.sc/xml/state.php

Запрос (XML-документ) 

<?xml version="1.0" encoding="utf-8" ?>

<request>

<security>

<login value="login" />

<password value="password" />

</security>

<get_state>

<id_sms>ID_SMS</id_sms>

<id_sms>ID_SMS</id_sms>

</get_state>

</request>

Наименование поля

Описание

login

Логин присвоенный ЗАКАЗЧИКУ. Тип данных: string

password

Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) Тип данных: string

ID_SMS

Идентификатор SMS сообщения. Тип данных: string

Ответ

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>

<response>

<error>error</error>

</response>

В случае отправки правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>

<response>

<state id_sms="ID_SMS" time="sms_time">State</state>

<state id_sms="ID_SMS" time="sms_time">State</state>

</response>

Наименование поля

Описание

ID_SMS

Идентификатор SMS сообщения. Тип данных: string

sms_time

Время изменения статуса в формате YYYY-MM-DD HH:MM (срок жизни смс)

где, YYYY-год, MM-месяц, DD-день, HH-часы, MM-минуты Напр: 2011-01-01 12:57:46

state

Статус сообщения на момент проверки. Возможные варианты перечислены в Приложении 1.


Адрес сервера:

https://gateway.api.sc/xml//balance.php

Запрос (XML-документ)

<?xml version="1.0" encoding="utf-8" ?>

<request>

<security>

<login value="login"/>

<password value="password"/>

</security>

</request>

Наименование поля

Описание

login

Логин присвоенный ЗАКАЗЧИКУ. Тип данных: string

password

Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) Тип данных: string

Ответ

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>

<response>

<error>error</error>

</response>

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>

<response>

<money currency="currency">sum</money>

<sms area="area">amount</sms>

<sms area="area">amount</sms>

</response>

Наименование поля

Описание

error

Описание ошибки при обработке XML пакета. Возможные значения и описание указаны в Приложении 1.

currency

Валюта учета логина. Напр.: RUR

sum

Сумма остатка средств на счету в валюте учета логина.

area

Направление в котором может быть отправлено сообщение

amount

Количество доступных SMS сообщений в данном направлении


Адрес сервера:

https://gateway.api.sc/xml//originator.php

Запрос (XML-документ)

<?xml version="1.0" encoding="utf-8" ?>

<request>

<security>

<login value="login"/>

<password value="password"/>

</security>

</request>

Наименование поля

Описание

login

Логин присвоенный ЗАКАЗЧИКУ. Тип данных: string

password

Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) Тип данных: string

Ответ

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>

<response>

<error>error</error>

</response>

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>

<response>

<any_originator>any</any_originator>

<list_originator>

<originator state="originator_state">source_address</originator>

</list_originator>

</response>

Наименование поля

Описание

error

Описание ошибки при обработке XML пакета. Возможные значения и описание указаны в Приложении 1.

any

Возможность использования произвольного имени отправителя. Возможные значения: TRUE/FALSE

Если TRUE, то можно использовать любое имя отправителя. При этом список отправителей не возвращается.

Если FALSE, то можно использовать только отправителей со статусом «completed».

originator_state

Статус модерации имени отправителя. Возможные значения:

'order' – в очереди на модерацию

'completed' - одобрено

'rejected' – отклонено

source_address

Адрес отправителя

Статусы сообщений

Значение

Описание

send

Сообщение отправлено.

Промежуточный статус

not_deliver

Сообщение не доставлено.

Конечный статус.

expired

Сообщение просрочено, истекло время жизни сообщения.

Конечный статус.

deliver

Сообщение доставлено.

Конечный статус

partly_deliver

Частичная доставка, доставлены не все части сообщения.

Конечный статус


Ошибки их значение и описание

Значение

Описание

Error_Destination_Address_Blocked

Отправка на указанный в запросе номер телефона невозможна, номер телефона присутствует в стоп-листе.

Error_Invalid_Login

Неправильный логин или пароль

Error_Invalid_POST_Data

POST данные отсутствуют

Error_Invalid_Source_Address

Некорректный адрес отправителя. Отправитель не должен превышать 15 символов для цифровых номеров и 11 символов для буквенно-числовых.

Error_Invalid_XML

Неправильный формат XML документа

Error_No_Destination_Address

Не указан номер телефона получателя

Error_No_Source_Address

Не указан адрес отправителя

Error_No_Text

В запросе отсутствует текст сообщения

Error_No_URL

Не указана WAP ссылка в запросе

Error_No_Vcard

Не указана ни один параметр для визитной карточки

Error_Not_Enough_Credits

Недостаточно средств

Error_Out_of_Service

Сервис недоступен (сообщение для дилеров)

Error_SMS_Declined

Текст сообщения не прошел модерацию

Error_SMS_User_Disabled

Ваш аккаунт заблокирован

Error_Source_Address_Declined

Адрес отправителя не прошел модерацию

Error_User_Destination_Blocked

Данное направление закрыто на вашем логине (отправка на международные направления)

Error_Flood_SMS

Множественная отправка смс на один номер с одинаковым текстом.