Mandarin

# Упрощенная идентификация

# Схема взаимодействия

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

  1. Проверка имени, отчества, фамилии, серии и номера паспорта, СНИЛС и ИНН (достаточно одного из двух: СНИЛС или ИНН, но возможно передавать оба) производится через СМЭВ.
  2. Проверка номера мобильного телефона выполняется с помощью отправки СМС-кода. Она проводится, только если вы передали номер мобильного телефона физического лица (в параметре phone).

Обе проверки занимают некоторое время. Сразу после инициализации булевы параметры personVerificationFinished и phoneVerificationFinished имеют значения false. По завершении проверки персональных данных personVerificationFinished принимает значение true, по окончании проверки номера телефона phoneVerificationFinished тоже становится равным true.

Когда проверка соответствующих данных завершена, булев параметр personVerified указывает на правильность персональных данных, булев параметр phoneVerified - на правильность номера мобильного телефона (если был передан). Когда оба параметра приняли значение true, то упрощенная идентификация считается пройденной.

Если были переданы и СНИЛС, и ИНН, то их проверка производится параллельно. В текущей реализации, булев параметр personVerified принимает значение результата той проверки, которая завершилась первой.

Запросы упрощенной идентификации используют стандартный для Mandarin способ аутентификации. Запросы как с боевыми, так и с тестовыми аутентификационными данными всегда включают в себя запрос в СМЭВ с реальными персональными данными, и реальную отправку СМС, и следовательно, являются боевыми.

ВАЖНО!

По умолчанию, функционал упрощенной идентификации отключен. Напишите в Cлужбу поддержки (opens new window) для получения доступа к упрощенной идентификации.
Система СМЭВ предоставляет результат проверки, как правило, в пределах 10 минут. Но время проверки может увеличиться по причинам, не зависящим от Mandarin.

Simplified Identification Diagram

ТЕСТИРОВАНИЕ

Данные для тестирования запросов по упрощенной идентификации находятся в отдельном разделе.

# Инициализация процесса идентификации

Запрос на инициализацию процесса идентификации должен включать в себя как параметр СНИЛС, так и параметр ИНН, причем один из этих двух параметров может быть пустым. Если вы хотите использовать и ИНН, и СНИЛС, то необходимо добавить поле с датой рождения клиента. В качестве серии и номера паспорта можно передать только данные паспорта гражданина РФ.

В случае успешной регистрации запроса вы синхронно получите идентификатор сессии id, который необходимо использовать в следующих запросах. Если был передан опциональный параметр phone, то на указанный в нем мобильный номер будет отправлено СМС-сообщение с кодом для подтверждения номера телефона.

Параметр Тип Обязателен Описание
firstName string Да Имя.
patronymic string Да Отчество.
lastName string Да Фамилия.
passportSeries string Да Серия паспорта РФ.
passportNumber string Да Номер паспорта РФ.
snils string Да Номер СНИЛС (может быть пустым, если заполнен ИНН).
inn string Да Номер ИНН (может быть пустым, если заполнен СНИЛС).
phone string Нет Мобильный номер,
в формате +79001234567.
gender string Да Гендерная принадлежность (пол): Male (муж.), Female (жен.)
birthDate string Да Дата рождения в формате "2021-02-23", параметр обязателен в случае использования СНИЛС в запросе

Запрос на идентификацию со СНИЛС

POST https://secure.mandarinpay.com/api/v2/personidentification

{
	"firstName": "Иван",
	"patronymic": "Иванович",
	"lastName": "Иванов",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "19033603123",
	"inn": "",
	"phone": "+79001234567",
    "gender": "Male",
    "birthDate" : "1997-02-23"
}

Запрос на идентификацию с ИНН

POST https://secure.mandarinpay.com/api/v2/personidentification

{
	"firstName": "Иван",
	"patronymic": "Иванович",
	"lastName": "Иванов",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "",
	"inn": "501716749325",
	"phone": "+79001234567",
    "gender": "Male"
}

Запрос на идентификацию с ИНН и СНИЛС

POST https://secure.mandarinpay.com/api/v2/personidentification

{
	"firstName": "Иван",
	"patronymic": "Иванович",
	"lastName": "Иванов",
	"passportSeries": "1111",
	"passportNumber": "111111",
	"snils": "19033603123",
	"inn": "501716749325",
	"phone": "+79001234567",
    "gender": "Male",
    "birthDate" : "1997-02-23"
}

Ответ в случае успешного создания запроса (200 ОК)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Ответ в случае, если запрос не создан (400 Bad request)

{
	"error": "Invalid request" 
}

# Передача СМС-кода

Запрос на передачу СМС-кода на проверку выполняется только в сценарии с проверкой номера мобильного телефона.

Он включает в себя id сессии (в адресе), полученный в предыдущем запросе, и СМС-код (в теле запроса). В случае успешной регистрации запроса вы синхронно получите тот же самый идентификатор сессии id.

В случае, если вы передали номер мобильного телефона, но пользователь неправильно ввел СМС-код, то на этапе проверки статуса вы получите "phoneVerified": false. Тогда вы можете повторять отправку данного запроса, передав тот же id и новый СМС-код, введенный пользователем, до тех пор, пока не получите "phoneVerified": true.

ВАЖНО!

Текущая версия протокола позволяет использовать до 5 (включительно) попыток передачи СМС-кода. Если лимит превышен, то необходимо инициализировать процесс идентификации заново.

