+7 (812) 326 10 75 Санкт-Петербург
8 800 333 10 75 Бесплатно по России

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

ВНИМАНИЕ!

Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom по адресу http://web.szk-info.ru. При регистрации Вы получаете логин и пароль, а так же имя отправителя, которое необходимо запросить и использовать отличное от "SMS Info". Т.е. при регистрации нового пользователя Вам присваивается тестовое имя отправителя (SMS Info) и его нужно сменить на любое другое.


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

Серверная платформа 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_integrationl_sms_xml.pdf

Функции

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

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

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

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

<request>

<message type="smstype">

<sender>sender</sender>

<url>URL</url>

<name>name</name>

<phone cell="cell" work="work" fax="fax"/>

<email>email</email>

<position>position</position>

<organization>organization</organization>

<address post_office_box="post_box" street="street"

city="city" region="region" postal_code="postal_code" country="country"/>

<additional>additional</additional>

<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>

<message type="smstype">

<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”/>

<security>

<login value="login" />

<password value="password" />

</security>

</request>

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

Описание

smstype

Тип отправляемого SMS сообщения. Необязательный параметр

Возможные значения (по умолчанию sms)

sms – обычное SMS сообщение

flashsms – сообщение, отображаемое на экране телефона в момент прихода и не сохраняющееся в памяти.

wappush - WAP-Push ссылка

vcard - визитная карточка (vCard)

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 отправляется сразу же.

validaty

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

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

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

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

sender

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

 Примечания

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

login

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

password

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

URL

Если тип wappush – ссылка на ресурс

Если тип vcard – адрес сайта для визитной карточки

name

Если тип vcard – «ФИО» в визитной карточке

cell

Если тип vcard – «номер телефона» контакта

work

Если тип vcard – «номер рабочего телефона» контакта

fax

Если тип vcard – «номер факса» контакта

email

Если тип vcard – «e-mail» контакта

position

Если тип vcard – «должность» контакта

organization

Если тип vcard – «организация» контакта

post_box

Если тип vcard – «абонентский ящик» контакта

street

Если тип vcard – «улица» для контакта

city

Если тип vcard – «город» контакта

region

Если тип vcard – «область» контакта

postal_code

Если тип vcard – «индекс» контакта

country

Если тип vcard – «страна» контакта

additional

Если тип vcard – «дополнительная информация» контакта

Ответ

В случае возникновения ошибки в отправляемом 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

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

information

Статус обработки корректного 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

Пароль присвоенный ЗАКАЗЧИКУ. Тип данных: 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

Пароль присвоенный ЗАКАЗЧИКУ. Тип данных: 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

Пароль присвоенный ЗАКАЗЧИКУ. Тип данных: 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

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

* Все функции могут быть доработаны на усмотрение разработчиков, внедряющих службы SMS в систему 1С.