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

Протокол интеграции HTTPs (REST) для рассылки 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_integration_sms_rest.pdf

Функции

Для начала работы через интеграцию REST, необходимо запросить идентификатор сессии (API ключ). API ключ нужен для того, чтобы при отправке запросов не было необходимости передачи конфиденциальных данных (логина и пароля) в открытом виде. Так же, если от личного кабинета будет изменен пароль, при работе через API, авторизация пользователя все равно будет происходить и работа не остановится.


GET-запрос

GET

HTTP/1.1

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

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

/?login=user&password=userpasswd


POST-запрос

POST

HTTP/1.1

Host: https://gateway.api.sc/rest/Session/session.php

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

login=user

&password=userpasswd

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

Описание

login

Логин присвоенный клиенту. Обязательный.

password

Пароль присвоенный клиенту. Обязательный.


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

"967648e7c4bc8926166632a4f0490f5e"

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

Описание

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

API ключ (36 символов).

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

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


GET-запрос

GET

HTTP/1.1

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

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

/?sessionId=967648e7c4bc8988542862a4f0490f5e


POST-запрос

POST

HTTP/1.1

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

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

sessionId=967648e7c4bc8988542862a4f0490f5e

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

Описание

sessionId

API ключ (36 символов). Обязательный.


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

20015.3

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

Описание

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

Баланс пользователя.

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

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

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


Запрос

POST

HTTP/1.1

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

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

Expect: 100-continue

HTTP/1.1 100 Continue

sessionId=967648e7c4bc8926183333a4f0490f5e

&sourceAddress=SMS Info

&destinationAddress=79001234567

&data=testdata

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

&validity=1440

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

Описание

sessionId

API ключ(36 символов). Обязательный.

destinationAddress

Номера получателя сообщения, в международном формате: код страны + код сети + номер телефона.

Пример: 79031234567. Обязательный.


sendDate

Дата и время отправки (пример 2010-06-01T19:14:00). Если не требуется отложенная отправка, то передавать данный параметр не нужно. Время указывается по UTC. Необязательный.

data

Текст сообщения. Обязательный.

sourceAddress

Имя отправителя. До 11 латинских символов или до 15 цифровых.

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

validity

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

(По умолчанию 1440) Необязательный.


Ответ

HTTP/1.1 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

Expect: 100-continue

HTTP/1.1 100 Continue

sessionId=967648e7c4bc8886182862a4f0490f5e

&sourceAddress=SMS Info

&destinationAddress=79160000000

&data=testdata

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

&validity=1440

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

Описание

sessionId

API ключ (36 символов). Обязательный.

sourceAddress

Имя отправителя. До 11 латинских символов или до 15 цифровых.

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

destinationAddress

Номер получателя сообщения, в международном формате: код страны + код сети + номер телефона.

Пример: 79031234567. Обязательный.

sendDate

Дата и время отправки (локальное время абонента). Например, необходимо чтобы сообщение было отправлено в 10 утра 28 августа, в этом случае нужно передать 2010-08-28T10:00:00, сервис автоматически определит часовой пояс абонента по номеру телефона и отложит отправку согласно полученному значению. Дату лучше назначать на следующий день, так как для некоторых абонентов время отправки может быть уже не актуальна, из-за разницы часовых поясов. Обязательный.

Время отправки должно быть указано в формате UTC.

data

Текст сообщения. Обязательный.

validity

Время жизни сообщения, устанавливается в минутах. Необязательный.


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

["371324579"]

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

Описание

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

Идентификатор сообщения.

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

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

Запрос

POST

HTTP/1.1

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

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

Expect: 100-continue

HTTP/1.1 100 Continue

sessionId=e3d4f2caa0cb90d788830ed5d3dcc073

&sourceAddress=SMS Info

&destinationAddresses=79001234567,79101234778,79121231267

&data=testdata

&validity=1440


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

Описание

sessionId

API ключ(36 символов). Обязательный.

sourceAddress

Имя отправителя. До 11 латинских символов или до 15 цифровых.

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

destinationAddresses

Список номеров получателей, в международном формате: код страны + код сети + номер телефона.

Пример: 79031234567, номера вводятся через запятую. Обязательный.

data

Текст сообщения. Обязательный.

validity

Время жизни сообщения, устанавливается в минутах. Необязательный.


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

[“371329058”,”371329059”]

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

Описание

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

Идентификатор сообщения.

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

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

Запрос

POST

HTTP/1.1

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

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

Expect: 100-continue

