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» - «невідомо»