Регистрация
Подключиться
Я даю согласие на обработку персональных данных
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 сессии описывается следующей схемой:

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

Сессия стартует когда 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
  • Со стороны абонента
  • Проблемы с сетью

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

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

Для управления сессией используется два метода start и release, доступные соответственно по адресам:
https://auth.terasms.ru/ussdapi/start/json и https://auth.terasms.ru/ussdapi/release/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:
Пример на языке программирования 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:

Пример на языке программирования 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 показывает удачно ли завершился запрос. Расшифровки кодов ниже:
- 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 методы запросов представлены ниже:

Пример запроса и ответа метода 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:
Параметры ответа:
пояснение к коду обработки, "" – если не возникло ошибок
Коды результата обработки запроса:
Пример запроса и ответа метода 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:
Коды результата обработки запроса аналогичны методу 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:
Параметры ответа метода response:
Коды результата обработки запроса аналогичны методу 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:
Коды результата обработки запроса аналогичны методу status
Регистрация
Подключиться
Я даю согласие на обработку персональных данных
Заказать просчет
It's totally free