Перейти к основному содержимому

Создание процесса

Этот эндпоинт обрабатывает три продукта, которые имеют один и тот же путь, но отличаются параметрами тела запроса, возможностями и полями ответа:

  • Онбординг -- проверяет, кто является пользователем, сравнивая его лицо с базой идентификации Unico (требуются subject.duiType + subject.code).
  • Транзакционный -- проверяет, что это тот же человек из предыдущего процесса, сравнивая лицо с лицом (требуется referenceProcessId ИЛИ массив references с селфи / ID процесса).
  • Cardholder Verification -- подтверждает, что карта принадлежит заявленному держателю, без захвата селфи (требуются subject.code + card). Опционально повторно использует ранее проверенный процесс через referenceProcessId для запуска проверки повторного использования (gate); без этого поля ответ по умолчанию — unsure. См. возможность Cardholder Verification.

Активный продукт определяется APIKEY, отправленным в заголовке запроса.

Полный поток интеграции см. в Обзор API.

Эндпоинт​

ОкружениеURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Запрос​

Заголовки
ЗаголовокЗначение
AuthorizationBearer <access_token> (см. Аутентификация)
APIKEYПредоставленный API-ключ -- определяет активный продукт и включённые возможности.
Content-Typeapplication/json
Параметры тела запроса
ПолеТипОбязательныйОписание
subject.duiTypeintegerдаИдентификатор типа документа. См. значения duiType ниже.
subject.codestringдаЗначение идентификатора в соответствии с subject.duiType. Без точек и дефисов.
subject.namestringнетПолное имя.
subject.genderstringнетM или F.
subject.birthDatestring (ISO 8601)нетДата рождения (YYYY-MM-DD).
subject.emailstringнетАдрес электронной почты.
subject.phonestringнетНомер телефона в формате E.164.
subject.clientReferencestringусловноУникальный идентификатор пользователя в вашей системе. Обязателен для возможности Мультиаккаунт. Уникален в вашей базе, максимум 256 символов, без пробелов.
useCasestringнетКонтекст операции, например Onboarding.
subsidiaryIdstringнетИдентификатор филиала — требуется только при наличии нескольких филиалов.
imageBase64stringдаСелфи, захваченное вашим фронтендом, в формате base64.
Значения duiType
СтранаКодОписание
BR1Бразильский CPF
MX2Мексиканский CURP
US4SSN США
BR5Бразильский паспорт
AR6Аргентинский паспорт
AR7Аргентинский DNI
NG8Нигерийский NIN
CL9Чилийский RUN
EC10Эквадорский NI
US11Паспорт США
GT12Гватемальский CUI
UY13Уругвайский CI
BR14Бразильский CNPJ
ZZ15Адрес электронной почты
ID16Индонезийский NIK
ZZ17Номер телефона
US18Водительское удостоверение США
NG20Нигерийский номер верификации банковского счёта (BVN)
US21Паспортная карта США
US22Поликарбонатный паспорт США
US23Идентификационная карта США
TR24Турецкий идентификационный номер (TCKN)
MX25Мексиканский RFC (физическое лицо)
CO26Колумбийский NIT
PE27Перуанский RUC
CA28Канадский SIN
DK29Датский CPR
GB30Британский номер национального страхования (NINO)
PL31Польский PESEL
SE32Шведский личный номер (PNR)
CH33Швейцарский номер AHV/AVS
AT34Австрийский налоговый номер (STNR)
FI35Финский код личной идентификации (HETU)
BE36Бельгийский национальный номер (NN)
IT37Итальянский налоговый код (Codice Fiscale, CF)
SE38Шведский координационный номер (Samordningsnummer)
NO39Норвежский национальный идентификационный номер (Fødselsnummer)
PE40Перуанский DNI
DE41Немецкий налоговый идентификационный номер (IdNr)
NL42Голландский идентификационный номер гражданина (BSN)
NG43Токен BVN Нигерии (хешированный)
NG44Токен NIN Нигерии (хешированный)
PT45Португальский налоговый идентификационный номер (NIF)
FR46Французский налоговый справочный номер (SPI)
IE47Ирландский номер социального страхования (PPSN)
LU48Люксембургский национальный идентификационный номер (Matricule)
AR49Аргентинское водительское удостоверение (Licencia Nacional de Conducir)
ES50Испанский номер иностранца (NIE)
ES51Испанский национальный документ, удостоверяющий личность (DNI)
CL52Чилийский паспорт
CO53Колумбийский паспорт
PE54Перуанский паспорт
CO55Колумбийское водительское удостоверение (Licencia de Conducción)
CO56Колумбийское удостоверение личности гражданина (Cédula de Ciudadanía)
CL57Чилийское водительское удостоверение (Licencia de Conducir)
MX58Мексиканское водительское удостоверение (Licencia de Conducir)
—0Не указано
—3Внутренний идентификатор Unico
Требования к изображению
  • Минимальное разрешение: 640 x 480 (стандарт HD)
  • Максимальный размер файла: 800 КБ (рекомендуется сжатие JPEG92)
  • Допустимые форматы: PNG, JPEG, WebP
  • JWT-токены из SDK истекают через 10 минут и могут быть использованы только один раз

