USSD API (HTTPS, JSON)

Введение

USSD (Unstructured Supplementary Service Data) — стандартный сервис в сетях GSM, позволяющий организовать интерактивное взаимодействие между абонентом сети и сервисным приложением в режиме передачи коротких сообщений.
USSD-сервис во многом схож с SMS, оба сервиса используют для передачи данных формат коротких сообщений. Однако USSD в основном предназначен для обмена сообщениями между абонентом и дополнительными сервисами.
Основное направление использования USSD-сервиса — предоставление абонентам возможности получать дополнительную информацию от приложений и управлять этими приложениями. USSD работает на всех существующих телефонах стандарта GSM, за исключением самых ранних моделей 1998—1999 годов выпуска.
USSD-сервис поддерживает два вида сессий, USSD Phase 1 и USSD Phase 2 (инициирование сессии со стороны USSD-приложения). Обе вида во многом схожи и отличаются по большей части лишь способом вызова.
Приложение, использующее данное API инициализирует сессии вида USSD Phase 2
Сессия представляет собой последовательность связанных друг с другом сообщений в следущей последовательности: вопрос от приложения –ответ оператора (абонента) - вопрос от приложения –ответ оператора (абонента) … вопрос от приложения. В дальнейшем вместо термина «вопрос от приложения» будет употребляться общепринятый термин “меню”
Меню — это текст содержащий вопрос и/или инструкции по продолжению диалога

Примером меню может быть такой текст:

Выберите услугу:
1 — перевод
2 — блокировка карты
0 — выход
или
Оцените качество предоставляемых услуг

Возможны две кодировки меню:
GSM-7 — «латиница», до 182 символов на меню
UCS2 — «юникод» UTF-16, до 67 символов на меню

Точные ограничения зависят от конкретного оператора сотовой связи. Ответы абонентов допускают только латиницу и цифры.

API

Течение сессии можно разделить на три этапа: старт, общение и завершение

Сессия стартует когда USSD приложение посылает запрос на URL https://auth.terasms.ru/ussdapi/start/json с указанием номера телефона абонента, кодировки и пр. параметрами ( все параметры будут указаны ниже).

После этого платформа инициализирует сессию и посылает запрос на адрес партнера {base_ur}/start, где {partner_url} – это URL партнера, например http://partner_host/partner_script указанный вами

В ответ на запрос скрипт партнера , скрипт расположенный по адресу {base_url}/start отдает первое меню пересылаемое платформой сначала оператору, а затем абоненту.
Фаза “общения” начинается когда получен первый ответ от абонента (параметр text). Ответ доставляется путем запроса платформы к скрипту партнера расположенному по адресу {base_url}/response. В ответ платформа ожидает следующее меню с флагом shouldClose, который говорит платформе будет ли меню завершающим или нет. Как только приходит очередной ответ от пользователя фаза повторяется.
“Общение” продолжается до тех пор пока сессия не завершится.
События приводящие к завершению сессии:

  • Со стороны приложения, при отправке меню с флагом shouldClose = true (завершающее меню)
  • Со стороны приложения, запрос https://auth.terasms.ru/ussdapi/release/json
  • Со стороны абонента
  • Проблемы с сетью
Статус Описание
200 Сессия завершена нормально (завершающее меню)
500 Сессия завершена из-за проблем с сетью
510 Сессия завершена USSD приложением
520 Сессия завершена абонентом
600 Превышен таймаут

В ответ посылаются ответ, подтверждающий что мы приняли запрос. Подробно все параметры будут описаны ниже.

Описание методов платформы

Для управления сессией используется два метода start и release, доступные соответственно по адресам:
https://auth.terasms.ru/ussdapi/start/json и https://auth.terasms.ru/ussdapi/release/json

Метод HTTP метод Формат данных
start HTTP POST JSON
release HTTP POST JSON

Пример запроса и ответа метода start:

>> POST https://auth.terasms.ru/ussdapi/start/json HTTP/1.1
>> Content-Length: 45
>> Content-Type: application/json
>> Host: localhost:80
>> Connection: Keep-Alive
>>
>> {
>> "login" => "login",
>> "password" => "password",
>> "bill_type" => "s",
>> "optional" => "id=234",
>> "destinstionAddr" => "79569900099",
>> "lang" => "UCS2"
>> }

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: hr-HR
<< Transfer-Encoding: chunked
<< Date: Thu, 08 Oct 2010 10:27:24 GMT
<<
<< {"responseExitCode":200,"responseMessage":"OK"}

Параметры запроса метода start:

