Skip to content

Mobile Id

Введение

На данной странице описаны программные интерфейсы (API) для аутентификации физического лица при помощи Mobile ID.

Полный список возвращаемых параметров вы можете увидеть здесь.

Протокол взаимодействия

В качестве транспортного протокола используется HTTP 1.1.

Для обеспечения безопасности при передаче данных используется TLS-шифрование.

Формат возвращаемых данных: JSON

Для задания формата ответа необходимо использовать http-заголовок “Accept”.

Для получения ответа в формате json: Accept: application/json

Поддержка сессий

API не поддерживает серверные сессии, т.е. является stateless. Аутентификация запросов производится при обработке каждого запроса.

Общее описание аутентификации с помощью Mobile ID

Процедура аутентификации при помощи Mobile ID предполагает следующие шаги:

  1. Формирование URL для перевода пользователя в сервис аутентификации.

    Необходимо воспользоваться вспомогательным методом POST /mnoAuth/start, который вернет сформированный URL на который контрагент должен перевести пользователя. При формировании URL необходимо указать параметр code, который уникально идентифицирует конкретную операцию аутентификации в системе контрагента.

  2. Вне зависимости от результата аутентификации пользователь возвращается на согласованный с контрагентом URL возврата (returnURL). При этом также передаются параметры:

    • code – см. п.1

    • operationToken – идентификатор операции в системе IDX

  3. Параллельно IDX возвращает контрагенту информацию о пользователе через согласованный callbackUrl. Возвращаемая информация включает:

    • ФИО

    • Дата рождения

    • Номер телефона

    • Паспортные данные (серия и номер, дата выдачи, кем выдан)

    • Адрес регистрации

  4. Вместо callbackUrl для получения информации о пользователе можно использовать метод getAsyncResult, передавая параметр operationToken, полученный в returnUrl (п.2).

Функции

POST mnoAuth/start

Данный вызов предназначен для формирования URL для старта аутентификации пользователя при помощи Mobile ID. Полученный URL должен передаваться в браузер пользователя.

Тип HTTP запроса: POST

URL вызова: https://api.id-x.org/idx/api2/mnoAuth/start

Поддерживаются следующие форматы передачи параметров:

  • JSON, Content-Type: application/json

  • Form submit, Content-Type: application/x-www-form-urlencoded

Параметры:

Параметр Тип Обязательный Описание
accessKey String Да Ключ доступа, выданный при регистрации в Системе IDX
secretKey String Да Секретный ключ, выданный при регистрации в Системе IDX
code String Да Уникальный код операции в системе контрагента
phone String Нет Телефон пользователя, если требуется предзаполнение. Формат: 79991112233
birthDate String Нет Дата рождения пользователя, если требуется предзаполнение. Формат: dd.MM.yyyy

Функция возвращает:

Параметр Тип Обязательный Описание
resultCode Int Да Результат выполнения функции (0 – успешное завершение функции, иные значения – ошибка выполнения)
resultMessage String Нет Сообщение об ошибке
operationToken String Нет Уникальный идентификатор операции в системе IDX
redirectUrl String Нет Сформированный URL для аутентификации

Пример вызова:

POST /idx/api2/mnoAuth/start
Host: api.id-x.org
Content-Type: application/json
Accept: application/json

{
    "accessKey": "выданный accessKey",
    "secretKey": "выданный secretKey",
    "code": "1234567890"
}

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

{
    "resultCode": 0,
    "operationToken": "a09062d0a75847b39f427b335c84da9b",
    "redirectUrl": "https://api.id-x.org/idx/api2/mnoAuth/start?
            token=7644ea65de1ba73285a62b2a2fdc5ab63df7fc3eaaa1ee348542e62bc61b4fa0"
}

Return - возврат пользователя после аутентификации

После процедуры аутентификации IDX возвращает пользователя на согласованный адрес возврата – returnUrl.

Для согласования пришлите желаемый returnUrl в письме на почту support@iidx.ru. Не забудьте указать желаемый формат передачи параметров и свой логин в системе IDX.

При этом в returnUrl добавляются следующие параметры:

  • code – идентификатор операции в системе контагента, переданный в вызов /mnoAuth/start

  • operationToken – уникальный идентификатор операции в IDX

Формат передачи параметров согласовывается отдельно. Ниже показаны варианты передачи параметров:

https://returnUrl?code={code}&token={operationToken}

https://returnUrl/{code}/{operationToken}

Callback - возврат результатов аутентификации

После аутентификации пользователя, параллельно с возвратом пользователя в систему контрагента, IDX передает информацию о пользователе в систему контрагента. Для этого согласовывается адрес возврата результатов – callbackUrl.

Для согласования пришлите желаемый callbackUrl в письме на почту support@iidx.ru. Не забудьте указать выбранный метод авторизации, ключи/токен для авторизации запросов и свой логин в системе IDX.

Возвращаемые результаты включают следующие параметры:

Параметр Тип Обязательный Описание
resultCode Int Да Результат выполнения аутентификации (см. коды возврата)
resultMessage String Нет Сообщение об ошибке
operationToken String Да Уникальный идентификатор операции
code String Да Код операции в системе контрагента, переданный при вызове /mnoAuth/start
lastName String Нет Фамилия
firstName String Нет Имя
midName String Нет Отчество
birthDate String Нет Дата рождения в формате ДД.ММ.ГГГГ
birthPlace String Нет Место рождения
phone String Нет Номер телефона в формате 9991112233
passportNumber String Нет Номер паспорта (серия и номер слитно без разделителя)
issueDate String Нет Дата выдачи паспорта в формате ДД.ММ.ГГГГ
issueAuthority String Нет Кем выдан паспорт
issueDivision String Нет Код подразделения
address String Нет Адрес регистрации
addressInfo Объект AddressInfo Нет Подробная информация об адресе. Подробнее см. информация об адресе
smsCode String Нет Код подтверждения по СМС. Возвращается только в случае, если код был успешно отправлен, и клиент хоть раз корректно ввел код
partialSuccess Boolean Нет Признак частичного совпадения данных (true - найдена часть данных, false - не было найдено никакой информации, null - была найдена вся информация)

