Протокол интеграции HTTPs (REST) для рассылки SMS

ВНИМАНИЕ

Для использования данного вида интеграции Вам необходимо

зарегистрироваться

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

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

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

Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.

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

Запросы КЛИЕНТА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL:

http://gateway.api.sc/rest/

(ssl:

https://gateway.api.sc/rest/

)

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

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

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

Для удобства тестирования данного метода, Вы можете скачать библиотеку всех функций на базе Postman и импортировать ее.
Скачать библиотеку функций JSON

Stream_Telecom_REST_1.13.pdf

Функции

Запрос на получение баланса пользователя.

GET-запрос

Host: https://gateway.api.sc/rest/Balance/?login=userlogin&pass=userpassword

POST-запрос

POST

Host: gateway.api.sc/rest/Balance/balance.php

Content-Type: application/x-www-form-urlencoded

&pass=userpassword

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

20015.3

Наименование поля	Описание
Возвращаемое значение	Баланс пользователя.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Запрос на получение списка отправителей.

GET-запрос

GET

Host: http://gateway.api.sc/rest/Statistic/originator.php/?login=userlogin&pass=userpassword

POST-запрос

POST

Host http://gateway.api.sc/rest/Statistic/originator.php

&pass=userpassword

Content-Type: application/x-www-form-urlencoded

Параметры	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.

Ответ

В ответ возвращается json со списком активных отправителей на логине.

Отправка единичного СМС-сообщения без учета часового пояса получателя

Отправляет единичное сообщение и возвращает его системный идентификатор.

Запрос

POST

Host: https://gateway.api.sc/rest/Send/SendSms/

Content-Type: application/x-www-form-urlencoded

&pass=userpassword

&sourceAddress=SMS Info

&destinationAddress=79001234567

&data=testdata

&sendDate=2013-08-30T19:00:00

&validity=1440

&callback_url=https://mysite.com/script.php

&user_id=3258544

&name_deliver=title

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
destinationAddress	Номера получателя сообщения, в международном формате: код страны + код сети + номер телефона. Пример: 79031234567. Обязательный.
sendDate	Дата и время отправки (пример 2010-06-01T19:14:00). Если не требуется отложенная отправка, то передавать данный параметр не нужно. Время указывается по UTC. Необязательный.
data	Текст сообщения. Обязательный.
sourceAddress	Имя отправителя. До 11 латинских символов или до 15 цифровых. Примечание: Передаваемое значение в адресе отправителя, должно в точности соответствовать ранее зарегистрированному. Если установлена функция динамической смены адреса, то значение может быть любым. Обязательный.
validity	Время жизни сообщения, устанавливается в минутах. (По умолчанию 1440) Необязательный.
callback_url	Адрес скрипта заказчика, на который будут возвращаться POST данные о статусе доставки смс (сервис активного приема статусов смс) Пример возвращаемых данных: {"id":"3273115186551386277","user_id":"3258544","status":"deliver","time_change_state":"2019-06-04 17:40:14","phone":"79001234567"} Необязательный.
user_id	Цифровой идентификатор клиента, который возвращается на адрес указанный в параметре callback_url Необязательный.
name_deliver	Название рассылки (название присваивается для удобства поиска в статистике). Необязательный.
no_replace	Указывает на необходимость передачи спецсимволов в неизменном виде. Допустимые значения: true, false (false – по умолчанию). Необязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

["371324579"]

Наименование поля	Описание
Возвращаемое значение	Идентификатор сообщения.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Отправка единичного СМС-сообщения с учетом часового пояса получателя

Отправляет единичное сообщение, учитывая часовой пояс получателя и возвращает его системный идентификатор.

Запрос

POST

Host: https://gateway.api.sc/rest/Send/SendByTime/

Content-Type: application/x-www-form-urlencoded

&pass=userpassword

&sourceAddress=SMS Info

&destinationAddress=79160000000

&data=testdata

&sendDate=2011-01-8T16:00:00

&validity=1440

&callback_url=https://mysite.com/script.php

&user_id=3258544