Параметр Тип Обязателен Описание
smsCode string Да СМС-код.

Запрос с передачей СМС-кода на проверку

PUT https://secure.mandarinpay.com/api/personidentification/{id}

{
	"smsCode": "123456"
}

Ответ в случае успешного создания запроса (200 ОК)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d"
}

Ответ в случае ошибки (400 Bad request)

{
	"error": "Invalid request" 
}

# Проверка статуса идентификации

Запрос по проверке статуса идентификации включает в себя id сессии (в адресе).

Ответ содержит идентификатор сессии, индикаторы окончания обеих проверок и индикаторы правильности предоставленных данных.

В редких случаях СМЭВ может отвечать с задержкой, по этой причине статус запроса может находится длительное время в ожидании. Рекомендуем в таком случае проверять статус повторно.

Запрос статуса идентификации

GET https://secure.mandarinpay.com/api/personidentification/v2/{id}

Ответ в случае успешного завершения запроса (200 ОК)

{
	"id": "794d3cc7-a2b4-4579-9173-bafc7d7dc29d",
	"phoneVerified": true,
	"phoneVerificationFinished": true,
	"personVerified": true,
	"personVerificationFinished": true,
	"personVerificationError": null,
    "Inn": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    },
    "Snils": {
        "Status": "NotProcessed",
        "Description": "Не указан СНИЛС, проверка не производилась"
    },
    "Passport": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    },
    "PassportDeferred": {
        "Status": "Valid",
        "Description": "Сведения соответствуют"
    }
}

Ответ, если запрос находится в ожидании (200 ОК)

{
	"id": "e2c3c860-1d68-427c-a16d-9666e0ffb706",
	"phoneVerified": null,
	"phoneVerificationFinished": false,
	"personVerified": null,
	"personVerificationFinished": false,
	"personVerificationError": null,
	"inn": {
		"status": "NotProcessed",
		"description": "Не указан ИНН, проверка не производилась"
	},
	"snils": {
		"status": "Processing",
		"description": "В обработке"
	},
	"passport": {
		"status": "Valid",
		"description": "Сведения соответствуют"
	},
	"passportDeferred": null
}

Ответ в случае ошибки (400 Bad request)

{
	"error": "Invalid request" 
}

Описание структуры ответа

Синхронный ответ содержит следующую информацию:

Параметр Описание
id Идентификатор сессии.
phoneVerificationFinished true - проверка СМС-кода завершена,
false - проверка СМС-кода не завершена.
phoneVerified На телефон пользователя было выслано СМС-сообщение с кодом.
null - пользователь не вводил код,
true - пользователь ввел верный код,
false - пользователь ввел неверный код.
personVerificationFinished true - проверка персональных данных завершена,
false - проверка персональных данных не завершена.
personVerified null - проверка персональных данных не завершена,
true - персональные данные верны,
false - персональные данные не верны.
personVerificationError Строка-описание ошибки из СМЭВ в случае ее наличия.
При отсутствии ошибок является пустой.
inn Объект, содержащий данные о проверке ИНН.
inn.status Статус проверки ИНН.
inn.description Расширенное описание статуса проверки ИНН.
snils Объект, содержащий данные о проверке СНИЛС.
snils.status Статус проверки СНИЛС.
snils.description Расширенное описание статуса проверки СНИЛС.
passport Объект, содержащий данные о проверке паспорта.
passport.status Статус проверки паспорта.
passport.description Расширенное описание статуса проверки паспорта.

# Получение информации о статусе мобилизованного

Создание запроса статуса мобилизованного

Параметр Тип Обязателен Описание
firstName string Да Имя
lastName string Да Фамилия
patronymic string Да Отчество
dateOfBirth string Да Дата рождения в формате ДД.ММ.ГГГГ
inn string Да* Номер ИНН (*не указывается, в случае проверки по паспорту)
passport string Да* Серия и номер паспорта без пробела (*не указывается, в случае проверки по ИНН)
dateOfDocument string Да* Дата выдачи документа в формате ДД.ММ.ГГГГ (*обязателен при указании passport)

Проверка по паспорту:

POST https://secure.psp.io/api/mobilizations

{
    "firstName": "Полиграф",
    "lastName": "Шариков",
    "patronymic": "Полиграфович",
    "dateOfBirth": "07.09.1997",
    "passport": "1111222222",
	"dateOfDocument": "07.09.1977"
}

Проверка по ИНН:

POST https://secure.psp.io/api/mobilizations

{
    "firstName": "Полиграф",
    "lastName": "Шариков",
    "patronymic": "Полиграфович",
    "dateOfBirth": "07.09.1997",
    "inn": "164441234567",
}

Ответ в случае успешного создания запроса

{
  "ExtId": "34b63379-66ce-4496-9091-0ffef"
}

Проверка состояния запроса на получение статуса мобилизованного

Параметр Тип Обязателен Описание
extId string Да Id запроса
GET https://secure.psp.io/api/mobilizations/{ExtId}

Ответ в случае успешного создания запроса

{
    "extId": "34b63379-66ce-4496-9091-0ffef",
    "orderId": "958477919",
    "actualDate": "2023-07-07T00:00:00+00:00",
    "isMobilized": false,
    "status": "Processed",
    "description": "Операция завершена"
}

← Самозанятые →