/sms_otp_notification

Назначение

sms_otp_notification_uri — callback сервис-провайдера, который Мобильный ID вызывает в процессе выполнения асинхронной операции аутентификации пользователя в SI-режиме, если для аутентификации задействован способ SMS-OTP.

В качестве endpoint используется предварительно зарегистрированное в сервисе Мобильный ID значение sms_otp_notification_uri.

POST https://service-provider.io/sms_otp_notification_uri/
Authorization: Bearer {client_notification_token}
Content-Type: application/json

Запрос

Заголовки

Параметр	Описание	Пример
`Authorization`	Тип авторизации и данные пользователя. В качестве значения bearer-токена используется значение параметра `client_notification_token`, предоставленное в исходном запросе.	`Bearer 53f4f85c-4fca-454e-92f5-3996e46f246c`
`Content-Type`	Тип передаваемого контента. По умолчанию `application/json`.	`application/json`
`X-Mobileid-Request-Id`	Уникальный идентификатор запроса. Используется в рамках оказания технической поддержки.	`0a1f42a5307e6d7435b6a20a1cbf8c78`
`X-Mobileid-Transaction-Id`	Уникальный идентификатор транзакции. Используется в рамках оказания технической поддержки.	`0b4f8e2d-2040-4e65-b404-055af6625e7e`

Параметры

Параметр	Описание	Обязательный	Пример
`auth_req_id`	Идентификатор запроса аутентификации	Да	`932eb8e1-cc0c-4b95-9962-d89dabad4711`
`smsotp_endpoint`	Динамический HTTPS URL для отправки запроса на проверку кода из SMS	Да	`https://idgw.mobileid.mts.ru/verify/5e48eace-83b9-4427-abe3-58fbcfe5d949`
`send`	Произвольная json-структура, регламентирующая тело запроса на проверку кода из SMS. Может отличаться в зависимости от принадлежности номера телефона к оператору. Обязательно содержит параметр со значением `enter_otp_code`, которое используется для подстановки в запрос кода из SMS, введённого пользователем.	Да	`{ "verify_code": "enter_otp_code" }`
`correlation_id`	Уникальный сквозной идентификатор для всех запросов в рамках одной транзакции. Возвращается в случае, если одноимённый параметр был использован в исходном запросе. Значение совпадает со значением, переданным в исходном запросе.	Нет	`05c4ac02-9144-411c-9279-166ac637528f`

Пример запроса

POST https://service-provider.io/sms_otp_notification_uri/
Authorization: Bearer 53f4f85c-4fca-454e-92f5-3996e46f246c
X-Mobileid-Request-Id: 0a1f42a5307e6d7435b6a20a1cbf8c78
X-Mobileid-Transaction-Id: 0b4f8e2d-2040-4e65-b404-055af6625e7e
Content-Type: application/json

{
  "auth_req_id": "932eb8e1-cc0c-4b95-9962-d89dabad4711",
  "smsotp_endpoint": "https://idgw.mobileid.mts.ru/verify/5e48eace-83b9-4427-abe3-58fbcfe5d949",
  "send": {
    "verify_code": "enter_otp_code"
  },
  "correlation_id": "05c4ac02-9144-411c-9279-166ac637528f"
}

Успешный ответ

В случае успешной обработки запроса сервис-провайдер должен ответить HTTP-кодом 200 или 204.

Сообщения об ошибках

Реализация остаётся на усмотрение сервис-провайдера.

Рекомендованные операции:

проверка формата запроса;
проверка наличия и времени жизни auth_req_id;
проверка авторизации.

Также рекомендуется при формировании ответов руководствоваться общей стилистикой API-контракта:

использовать HTTP-коды 4xx и 5xx;
включать в ответ параметры error и error_description с описанием ошибки.

Отправка OTP-кода

Для выполнения запроса используются значения параметров, полученные в нотификации SMS-OTP.

POST {smsotp_endpoint}
Content-Type: application/json

Параметры

Параметр	Описание	Обязательный	Пример
Не определено	Набор параметров, необходимых для формирования тела запроса, предоставляется в качестве значения параметра `send` в составе запроса нотификации SMS-OTP. Введённый пользователем OTP-код необходимо передать вместо значения `enter_otp_code`.	Да	`{ "verify_code": "1234" }`

Пример запроса

POST https://idgw.mobileid.mts.ru/verify/5e48eace-83b9-4427-abe3-58fbcfe5d949
Content-Type: application/json

{
  "verify_code": "1234"
}

Успешный ответ

В случае успешной обработки запроса и проверки кода будет предоставлен ответ с HTTP-кодом 200. Тело ответа будет пустым.

Сообщения об ошибках

Параметр	Описание	Пример
`Content-Type`	Тип передаваемого контента. Всегда `application/json`.	`application/json`
`X-Mobileid-Error`	Категория ошибки	`invalid_request`
`X-Mobileid-Request-Id`	Уникальный идентификатор запроса. Используется в рамках оказания технической поддержки.	`0a1f42a5307e6d7435b6a20a1cbf8c78`
`X-Mobileid-Transaction-Id`	Уникальный идентификатор транзакции. Используется в рамках оказания технической поддержки.	`0b4f8e2d-2040-4e65-b404-055af6625e7e`
`error`	Категория ошибки	`invalid_request`
`error_description`	Описание ошибки	`invalid otp code`
`retry_count`	Целое число, указывающее на оставшееся количество попыток проверки кода	`2`

Пример ответа с ошибкой

HTTP 400
Content-Type: application/json
X-Mobileid-Request-Id: 0a1f42a5307e6d7435b6a20a1cbf8c78
X-Mobileid-Transaction-Id: 0b4f8e2d-2040-4e65-b404-055af6625e7e
X-Mobileid-Error: invalid_request

{
  "error": "invalid_request",
  "error_description": "invalid otp code",
  "retry_count": 2
}

Негативные сценарии и используемые значения error и error_description

Сценарий	HTTP-код	Error	Error_description
Предоставлен некорректный OTP-код	400	`invalid_request`	`invalid otp code`
Не найдена связанная транзакция аутентификации или время её «жизни» истекло	404	`invalid_request`	`sms session not found`
Параметр, содержащий OTP-код, отсутствует или имеет пустое значение	400	`invalid_request`	`required parameter "%parameter%" is missing or empty`
Передан пустой идентификатор сессии для проверки SMS-OTP кода	400	`invalid_request`	`url id not found`
Переданный идентификатор сессии для проверки SMS-OTP кода не соответствует формату UUIDv4	400	`invalid_request`	`invalid url id`
Предыдущий запрос на проверку SMS-OTP кода ещё в работе	403	`access_denied`	`verification of SMS-OTP code in progress`
Внутренняя ошибка	500	`server_error`	`internal server error`

Если код принят, Мобильный ID продолжает сценарий и затем отправляет итоговый /notification.