Общая информация о SMS API
SMS-платформа служит для взаимодействия клиентов с абонентами посредством SMS-сообщений.
Основные функции платформы:
- отправка сообщений;
- получение статусов доставки сообщений;
- получение входящих сообщений;
- получение статуса сервиса.
Для подключения к платформе разработаны коннекторы – протоколы взаимодействия. Коннектор HPX основан на передаче XML-документов посредством протокола HTTP.
Термины и сокращения
| Термин | Определение |
|---|---|
| SMS-платформа, платформа | Платформа, разработанная компанией edna для коммуникации клиентов с получателями посредством SMS-сообщений. |
| Абонент | Владелец мобильного устройства, конечный получатель сообщений. |
| Клиент | Организация, использующая возможности платформы, или программное обеспечение, установленное на серверах этой организации и реализующее интерфейс взаимодействия. |
| Контент | Информационное содержимое сообщения. |
| Провайдер | Компания edna, предоставляющая сервисы клиентам. |
| Подпись | Идентификатор клиента, от имени которого происходит отправка сообщений. |
| Префикс | Начальная часть нескольких номеров или полный номер телефона. |
| MNP | Mobile Number Portability – сохранение телефонного номера после смены оператора мобильной связи. Данные MNP позволяют определять оператора с учетом переноса телефонных номеров. |
Схема взаимодействия
Ниже представлена схема взаимодействия клиента с абонентами.

Общее описание протокола
Протокол HPX дает клиенту следующие возможности:
-
отправлять исходящие сообщения;
-
запрашивать идентификаторы исходящих сообщений;
-
запрашивать статусы доставки сообщений;
-
получать входящие сообщения от абонентов;
-
запрашивать статус сервиса провайдера.
Все виды операций взаимодействия между клиентом и платформой инициируются клиентом. Платформа работает как сервер за исключением случаев передачи статусов отправленных сообщений и входящих сообщений методом обратного вызова (callback).
Платформа маршрутизирует сообщения абонентам через SMS-шлюзы операторов сотовой связи, принимает от шлюзов операторов данные по статусам сообщений и обеспечивает поддержку соединения с этими шлюзами.
Клиенты отправляют HTTP-POST-запросы. Формат передачи данных определяется заголовком HTTP-запроса Content-Type. Допустимые значения: application/xml или application/json.
Если в запросе не указано значение заголовка Content-Type, заголовок имеет значение application/xml или заголовок имеет значение отличное от application/json — сервер будет ожидать запрос в формате XML. Ответ будет также возвращён в формате XML.
Если пакет содержит данные, кодировка которых не входит в таблицу символов ASCII, то следует использовать кодировку UTF-8.
Все пакеты имеют одинаковую структуру и состоят из двух разделов: header (заголовок) и payload (полезная нагрузка). Раздел header в пакетах клиента содержит аутентификационную информац ию, в ответах платформы этот раздел не содержит данных. В callback-запросах, отправляемых платформой, раздел header содержит данные для авторизации на стороне клиента. В разделе payload передаются идентификаторы абонентов и сообщений, приоритет, контент и статус доставки сообщений, коды ответов платформы и другие параметры.
Поскольку параметры раздела header одинаковы в пакетах одного типа, то в таблицах ниже представлены только параметры раздела payload.
Пример структуры пакета протокола
<RequestName>
<header>
<auth>
<login>string</login>
<password>string</password>
</auth>
</header>
<payload><!--параметры пакета--></payload>
</RequestName>
Авторизация
Перед началом работы с API необходимо сообщить в компанию edna IP-адрес, с которого будет выполняться подключение.
В запросах используется Basic-авторизация. Логин login и пароль password передаются в теле запроса в элементе auth секции header.
Данные авторизаци и для обращения к серверу определяются на этапе подключения сервиса. Данные по умолчанию для тестового использования:
- логин:
test; - пароль:
test.
Примеры авторизации
<!-- XML -->
<provideAddressOperatorRequest>
<header>
<auth>
<login>test</login>
<password>test</password>
</auth>
</header>
...
</provideAddressOperatorRequest>
Типы используемых данных
| Параметр | Описание |
|---|---|
Object | Объект, содержащий набор данных |
Address | Номер мобильного телефона абонента в формате E.164 |
Boolean | Параметры, которые принимают одно из строковых значений: true или false |
Datetime | Дата и время в формате yyyy-MM-dd hh:mm:ss |
Id | Уникальные идентификаторы |
Integer | Целые положительные числа |
String | Строка символов в кодировке UTF-8 |