&name_deliver=title

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
sourceAddress	Имя отправителя. До 11 латинских символов или до 15 цифровых. Примечание: Передаваемое значение в адресе отправителя, должно в точности соответствовать ранее зарегистрированному. Если установлена функция динамической смены адреса, то значение может быть любым. Обязательный.
destinationAddress	Номер получателя сообщения, в международном формате: код страны + код сети + номер телефона. Пример: 79031234567. Обязательный.
sendDate	Дата и время отправки (локальное время абонента). Например, необходимо чтобы сообщение было отправлено в 10 утра 28 августа, в этом случае нужно передать 2010-08-28T10:00:00, сервис автоматически определит часовой пояс абонента по номеру телефона и отложит отправку согласно полученному значению. Дату лучше назначать на следующий день, так как для некоторых абонентов время отправки может быть уже не актуальна, из-за разницы часовых поясов. Обязательный. Время отправки должно быть указано в формате UTC.
data	Текст сообщения. Обязательный.
validity	Время жизни сообщения, устанавливается в минутах. Необязательный.
callback_url	Адрес скрипта заказчика, на который будут возвращаться POST данные о статусе доставки смс (сервис активного приема статусов смс) Пример возвращаемых данных: {"id":"3273115186551386277","user_id":"3258544","status":"deliver","time_change_state":"2019-06-04 17:40:14","phone":"79160000000"} Необязательный.
user_id	Цифровой идентификатор клиента, который возвращается на адрес указанный в параметре callback_url Необязательный.
name_deliver	Название рассылки (название присваивается для удобства поиска в статистике). Необязательный.
no_replace	Указывает на необходимость передачи спецсимволов в неизменном виде. Допустимые значения: true, false (false – по умолчанию). Необязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

["371324579"]

Наименование поля	Описание
Возвращаемое значение	Идентификатор сообщения.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Отправляет сообщение адресатам и возвращает системные идентификаторы сообщений.

Запрос

POST

Host: gateway.api.sc/rest/Send/SendBulk/

Content-Type: application/x-www-form-urlencoded

&pass=userpassword

&sourceAddress=SMS Info

&destinationAddresses=79001234567,79101234778,79121231267

&data=testdata

&validity=1440

&callback_url=https://mysite.com/script.php

&name_deliver=title

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
sourceAddress	Имя отправителя. До 11 латинских символов или до 15 цифровых. Примечание: Передаваемое значение в адресе отправителя, должно в точности соответствовать ранее зарегистрированному. Если установлена функция динамической смены адреса, то значение может быть любым. Обязательный.
destinationAddresses	Список номеров получателей, в международном формате: код страны + код сети + номер телефона. Пример: 79031234567, номера вводятся через запятую. Обязательный.
data	Текст сообщения. Обязательный.
validity	Время жизни сообщения, устанавливается в минутах. Необязательный.
callback_url	Адрес скрипта заказчика, на который будут возвращаться POST данные о статусе доставки смс (сервис активного приема статусов смс) Пример возвращаемых данных: {"id":"3273115186551386277","status":"deliver","time_change_state":"2019-06-04 17:40:14","phone":"79001234567"} Необязательный.
name_deliver	Название рассылки (название присваивается для удобства поиска в статистике). Необязательный.
no_replace	Указывает на необходимость передачи спецсимволов в неизменном виде. Допустимые значения: true, false (false – по умолчанию). Необязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

[“371329058”,”371329059”]

Наименование поля	Описание
Возвращаемое значение	Идентификатор сообщения.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Отправка сообщений нескольким адресатам с разным текстом.

Запрос

POST

Host: gateway.api.sc/rest/Send/SendBulkPacket/

Content-Type: application/x-www-form-urlencoded

&pass=userpassword

&sourceAddress=SMS Info

&phone_data={"sms":[{"phone":"79114567865","text":"text1"},

{"phone":"79115842514","text":"text2"}]}

&validity=1440

&callback_url=https://mysite.com/script.php