Пример​

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Ответы​

200 OK

Контракт единый — поле idCloud.result содержит консолидированный вердикт используемых возможностей.

Unico консолидирует результаты выполненных возможностей в единое поле idCloud.result, готовое для принятия решения о следующем шаге вашего флоу — без необходимости оркестрировать отдельные результаты.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}
ПолеТипОписание
idstring (UUID)Идентификатор процесса. Используйте с Получением процесса для повторных запросов.
statusinteger1 (обработка), 3 (завершён успешно), 5 (ошибка).
Возможные значения результата
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot enough evidence for a verdict.Route to manual review or an alternative flow.

Возвращаемые значения зависят от рецепта, настроенного в вашем APIKey. См. Потоки — значения результата, которые может вернуть каждый рецепт.

BrazilКлиенты в Бразилии могут получать ответ по возможностям

Общая структура ответа остаётся прежней — единый результат используется по умолчанию.

Интеграции в Бразилии могут получать открытые результаты по каждой возможности отдельно. Каждая возможность, включённая в APIKey, добавляет свой блок в ответ — поля для отключённых возможностей отсутствуют.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}
Поля ответа зависят от вашего APIKey

Приведённый выше пример содержит все возможные поля возможностей. В реальном ответе будут только поля для возможностей, включённых в конфигурации вашего APIKey — поля для отключённых возможностей полностью отсутствуют. Свяжитесь с вашим менеджером проекта Unico для включения или изменения возможностей.

ПолеТипОписание
unicoId.resultstringyes, no, inconclusive -- см. Проверка личности.
riskLevel.resultstringapproved, reproved, risk-critical, risk-high, inconclusive -- см. возможные значения ниже или Классификация рисков мошенничества.
idFace.resultstringFOUND — см. Идентификатор лица.
idFace.personIdstringСтабильный непрозрачный идентификатор лица, возвращается вместе с idFace.result = FOUND. Если лицо не удаётся идентифицировать на изображении, запрос завершается ошибкой 20532 вместо возврата блока idFace.
identityFraudsters.resultstringУстарело. Используйте вместо него riskLevel. Клиенты с текущими интеграциями могут продолжать использовать это поле, согласовывая миграцию с командой проекта.
government.serprointegerОценка сходства Serpro (0--100, -1, -2). Доступно только в Бразилии. См. Результат проверки сходства Serpro.
livenessinteger1 (пройдено), 2 (не пройдено) -- см. Проверка живости.
riskLevel.result — возможные значения
ЗначениеОписание
approvedЭто лицо владельца удостоверения личности, и никаких признаков мошенничества не обнаружено.
reprovedРекомендуется отказ, поскольку обнаружено несколько индикаторов мошенничества.
risk-criticalРекомендуется отказ, однако окончательное решение остаётся за вами. Критический риск означает, что обнаружено не менее 2 веских признаков мошенничества.
risk-highОтказ также рекомендуется, однако решение остаётся за вами. Высокий риск означает, что обнаружен как минимум один весомый признак мошенничества.
inconclusiveВеских признаков мошенничества не обнаружено. Поэтому невозможно сделать однозначный вывод о наличии существенного риска.
информация