Параметр Значения Описание
login строка обязательный параметр

Логин и пароль Партнера на Платформе TERASMS
password строка
billType строка обязательный параметр
s - Тарификация по сессиям
r - Тарификация по реквестам
destinationAddr строка обязательный параметр
Номер абонента в международном формате. Пример: 79161111111
optional строка необязательный параметр
дополнительные параметры которые вы хотите передать вашему приложению при старте сессии, не меняются в течении всей сессии
optional строка обязательный параметр
кодировка в котором меню будут передаваться абоненту

Пример на языке программирования php:

$api_uri = "https://auth.terasms.ru/ussdapi/start/json";
$query_array = array(
"login" => "login",
"password" => "password",
"billType" => "r",
"optional" => "id=234",
"destinationAddr" => "79569900099"
);
$context = stream_context_create( array(
"http" => array(
"method"  => "POST",
"content" => http_build_query( $query_array ),
"timeout" => 10,
    ),
));
$response  = file_get_contents( $api_uri, false, $context);

Пример запрос и ответа метода release:

>> POST https://auth.terasms.ru/ussdapi/release/json  HTTP/1.1
>> Content-Length:234
>> Content-Type: application/json
>> Host: localhost:80
>> Connection: Keep-Alive
>>
>> {
>> "sessionId" : "13edc5f863606c69766531",
>> "reason" : "test reason",
>> "login" => "login",
>> "password" => "password",
>> }

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: hr-HR
<< Transfer-Encoding: chunked
<< Date: Thu, 08 Oct 2010 11:38:29 GMT
<<
<< {"responseExitCode":200,"responseMessage":""}

Параметры запроса метода release:

Параметр Значения Описание
login строка обязательный параметр
Логин и пароль Партнера на Платформе TERASMS
password строка
sessionId строка обязательный параметр
Идентификатор сессии идентификатор сессии
reason строка обязательный параметр
Причина по которой была завершена сессия

Пример на языке программирования php:

$api_uri = "https://auth.terasms.ru/ussdapi/release/json";
$query_array = array(
"login" => "login",
"password" => "password",
"sessionId" => "13edc5f863606c69766531",
"reason" => "password",
);
$context = stream_context_create( array(
"http" => array(
"method"  => "POST",
"content" => http_build_query( $query_array ),
"timeout" => 10,
    ),
));
$response  = file_get_contents( $api_uri, false, $context);

Ответ в обоих случаях приходит в JSON формате и содержит в себе два параметра
-responseExitCode показывает удачно ли завершился запрос. Расшифровки кодов ниже:

Статус Описание
200 Запрос прошел без ошибок
400 Ошибка обработки JSON данных
401 Ошибка авторизации
500 Внутренняя ошибка сервера
-10 Способ тарификации задан неверно (bill_type)
-30 Номер абонента задан неверно (destinationAddr)
-40 Кодировка задана неверно (lang)
-70 Недостаточно средств на счете

-responseMessage указывает возможную причину ошибки

Описание методов партнера

Приложение со стороны партнера должно располагать следующими методами, расположенными по адресу:

{partner_url} / status
{partner_url} / start
{partner_url} / response
{partner_url} / end

Значение partner_url зависит от сервера на котором расположено приложение партнера, например http://partner_host/partner_script.

Тело HTTP запроса представляет собой данные в JSON формате (кроме метода status) заданных кодировке UTF-8. HTTP методы запросов представлены ниже:

Метод HTTP метод
status HTTP GET
start HTTP POST
response HTTP POST
end HTTP POST

Пример запроса и ответа метода status:

>> GET {partner_url}/6651/status HTTP/1.1
>> Host: localhost:80
>> Connection: Keep-Alive

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: en-US
<< Transfer-Encoding: chunked
<< Date: Thu, 18 Oct 2012 10:18:00 GMT
<<
<< {"sessionActive":true,"responseExitCode":0,"responseMessage":""}

Параметры запроса метода status:

Параметр Значения Описание
sessionId строка обязательный параметр
идентификатор сессии

Параметры ответа:

Параметр Значения Описание
sessionActive boolean True если сессия активна, false если завершена
responseExitCode строка обязательный параметр
код результата обработки запроса
responseMessage строка  

пояснение к коду обработки, “” – если не возникло ошибок
Коды результата обработки запроса:

Статус Описание
200 Запрос прошел без ошибок
400 Ошибка обработки JSON данных
500  

Пример запроса и ответа метода start:

>> POST {partner_url}/6651/status HTTP/1.1
>> Content-Length: 17
>> Content-Type: application/json
>> Host: localhost:80
>> Connection: Keep-Alive
>>
>> {
>> "sessionId":"13ee0c52f8326c69766531",
>> "destinationAddr":"79079007899",
>> "text":"",
>> "optional":"id=234"
>> }

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: en-US
<< Transfer-Encoding: chunked
<< Date: Thu, 08 Oct 2012 12:28:53 GMT
<<
<< {
<< "shouldClose":false,
<< "ussdMenu":"1. Проверить баланс\n0. Выход ",
<< "responseExitCode" => 200,
<< "responseMessage" => ''
<< }

Параметры запроса метода start:

Параметр Значения Описание
sessionId строка обязательный параметр
идентификатор сессии
destinationAddr строка обязательный параметр
Номер абонента в международном формате. Пример: 79161111111
optional строка необязательный параметр
дополнительные параметры переданные в одноименном параметре при старте сессии (вызов https://auth.terasms.ru/ussdapi/start/json )

Параметры ответа метода start:

Параметр Значения Описание
shouldClose boolean обязательный параметр
true если это последнее меню , отправляемое абоненту (завершающее меню), false если сессия продолжается
ussdMenu строка обязательный параметр
ussd меню отправляемое пользователю, для переноса строки используется “\n”
responseExitCode строка обязательный параметр
код результата обработки запроса
text строка необязательный параметр
эмуляция ответа абонента на отправленное меню

Коды результата обработки запроса аналогичны методу status

Пример запроса и ответа метода response:

>> POST {partner_url}/6651/status HTTP/1.1
>> Content-Length: 96
>> Content-Type: application/json
>> Host: localhost:80
>> Connection: Keep-Alive
>>
>> {
>> "sessionId":"13ee0c52f8326c69766531",
>> "destinationAddr":"79079007899",
>> "optional":"id=234"
>> "conversation":"menu_id=3&count=2",
>> "text" : "1"
>> }

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: en-US
<< Transfer-Encoding: chunked
<< Date: Thu, 18 Oct 2013 11:21:01 GMT
<< {
<< "shouldClose":false,
<< "ussdMenu":"Оцените качество работы сервиса",
<< "conversation":"menu_id=3&count=2",
<< "responseExitCode":"200",
<< "responseMessage":""
<< }

Параметры запроса метода response:

Параметр Значения Описание
sessionId строка обязательный параметр
destinationAddr строка обязательный параметр
обязательный параметр Номер абонента в международном формате. Пример: 79161111111
optional строка необязательный параметр
дополнительные параметры переданные в одноименном параметре при старте сессии (вызов https://auth.terasms.ru/ussdapi/start/json)
text строка обязательный параметр
ответ абонента на отправленное меню
conversation строка необязательный параметр
если в ответе с меню передавался параметр conversation он вернется вместе с ответом

Параметры ответа метода response:

Параметр Значения Описание
shouldClose boolean обязательный параметр
true если это последнее меню , отправляемое абоненту (завершающее меню), false если сессия продолжается
ussdMenu строка необязательный параметр
возвращается с ответом только если был передан с вместе с меню , используется для хранения промежуточной информации партнера, например идентификатора предыдущего меню
conversation строка  
responseExitCode строка обязательный параметр
код результата обработки запроса
responseMessage строка обязательный параметр
“” – если не возникло ошибок

Коды результата обработки запроса аналогичны методу status

Пример запроса и ответа метода end:

>> PUT {partner_url}/6651/end HTTP/1.1
>> Content-Length: 87
>> Content-Type: application/json
>> Host: localhost:8
>> Connection: Keep-Alive
>>
>> {
>> "sessionId":"13ee0c52f8326c69766531",
>> "reason" : "ok",
>> "exitCode" : 200
>> }

<< HTTP/1.1 200 OK
<< Server: Apache-Coyote/1.1
<< Content-Language: en-US
<< Transfer-Encoding: chunked
<< Date: Thu, 06 Oct 2012 02:21:54 GMT
<<
<< {"responseExitCode":0,"responseMessage":""}

Параметры запроса метода end:

Параметр Значения Описание
sessionId строка обязательный параметр
идентификатор сессии
reason строка обязательный параметр
сообщение о причине завершения сессии
exitCode строка обязательный параметр
код завершения сессии, расшифровка указаны в конце раздела 3. AP
responseExitCode строка обязательный параметр
код результата обработки запроса
responseMessage строка обязательный параметр
пояснение к коду обработки, “” – если не возникло ошибок

Коды результата обработки запроса аналогичны методу status