&name_deliver=title

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
sourceAddress	Имя отправителя. До 11 латинских символов или до 15 цифровых. Примечание: Передаваемое значение в адресе отправителя, должно в точности соответствовать ранее зарегистрированному. Если установлена функция динамической смены адреса, то значение может быть любым. Обязательный.
phone_data .phone	Номер получателя, в международном формате: код страны + код сети + номер телефона. Пример: 79031234567 Обязательный.
phone_data .text	Текст сообщения. Обязательный.
validity	Время жизни сообщения, устанавливается в минутах. Необязательный.
callback_url	Адрес скрипта заказчика, на который будут возвращаться POST данные о статусе доставки смс (сервис активного приема статусов смс) Пример возвращаемых данных: {"id":"3273115186551386277","status":"deliver","time_change_state":"2019-06-04 17:40:14","phone":"79114567865"} Необязательный.
name_deliver	Название рассылки (название присваивается для удобства поиска в статистике). Необязательный.
no_replace	Указывает на необходимость передачи спецсимволов в неизменном виде. Допустимые значения: true, false (false – по умолчанию). Необязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

[“371329058”,”371329059”]

Наименование поля	Описание
Возвращаемое значение	Идентификатор сообщения.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Возвращает статус сообщения и время обновления статуса.

GET-запрос

GET

Host: gateway.api.sc/rest/State/?login=userlogin&pass=userpassword&messageId=3273115188086356946

POST-запрос

POST

Host: gateway.api.sc/rest/State/state.php

&pass=userpassword

&messageId=3273115188086356946

Content-Type: application/x-www-form-urlencoded

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
messageId	Идентификатор сообщения. Обязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

{"State":0,"StateDescription":"Delivered","ReportedDateUtc":"/Date(1377761466000)/","TimeSend":"2021-11-30 14:34:09","TimeChangeState": "2021-11-30 14:34:09","MessageId": "3273115188083429690","Price":"0.5"}

Наименование поля	Описание
State	Статус сообщения (см. раздел "Коды ошибок").
StateDescription	Описание статуса.
ReportedDateUtc	Дата доставки. Указана в формате unixtime. Который показывает количество миллисекунд, прошедших с 1 января 1970 года. Время указывается по UTC.
TimeSend	Время отправки сообщения. Возвращается в том часовом поясе, который настроен на логине.
TimeChangeState	Время получения статуса сообщения. Возвращается в том часовом поясе, который настроен на логине.
MessageId	Идентификатор сообщения
Price	Цена за сообщение.

Расшифровку статусов сообщений, можно посмотреть в таблице статусов сообщений

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Запрос на получение входящих сообщений.

Запрос

GET

Host gateway.api.sc/rest/Incoming/?login=userlogin&pass=userpassword&minDateUTC=2011-01-01T00:00:00&maxDateUTC=2011-01-11T00:00:00

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
minDateUTC	Минимальное значение периода за который происходит выборка входящих сообщений (пример 2010-06-01T19:14:00). Время указывается по UTC. Обязательный.
maxDateUTC	Максимальное значение периода за который происходит выборка входящих сообщений (пример 2010-06-02T19:14:00). Время указывается по UTC. Обязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

[{"Prefix":"prefix","Data":"message","SourceAddress":"79115687451",

"DestinationAddress":"2420","ID":5126,"CreatedDateUtc":"\/Date(1357536599000)\/"}]

Наименование поля	Описание
Data	Текст входящего сообщения.
SourceAddress	Номер отправителя.
DestinationAddress	Номер для приема входящих сообщений.
Prefix	Префикс сообщения.
ID	Идентификатор сообщения.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Пользователю требуется прислать адрес своего скрипта-обработчика, который будет принимать данные об смс, отправленных на входящий номер.

При получении запроса от абонента, платформа вызывает URI скрипта-обработчика пользователя.

При получении сообщения отправителю от платформы Stream Telecom отправляется сообщение «Спасибо, ваше сообщение получено»

Пример:

http://www.my_site.ru/sms.php?date=@@MSGDATE@@&text=@@FULLSMS@@&smsid=@@MESSAGEID@@&

Параметр	Описание
MSGDATE	дата и время сообщения в системе
FULLSMS	сообщение, которое отправил абонент
MESSAGEID	идентификатор сообщения
SENDER	телефон абонента, отправившего смс
RECIP	номер получателя сообщения
PREFIX	префикс на который отправлено сообщение

Все параметры необязательны для ответа и являются информационными. Информационные параметры используются при создании собственного сервиса.

Пример ответа:

smsid=5094

Параметр	Описание
smsid	идентификатор сессии, он передается в http-запросе от платформы при вызове скрипта-обработчика пользователем

