Зарегистрироваться
Войти
Протокол интеграции HTTPs (REST) для рассылки SMS
ВНИМАНИЕ
Для использования данного вида интеграции Вам необходимоПароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Общие положения
Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.
Точка доступа
Запросы КЛИЕНТА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL:
(ssl:
ПРОВЕРКА КОРРЕКТНОСТИ ЗАПРОСОВ
Корректность формирования запросов и ответов можно проверить по адресу:
Для удобства тестирования данного метода, Вы можете скачать библиотеку всех функций на базе Postman и импортировать ее.
Скачать библиотеку функций JSON
Функции
Запрос на получение баланса пользователя.
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 login=userlogin &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 login=userlogin &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 login=userlogin &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 данные о статусе доставки смс (сервис активного приема статусов смс)
Пример возвращаемых данных: |
|
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 login=userlogin &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 данные о статусе доставки смс (сервис активного приема статусов смс)
Пример возвращаемых данных: |
|
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 login=userlogin &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 данные о статусе доставки смс (сервис активного приема статусов смс)
Пример возвращаемых данных: |
|
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 login=userlogin &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 данные о статусе доставки смс (сервис активного приема статусов смс)
Пример возвращаемых данных: |
|
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 login=userlogin &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). |
|
maxDateUTC |
Максимальное значение периода за который происходит выборка входящих сообщений (пример 2010-06-02T19:14:00). |
Ответ
|
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), где: |
В случае отправки некорректного запроса, Вам вернется код возникшей ошибки
Формирование детальной статистики по рассылкам
Запрос на получение детальной статистики по рассылкам за заданный указанный период времени, по номеру телефона, статусу, отправителю и данным подлогинов.
Вы можете выполнить не более 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 login=userlogin &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 – по умолчанию). |
|
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 login=userlogin &pass=userpassword &id_report=12124
Content-Type: application/x-www-form-urlencoded |
|
В зависимости от передаваемых настроек, файл детальной статистики в формате xlsx или архив, содержащий данный файл. |
Выгрузка списка тарифов
POST
Host: https://gateway.api.sc/rest/Balance/price_list.php
login=testuser
&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"
}
}
}
Коды ошибок
|
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 |
Недоступно (статус в архиве/нет доступа к статусу) |
Окончательный |
