Зарегистрироваться
Войти
Протокол интеграция 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, для каждого метода указывается свой путь
ПРОВЕРКА КОРРЕКТНОСТИ ЗАПРОСОВ
Корректность формирования запросов и ответов можно проверить по адресу:
Функции
Адрес сервера:
Запрос (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” callback_url=”https://mysite.com/script.php" /> <abonent phone="phone" number_sms="number_sms" phone_id="phone_id" time_send="time_send" validity_period=”validity” callback_url=”https://mysite.com/script.php" /> <abonent phone="phone" number_sms="number_sms" phone_id="phone_id" time_send="time_send" validity_period=”validity” callback_url=”https://mysite.com/script.php" /> </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 параметра при обращении на сервер. |
|
callback_url |
Адрес скрипта заказчика, на который будут возвращаться POST данные о статусе доставки смс (сервис активного приема статусов смс) Тип данных: string Пример возвращаемых данных: {"id":"3273115187855985029","user_id":"1","status":"deliver","time_change_state":"2021-06-30 12:54:08","phone":"79999999999"} где:
id - идентификатор сообщения
|
Ответ
В случае возникновения ошибки в отправляемом 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 |
Номер сообщения, указанный при отправке запроса на отправку |
|
Parts |
Количество частей смс |
|
Status |
Статус обработки корректного XML запроса на отправку SMS Возможные значения: |
Адрес сервера:
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 |
Множественная отправка смс на один номер с одинаковым текстом. |
