Перейти к основному содержимому

Общая информация о SMS API

SMS-платформа служит для взаимодействия клиентов с абонентами посредством SMS-сообщений.

Основные функции платформы:

  • отправка сообщений;
  • получение статусов доставки сообщений;
  • получение входящих сообщений;
  • получение статуса сервиса.

Для подключения к платформе разработаны коннекторы – протоколы взаимодействия. Коннектор HPX основан на передаче XML-документов посредством протокола HTTP.

Термины и сокращения​

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

Схема взаимодействия​

Ниже представлена схема взаимодействия клиента с абонентами.

alt text

Общее описание протокола​

Протокол HPX дает клиенту следующие возможности:

  • отправлять исходящие сообщения;

  • запрашивать идентификаторы исходящих сообщений;

  • запрашивать статусы доставки сообщений;

  • получать входящие сообщения от абонентов;

  • запрашивать статус сервиса провайдера.

Все виды операций взаимодействия между клиентом и платформой инициируются клиентом. Платформа работает как сервер за исключением случаев передачи статусов отправленных сообщений и входящих сообщений методом обратного вызова (callback).

Платформа маршрутизирует сообщения абонентам через SMS-шлюзы операторов сотовой связи, принимает от шлюзов операторов данные по статусам сообщений и обеспечивает поддержку соединения с этими шлюзами.

Клиенты отправляют HTTP-POST-запросы. Формат передачи данных определяется заголовком HTTP-запроса Content-Type. Допустимые значения: application/xml или application/json.

к сведению

Если в запросе не указано значение заголовка Content-Type, заголовок имеет значение application/xml или заголовок имеет значение отличное от application/json — сервер будет ожидать запрос в формате XML. Ответ будет также возвращён в формате XML.

warning

Если пакет содержит данные, кодировка которых не входит в таблицу символов 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

Методы​

File IconОтправка исходящих сообщений File IconЗапрос идентификаторов исходящих сообщений File IconЗапрос статусов доставки сообщений File IconПолучение статусов сообщений методом обратного вызова File IconПолучение входящих сообщений File IconПодтверждение получения входящих сообщений File IconПолучение входящих сообщений методом обратного вызова File IconПроверка статуса сервиса File IconПолучение информации об операторе File IconОбновление данных об операторах

Дополнительная информация​

File IconОтвет на ошибочный пакет