Особенности выполнения callback-вызова

  • Тип callback вызова – HTTP POST.

  • Формат передаваемых данных– application/json.

  • Для авторизации callback-вызовов на стороне контрагента могут использоваться следующие схемы:

NONE – без авторизации, не рекомендуется, обычно используется на этапе тестирования

BASIC – HTTP BASIC AUTH, авторизационная информация передается в заголовке Authorization: Basic

TOKEN - авторизация по токену, токен передается в заголовке Authorization: Token

BEARER – авторизация по токену , токен передается в заголовке Authorization: Bearer

  • Возвращаемый результат обработки callback вызова игнорируется.

Пример успешного callback вызова когда все данные найдены:

POST /callbackUrl
Host: {callbackHost}
Authorization: Token 435897345935730572356203456349087392734034738
Content-Type: application/json
Accept: application/json

{
    "resultCode": 0,
    "operationToken": "53d6868bec1f57483369f90987a71f2",
    "code": "1234567890",
    "lastName": "Иванов",
    "firstName": "Иван",
    "midName": "Иванович",
    "birthDate": "31.12.1970",
    "phone": "9991112233",
    "passportNumber": "4510123456",
    "issueDate": "31.12.2010",
    "issueAuthority": "ОВД Бассманный"
    "address": "г. Москва, ул.Строителей, д.22, кв.1",
    "addressInfo": {
        "postalCode": "119311",
        "country": "Россия",
        "regionType": "город",
        "region": "Москва",
        "streetType": "улица",
        "street": "Строителей",
        "house": "22",
        "flat": "1"
    },
    "smsCode": "1234"
}

Пример успешного callback вызова когда найдена только часть данных:

POST /callbackUrl
Host: {callbackHost}
Authorization: Token 435897345935730572356203456349087392734034738
Content-Type: application/json
Accept: application/json

{
    "resultCode": 0,
    "operationToken": "53d6868bec1f57483369f90987a71f2",
    "code": "1234567890",
    "birthDate": "31.12.1970",
    "phone": "9991112233",
    "smsCode": "1234",
    "partialSuccess": true
}

Пример успешного callback вызова когда данные не найдены:

POST /callbackUrl
Host: {callbackHost}
Authorization: Token 435897345935730572356203456349087392734034738
Content-Type: application/json
Accept: application/json

{
    "resultCode": -100,
    "operationToken": "53d6868bec1f57483369f90987a71f2",
    "code": "1234567890",
    "birthDate": "31.12.1970",
    "phone": "9991112233",
    "smsCode": "1234",
    "partialSuccess": false
}

Пример ошибочного callback вызова:

POST /callbackUrl
Host: {callbackHost}
Authorization: Token 435897345935730572356203456349087392734034738
Content-Type: application/json
Accept: application/json

{
    "resultCode": -120,
    "resultMessage": "Аутентификация при помощи СМС не пройдена",
    "operationToken": "53d6868bec1f57483369f90987a71f2",
    "code": "1234567890",
    "birthDate": "31.12.1970",
    "phone": "9991112233",
    "smsCode": "1234",
    "partialSuccess": false
}

Информация об адресе

Это объект, содержащий следующие атрибуты:

Атрибут Тип Описание
postalCode String Почтовый индекс
country String Страна
regionType String Тип региона
region String Регион
areaType String Тип района в регионе
area String Район в регионе
cityType String Тип города
city String Город
streetType String Тип улицы
street String Улица
house String Дом
block String Корпус/строение
flat String Квартира

GetAsyncResult

Дополнительный способ получения результатов аутентификации, может использоваться как альтернатива Callback.

Тип HTTP запроса: POST

URL вызова: https://api.id-x.org/idx/api2/getAsyncResult

Поддерживаются следующие форматы передачи параметров:

  • JSON, Content-Type: application/json

  • Form submit, Content-Type: application/x-www-form-urlencoded

Параметры:

Параметр Тип Обязательный Описание
accessKey String Да Ключ доступа, выданный при регистрации в Системе IDX
secretKey String Да Секретный ключ, выданный при регистрации в Системе IDX
operationToken String Да Токен операции

Функция возвращает результат, аналогичный возвращаемому в callback-вызове.

Коды возврата

Код Название Описание
0 success Успешное выполнение, данные были найдены
-1 unknownError Неизвестная ошибка
-30 resultExpired Срок хранения результата истек
-31 incorrectParameter От клиента были получены некорректные данные
-100 notFound Все отработало корректно, но данные не были найдены
-120 operationNotCompleted Ошибка аутентификации по СМС

Тарифицируются результаты 0, -100 и -120. Остальные результаты считаются ошибочными. Вызов /getAsyncResult тарификации не подлежит.

Подключение проверки в iframe

Проверка поддерживает встраивание в интерфейс через iframe. Общие принципы подключения, описание механизма postMessage, а также пример обработки сообщений в родительском окне приведены в разделе Интеграция проверок через iframe.

Во время выполнения проверки страница внутри iframe может отправлять родительскому окну следующие сообщения:

Название Описание
verify_success Проверка завершена успешно, данные получены
verify_error Проверка завершена с ошибкой