HTTP/1.1 100 Continue

sessionId=967648e7c4bc8926182444a4f0490f5e&sourceAddress=SMS Info

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

 {"phone":"79115842514","text":"text2"}]}&validity=1440


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

Описание

sessionId

API ключ (36 символов). Обязательный.

sourceAddress

Имя отправителя. До 11 латинских символов или до 15 цифровых.

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

phone_data .phone

Номер получателя, в международном формате: код страны + код сети + номер телефона.

Пример: 79031234567 Обязательный.

phone_data .text

Текст сообщения. Обязательный.

validity

Время жизни сообщения, устанавливается в минутах. Необязательный.


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

[“371329058”,”371329059”]

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

Описание

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

Идентификатор сообщения.

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

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

GET-запрос

GET

/?sessionId=967648e7c4bc8926177842a4f0490f5e&messageId=GW0261BA732A

HTTP/1.1

Host gateway.api.sc/rest/State/

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

POST-запрос

POST

sessionId=967648e7c4bc8926177842a4f0490f5e&messageId=GW0261BA732A

HTTP/1.1

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

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


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

Описание

sessionId

API ключ(36 символов). Обязательный.

messageId

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


Ответ

HTTP/1.1 200 OK

Cache-Control: private

Connection: Keep-Alive

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

 {"State":0,"ReportedDateUtc":"\/Date(1377761466000)\/","StateDescription":"Delivered",

 "Price":"0.5"}

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

Описание

State

Статус сообщения (см. приложение).

ReportedDateUtc

Дата доставки. Указана в формате unixtime. Который показывает количество миллисекунд, прошедших с 1 января 1970 года.

Время указывается по UTC.

StateDescription

Описание статуса.

Price

Цена за сообщение.

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

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

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

Запрос

GET

/?sessionId=967648e7c4bc8929898862a4f0490f5e

 &minDateUTC=2011-01-01T00:00:00&maxDateUTC=2011-01-11T00:00:00

HTTP/1.1

Host gateway.api.sc/rest/Incoming/

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

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

Описание

sessionId

API ключ(36 символов). Обязательный.

minDateUTC

Минимальное значение периода за который происходит выборка входящих сообщений (пример 2010-06-01T19:14:00).
Время указывается по UTC.
Обязательный.

maxDateUTC

Максимальное значение периода за который происходит выборка входящих сообщений (пример 2010-06-02T19:14:00).
Время указывается по UTC.
Обязательный.


Ответ

HTTP/1.1 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

Идентификатор сообщения.

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

Данный функционал включается по запросу, через менеджера.

В запросе на включение функционала необходимо указать URL адрес, на который Платформа будет передавать, запрос с информацией о входящем номере



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

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

Запрос

GET

/?sessionId=967648e7c4bc5557182862a4f0490f5e

&startDateTime=2012-01-18%2000:00:00&endDateTime=2012-01-18%2023:59:00

HTTP/1.1

Host gateway.api.sc/rest/Statistic/

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

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

Описание

sessionId

API ключ (36 символов). Обязательный.

startDateTime

Дата и время начала периода, за который необходимо получить статистику, например 2012-01-18T00:00:00. Обязательный.

endDateTime

Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18T23:59:00. Обязательный.


Ответ

HTTP/1.1 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). 

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

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

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

Запрос

GET

/?sessionId=967648e7c4bc5557182862a4f0490f5e

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

HTTP/1.1

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

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

POST

sessionId=967648e7c4bc5557182862a4f0490f5e

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

HTTP/1.1

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

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

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

Описание

sessionId

API ключ (36 символов). Обязательный.

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 -по умолчанию) Необязательный.

type_load

Выбор формата отчета. Допустимые значения: 0, 1 (0 - csv по умолчанию, 1 - xls) Необязательный.

Ответ

HTTP/1.1 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

Запрос двух отчетов одновременно не разрешен, отправьте запрос позднее

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

/?sessionId=967648e7c4bc5557182862a4f0490f5e

&id_report=12124

HTTP/1.1

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

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

POST

sessionId=967648e7c4bc5557182862a4f0490f5e

&id_report=12124

HTTP/1.1

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

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

Коды ошибок

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

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

State

Описание

Тип статуса

-1

Отправлено (передано в мобильную сеть)

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

0

Доставлено абоненту

Окончательный

42

Не доставлено

Окончательный

46

Просрочено (истек срок жизни сообщения)

Окончательный

255

Недоступно (статус в архиве/нет доступа к статусу)

Окончательный

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