Пример скрипта на PHP:

$smsid = $_GET['smsid'];

echo "smsid=" . $smsid . "\n";

Получение статистики по СМС-рассылкам

Запрос на получение статистики по СМС рассылкам за заданный период времени.

Запрос

GET

Host: gateway.api.sc/rest/Statistic/?login=userlogin&pass=userpassword&startDateTime=2012-01-18%2000:00:00&endDateTime=2012-01-18%2023:59:00

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
startDateTime	Дата и время начала периода, за который необходимо получить статистику, например 2012-01-18T00:00:00. Обязательный.
endDateTime	Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18T23:59:00. Обязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

[{"Sent":12124,"Delivered":9994,"NotDelivered":632,"InProcess":44,"Expired":1454,"DeliveryRatio":82}]

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

Описание

Возвращаемое значение

JSON со статистикой (в utf-8), где:
Sent - колчиество отправленных сообщений
Delivered - количество доставленных смс
NotDelivered - количество недоставленных смс
InProcess - количество смс в процессе доставки
Expired - колчиество просроченных смс
DeliveryRatio - процент доставленных смс

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Формирование детальной статистики по рассылкам

Запрос на получение детальной статистики по рассылкам за заданный указанный период времени, по номеру телефона, статусу, отправителю и данным подлогинов.

Вы можете выполнить не более 4 запросов на формирование детальной статистики по рассылкам в час.

Запрос

GET

Host: gateway.api.sc/rest/Statistic/all_stat.php/?login=userlogin&pass=userpassword&startDateTime=2012-01-18T00:00:00&endDateTime=2012-01-18T23:59:00

POST

Host: gateway.api.sc/rest/Statistic/all_stat.php

&pass=userpassword

&startDateTime=2012-01-18T00:00:00&endDateTime=2012-01-18T23:59:00

Content-Type: application/x-www-form-urlencoded

Наименование поля	Описание
login	Логин, присвоенный Клиенту. Обязательный.
pass	Пароль API, присвоенный Клиенту. Обязательный.
startDateTime	Дата и время начала периода, за который необходимо получить статистику, например 2012-01-18T00:00:00. Обязательный.
endDateTime	Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18T23:59:00. Обязательный.
state	Формирование статистики по определенному статусу сообщений. Допустимые значения: deliver, not_deliver, expired, sent (доставлено, не доставлено, просрочено, в процессе) Необязательный.
phone	Формирование статистики по определенному номеру абонента. Необязательный.
c_base	Указывает на необходимость выгрузки данных с привязкой к базе адресатов. Допустимые значения: 0, 1 (0 -по умолчанию) Необязательный.
sub_stat	Указывает на необходимость выгрузки данных с подлогинов. Допустимые значения: 0, 1 (0 -по умолчанию) Необязательный.
zip	Указывает на формат выгрузки. Допустимые значения: 0, 1 (0 – по умолчанию). 0 – файл в формате xlsx 1 – архив, содержащий файл в формате xlsx Необязательный.
id_smpp	Указывает на необходимость добавления в выгрузку идентификаторов сообщений. Допустимые значения: true, false (false – по умолчанию) Необязательный.

Ответ

200 OK

Cache-Control: private

Connection: Keep-Alive

Content-Type: application/json; charset=utf-8

12124

Наименование поля	Описание
Возвращаемое значение	ID формируемого отчета.

В случае отправки некорректного запроса, Вам вернется код возникшей ошибки

Текст ошибки	Описание
More than 2 reports at once are not allowed, make request later	Запрос более двух отчетов одновременно не разрешен, отправьте запрос позднее
Request per hour limit exceeded	Превышен лимит запросов в час (не более 4)
Bad Request	Некорректный запрос
Not correct format endDateTime	Некорректный формат даты конца периода
Not correct format startDateTime	Некорректный формат даты начала периода
SessionID expired	Истек срок идентификатора сессии
Not correct length originator	Некорректная длина имени отправителя
Not correct length phone	Некорректная длина номера телефона
Phone must be numeric	Номер телефона должен иметь числовой формат
EndDateTime can not be null or empty\r\nParameter name: endDateTime	Параметр endDateTime не может быть нулевым или пустым
StartDateTime can not be null or empty\r\nParameter name: startDateTime	Параметр startDateTime не может быть нулевым или пустым
Id report not found	Идентификатор отчета не найден
Report is not ready yet	Отчет не готов
File not exist	Файл не существует

