API для SMS интерактивов

Данный документ является описанием протокола взаимодействия программного обеспечения компаний-партнеров с платформой Start Mobile в рамках проекта SMS-интерактив [скачать API для SMS интерактивов].. Протокол обеспечивает программному обеспечению партнеров следующие возможности:

  • прием сообщений от операторов и отправку партнерам в едином формате
  • отправку ответных сообщений SMS мобильным абонентам
  • получение информации о статусе отосланных сообщений

Существенными целями при разработке данного протокола являлись:

  • гибкость и расширяемость
  • простота реализации
  • отсутствие необходимости в сложном программном обеспечении со стороны партнеров

Исходя из указанных целей, в качестве основы для протокола был выбран обмен XML-сообщениями через протокол HTTP. Использование языка XML обеспечивает необходимую гибкость и расширяемость. Наличие большого количества готовых средств генерации и обработки XML, а также простая структура протокола делают реализацию клиентской части не очень сложной.

Протокол опирается на стандартную модель "клиент-сервер", причем при доставке входящего SMS партнеру в качестве клиента выступает платформа Start Mobile, а в качестве сервера — программное обеспечение партнера. При отправке ответа роли клиента и сервера меняются на противоположные

Следующий раздел данного документа содержит описание взаимодействия клиента и сервера на нижнем уровне (уровне HTTP). Последующие два раздела подробно описывают два основных типа запросов. Наконец, в последнем разделе приведены формальные спецификации протокола.

Протокол нижнего уровня

Как уже говорилось ранее, в качестве транспортного уровня для описываемого протокола был выбран протокол HTTP. Соответственно, на нижнем уровне все запросы клиента к серверу выглядят как обычные HTTP запросы, использующие метод POST, в которых тело запроса является XML-текстом. В результате выполнения запроса, ПО сервера возвращает XML-текст, содержащий результат. Тип возвращаемого результата (Content-Type) всегда text/xml.

Доставка сообщений партнеру

Для доставки сообщения партнеру, платформа Start Mobile передает серверу партнера XML-запрос следующего вида:

Отсылка одиночного сообщения:

<message>
    <service type="тип" timestamp="message_timestamp" auth="authorization_line" request_id=”id_запроса”/>
    <from>номер абонента</from>
    <to>сервисный номер</to>
    <body content-type="тип содержимого" encoding="кодировка">
    текст сообщения
    </body>
</message>

Здесь:

  • тип – на данный момент значение параметра должно быть равно «sms».
  • message_timestamp — время отправки сообщения абонентом (в случае, когда его возможно определить) или время получения сообщения платформой StartMobile в формате UNIX-time.
  • authorization_line — строка авторизации, вычисляемая как стандратная хэш-функция md5 от строки ”login:password:message_timestamp”, где login и password – параметры, выданные партнеру при подключении к системе;
  • id_запроса — идентификатор сообщения в системе StartMobile;
  • кодировка - задает кодировку тела сообщения, если тело сообщения двоичное. Для текстовых сообщений (тип сообщения - text/plain) данный параметр можно опустить, либо установить равным plain. Допустимые значения кодировки - следующие:
    • plain - кодирование отсутствует. Данный тип допустим только для текстовых сообщений в UTF-8
    • base64 - тело сообщения закодировано как BASE64 (см. стандарт MIME)

В результате обработки запроса, сервер партнера возвращает клиенту результат следующего вида в зависимости от режима обработки сообщения:

а) Синхронный режим. Сервер партнера возвращает ответ для абонента:

<answer type="тип_ответа">
        <body paid=”флаг_платности”>
        Текст ответа
        </body>
</answer>

Здесь:

  • тип_ответа – для синхронного режима тип ответа должен быть установлен в «sync».
  • флаг_платности — может принимать значения true или false, позволяет определить, является ли ответ платным для абонента. Возможность поддерживается только при типе тарификации МТ и не для всех операторов.
  • Текст ответа — текст ответа, который будет отправлен абоненту. Тег body может повторяться несколько раз — в этом случае абоненту будет отправлено несколько ответов.

б) Асинхронный режим. Сервер партнера возвращает только подтверждение приема запроса:

<answer type="тип_ответа">
        <state>
        Accepted
        </state>
</answer>

Здесь:

  • тип_ответа – для асинхронного режима тип ответа должен быть установлен в «async».

В случае работы в асинхронном режиме после обработки система партнера должна прислать платформе StartMobile ответ для абонента в следующем формате:

<answer request_id="id_запроса" auth=”authorization_line” timestamp=”answer_timestamp”>
        <body paid=”флаг_платности”>
        Текст ответа
        </body>
</answer>

Все поля формируются аналогично выше описанным.

Получение информации о статусе сообщения

Для получения информации о статусе сообщения, партнер должен послать серверу запрос следующего вида:

<request id="id_запроса">status<request>

В ответ платформа Start Mobile выдает следующее:

<status>
<state answer='1'>состояние</state>
<state answer='2'>состояние</state>
…
<state answer='N'>состояние</state>
<status>

где «состояние» может принимать значения:

  • «enroute» - «доставляется»
  • «delivered» - «доставлено»
  • «undeliverable» - «доставка невозможна»
  • «expired» - «истек срок доставки»
  • «unknown» - «неизвестно»