Описание API

Услуга предоставления информации с использованием транзакционного сервиса предназначена для получения информации о телефонных номерах.

Рабочим протоколом транзакционного сервиса является HTTPs.

Структура и логика его работы аналогична работе других веб-технологий: пользователь формирует запрос с указанием телефонного номера, на который сервис отвечает сообщением с указанием информации о запрашиваемом телефонном номере. Запрос происходит по URL сервиса с указанием телефонного номера в качестве параметра, а ответ является текстом в формате JSON в готовом для дальнейшей обработки виде.

Транзакционный сервис реализован таким образом, что в рамках одного запроса можно получить информацию только по одному телефонному номеру. Указанная реализация позволяет сформировать несколько запросов по разным телефонным номерам один за другим в рамках установленной первым запросом HTTPs-сессии.

Информация о телефонном номере предоставляется простым HTTPs-сервисом, использующим тип запроса GET или POST с параметром, указывающим телефонный номер, для которого требуется получить информацию. Сервис использует Bearer аутентификацию.

Пример GET-запроса:
https://nums.zniis.ru:9088/get?phone=9000000000, где 9000000000 – номер телефона.

HTTPs запрос должен иметь заголовки: "Authorization" (указать Bearer authentication).

Пример POST-запроса:
{"RequestType":"GetPhoneData",
"PhoneNumber":"9000000000"}

Ключевые слова JSON регистрозависимы.

Ответ сервиса на запрос посылается в формате JSON. Пример ответа предоставлен ниже:

{"org":"Оператор1",
"code":"mOPERATOR",
"mnc":"17",
"region":"77",
"region.name":"Москва и Московская область",
"portdate":"2014-01-01T00:00:00",
"Transaction ID":"00000000-0000-0000-0000-000000000000"}, где:

Наименование (О)бязательный / (Н)еобязательный Описание значения Возможные значения
org О Наименование оператора связи, в сети связи которого обслуживается телефонный номер  
code Н Код оператора связи в Информационной системе  
mnc Н Код сети оператора связи Две цифры (01, 02 и т.д.)
region Н Идентификатор региона (субъекта/субъектов РФ) Две цифры (77 – Москва и Московская область, 56 -Новосибирская область и т.д.)
region.name Н Название региона (субъекта РФ), в котором зарегистрирован данный номер  
region.detail Н Только для номеров сетей фиксированной связи
Точное название местности, где находится абонентский номер
 
portdate Н Дата последнего переноса телефонного номера Дата в формате ISO yyyy-mm-ddTHH:NN:SS
Transaction ID Н Номер транзакции, идентифицирующий запрос к Сервису Значение типа UUID

Решение использует следующие технологии:

REST API сервис (HTTP/1.1 GET и POST запросы),

JSON форматирование данных,

CORS – возможность осуществления запроса с помощью Javascript из веб-браузера.

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

  • механизм сверки (Аутентификации) и авторизации пользовательских прав Bearerauthentication согласно спецификации OAuth0;
  • HTTPs (SSL/TLS) - расширенный протокол HTTP, поддерживающий шифрование TLS v1.2 и TLSv1.3;
  • ограничение запросов по IP адресу (защита от DDoS).

Заголовок авторизации формируется следующим образом:
Authorization: Bearer <токен>

Пример заголовка авторизации:
Authorization: Bearer 7c04184e7e6dce64dd6bd7bcba9c5d9f86a85ebaed4ce8241ae2f305f5e30b16

Код Описание
400 400 Bad request
401 401 Unauthorized
403 403 Forbidden
404 404 Not found
429 429 Too Many Requests
431 431 Bad Header
451 451 Unavailable For Legal Reasons
500 500 Internal server error
504 504 Gateway timeout

Код ошибки отправляется в виде JSON. Сервис не использует коды состояния HTTP/1.1, поэтому HTTP статус всегда будет 200.

Пример ответа предоставлен ниже:

HTTP/1.1 200 OK
{"Error":"401",
"ErrorDescription":"401 Unauthorized"}

Пример запроса:
GET https://nums.zniis.ru:9088/get?phone=1000000000

Origin: http://zniis.ru
Authorization: Bearer 48a45a853c5560d373c681caff76c4bbda6244b52c07c411a705c912b8ac7964
Host: nums.zniis.ru:9088
Accept: application/json, charcode=utf-8
User-Agent: Mozilla/5.0

Пример ответа:
HTTP/1.1 200 OK

Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 158
Date: Wed, 04 Sep 2019 12:33:18 GMT
Access-Control-Allow-Origin: http://zniis.ru
Server: nginx/1.20.0
{"org":"Оператор1",
"Transaction ID":"00000000-0000-0000-0000-000000000000"}

_______________________
! Выделенная красным цветом строка является обязательной !