Запрос на получение файла с отчетом

GET

Host: gateway.api.sc/rest/Statistic/all_stat.php/?login=userlogin&pass=userpassword&id_report=12124

POST

Host gateway.api.sc/rest/Statistic/all_stat.php

&pass=userpassword

&id_report=12124

Content-Type: application/x-www-form-urlencoded

Ответ

В зависимости от передаваемых настроек, файл детальной статистики в формате xlsx или архив, содержащий данный файл.

Выгрузка списка тарифов

POST

Host: https://gateway.api.sc/rest/Balance/price_list.php

&pass=userpassword

Content-Type: application/x-www-form-urlencoded

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность)

Пример ответа

    {
        "sms": {
            "РОССИЯ, Russia": {
                "R": "2.5"
            },
            "МТС": {
                "R": "2.5"
            },
            "Мегафон": {
                "R": "2.5"
            },
            "ТЕЛЕ2": {
                "R": "2.8"
            },
            "Билайн": {
                "R": "2.9"
            }
        }
    }

В ответ возвращается список номеров, содержащихся в стоп-листе. Список запрашивается постранично (страница содержит 1000 номеров). По умолчанию возвращается первая страница. Для запроса последующих страниц необходимо передать номер страницы в параметре page.

POST-запрос

Host: http://gateway.api.sc/rest/sms_black_list/?list
{
        "login": "userlogin",
        "pass": "userpassword"
}

Наименование	Обязательное поле	Описание
login	Да	Логин от учетной записи Stream Telecom
pass	Да	Пароль для API Stream Telecom
page	Нет	Страница

Ответ

{
        "result": "success"
        "data": [
                {
                        "phone": "7900000000",
                        "block-reason": "Отписка через подрядчика"
                }
        ]
}

Наименование поля	Описание
result	Статус запроса
message	Сообщение об ошибке
total	Общее количество номеров в стоп-листе
phone	Номер телефона
block-reason	Причина добавления в стоп-лист

POST-запрос

Host: http://gateway.api.sc/rest /sms_black_list/?add
 {
        "login": "userlogin",
        "pass": "userpassword",
        "phone": "70000000000",
        "block-reason": "Отписка через подрядчика"
}

Наименование	Обязательное поле	Описание
login	Да	Логин от учетной записи Stream Telecom
pass	Да	Пароль для API Stream Telecom
phone	Да	Номер для добавления в стоп-лист
block-reason	Нет	Причина добавления в стоп-лист

Ответ

{
        "result": "success"
}

{
        "result": "failed",
        "message": "Number is already in black list"
}

Наименование поля	Описание
result	Статус запроса
message	Сообщение об ошибке

POST-запрос

Host: http://gateway.api.sc/rest/sms_black_list/?remove    
{
        "login": "userlogin",
        "pass": "userpassword",
        "phone": "70000000000",
}

Наименование	Обязательное поле	Описание
login	Да	Логин от учетной записи Stream Telecom
pass	Да	Пароль для API Stream Telecom
phone	Да	Номер для добавления в стоп-лист

Ответ

{
        "result": "success"
}

Наименование поля	Описание
result	Статус запроса
message	Сообщение об ошибке

Коды ошибок

REST error code	HTTP status code	Описание
-	200	OperationComplete
1	400	ArgumentCanNotBeNullOrEmpty
2	400	InvalidArgument
3	400	InvalidSessionID
4	401	UnauthorizedAccess
5	403	NotEnoughCredits
6	400	InvalidOperation
7	403	Forbidden
8	500	GatewayError
9	500	InternalServerError
10	400	Flood SMS
-	429	Too many requests

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

State	Описание	Тип статуса
-1	Отправлено (передано в мобильную сеть)	Промежуточный
0	Доставлено абоненту	Окончательный
42	Не доставлено	Окончательный
46	Просрочено (истек срок жизни сообщения)	Окончательный
255	Недоступно (статус в архиве/нет доступа к статусу)	Окончательный

Протокол интеграции HTTPs (REST) для рассылки SMS

Функции

Точный расчет