Когда unicoId.result = inconclusive и оркестрация Риск-скора активна, процесс может вернуть status: 1 (обработка). Опрашивайте Получение процесса или используйте вебхуки для получения финального результата.

Коды ошибок​

КодСообщениеОписание
40221This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.Поток повторного использования (referenceProcessId/bioTokenId, без изображения) был отклонён, поскольку повторное использование процесса не включено для этого API-ключа.
20900O base64 informado não é válido.Параметр base64 недействителен. Возможные причины: это не изображение или попытка инъекции.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.Разрешение загруженного изображения слишком низкое.
20532No face detected in image.Не удалось обнаружить лицо на отправленном изображении.
20513The referenced process was not found.referenceProcessId указывает на процесс, который не существует или более недоступен.
20512The referenced process is not available for reuse.Ссылочный процесс существует, но недоступен для повторного использования.
20509The subject.name field is invalid.subject.name содержит недопустимые символы.
20508The subject.gender field is invalid.subject.gender должен быть M или F.
20507O parâmetro subject.code é inválido.Нестандартный или несуществующий CPF.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Размер изображения превышает 800 КБ; сожмите до JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Формат base64 недействителен или не поддерживается.
20065The referenceProcessId field is invalid.referenceProcessId не является действительным UUID.
20062The useCase field is invalid.Нераспознанное значение в поле useCase.
20024The referenceProcessId field is missing.Параметр referenceProcessId не указан, и references не отправлен в качестве альтернативы. Не применяется к Cardholder Verification — его referenceProcessId никогда не проверяется как обязательный; при невыполненном условии повторного использования возвращается unsure.
20533The card field is missing.Cardholder Verification: объект card не был предоставлен.
20534The card.bin field is missing.Cardholder Verification: card.bin не был предоставлен.
20535The card.last4 field is missing.Cardholder Verification: card.last4 не был предоставлен.
20536The card data is invalid.Cardholder Verification: данные карты были отклонены как недействительные.
20021The subject.phone field is invalid.Формат subject.phone недействителен (IDD + код региона + номер, 13 символов).
20019The subject.birthDate field is invalid.subject.birthDate не соответствует формату ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.Отсутствует параметр изображения селфи.
20008The subject.email field is invalid.Недействительный формат email в subject.email.
20006O parâmetro subject.name não foi informado.Отсутствует параметр subject.name.
20005O parâmetro subject.code não foi informado.Отсутствует параметр subject.code.
20004O parâmetro subject não foi informado.Отсутствует параметр subject.
20003The request body is missing or invalid.Пустое или некорректное тело запроса.
20002O parâmetro APIKey não foi informado.Параметр APIKEY отсутствует в заголовке запроса.
20001O parâmetro authtoken não foi informado.Параметр токена интеграции отсутствует в заголовке запроса.
10508The JWT with the captured face has already been used.JWT может быть использован только один раз.
10507The JWT with the captured face is expired.JWT истёк; должен быть отправлен в течение 10 минут.
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 не является действительным JWT, сгенерированным SDK.

Что дальше​

  • Для запроса результата процесса онбординга см. Получение процесса.
  • Чтобы увидеть все комбинации рецептов и их возможные значения результата, см. Потоки.
  • Для операций с документами и проверкой возраста см. соответствующие страницы в этом разделе.
Последнее обновление