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

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

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

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

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

Эндпоинт

Окружение	URL
Production	`POST https://api.id.unico.app/processes/v1`
Sandbox	`POST https://api.id.uat.unico.app/processes/v1`

Запрос

Заголовки

Заголовок	Значение
`Authorization`	`Bearer <access_token>` (см. Аутентификация)
`APIKEY`	Предоставленный API-ключ -- определяет активный вариант использования и включённые возможности.
`Content-Type`	`application/json`

Параметры тела запроса

Онбординг
Транзакционный

Поле	Тип	Обязательный	Описание
`subject.duiType`	integer	да	Идентификатор типа документа. См. значения `duiType` ниже.
`subject.code`	string	да	Значение идентификатора в соответствии с `subject.duiType`. Без точек и дефисов.
`subject.name`	string	нет	Полное имя.
`subject.gender`	string	нет	`M` или `F`.
`subject.birthDate`	string (ISO 8601)	нет	Дата рождения (`YYYY-MM-DD`).
`subject.email`	string	нет	Адрес электронной почты.
`subject.phone`	string	нет	Номер телефона в формате E.164.
`useCase`	string	нет	Контекст операции, например `Onboarding`.
`subsidiaryId`	string	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.
`imageBase64`	string	да	Селфи, захваченное вашим фронтендом, в формате base64.

Поле	Тип	Обязательный	Описание
`references`	array	условно	Входные данные для потоков валидации 1:1. Каждый элемент содержит `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` или `REFERENCE_TYPE_PROCESS_ID`) и `referenceContent` (base64-изображение или UUID процесса).
`referenceProcessId`	string	условно	Устарело. Используйте `references` вместо этого. ID ссылочного процесса онбординга для сравнения. Если ссылка представляет собой процесс by-Unico, используйте `authenticationInfo.authenticationId`.
`imageBase64`	string	да	Селфи, захваченное вашим фронтендом, в формате base64.
`subject`	object	нет	Контейнер информации о пользователе.
`subject.duiType`	string	нет	Тип идентификатора. Возможные значения: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`subject.code`	string	нет	Значение идентификатора в соответствии с `subject.duiType`. Без точек и дефисов.
`subject.name`	string	нет	Полное имя пользователя.
`subject.gender`	string	нет	`M` или `F`.
`subject.birthDate`	string (ISO 8601)	нет	Дата рождения (`YYYY-MM-DD`).
`subject.email`	string	нет	Адрес электронной почты.
`subject.phone`	string	нет	Номер телефона в формате E.164.
`useCase`	string	нет	Контекст операции, например `Transactional`.
`subsidiaryId`	string	нет	ID филиала -- обязателен только при наличии нескольких филиалов.

информация

Для этого варианта использования невозможна оркестрация с Риск-скором. Результат всегда возвращается синхронно в ответе POST.

Значения duiType

Страна	Код	Описание
BR	1	Бразильский CPF
BR	5	Бразильский паспорт
MX	2	Мексиканский CURP
AR	6	Аргентинский паспорт
AR	7	Аргентинский DNI
US	4	SSN США
US	11	Паспорт США
US	18	Водительское удостоверение США
ID	16	Индонезийский NIK
NG	8	Нигерийский NIN
CL	9	Чилийский RUN
EC	10	Эквадорский NI
GT	12	Гватемальский CUI
UY	13	Уругвайский CI
ZZ	15	Адрес электронной почты
ZZ	17	Номер телефона
MX	25	Мексиканский RFC (физическое лицо)
CO	26	Колумбийский NIT
PE	27	Перуанский RUC
CA	28	Канадский SIN
DK	29	Датский CPR
GB	30	Британский номер национального страхования (NINO)
PL	31	Польский PESEL
SE	32	Шведский личный номер (PNR)
AT	34	Австрийский налоговый номер (STNR)
FI	35	Финский код личной идентификации (HETU)
—	0	Не указано
—	3	Внутренний идентификатор Unico

Требования к изображению

Минимальное разрешение: 640 x 480 (стандарт HD)
Максимальный размер файла: 800 КБ (рекомендуется сжатие JPEG92)
Допустимые форматы: PNG, JPEG, WebP
JWT-токены из SDK истекают через 10 минут и могут быть использованы только один раз

Пример

Онбординг -- cURL
Онбординг -- Node.js
Транзакционный -- cURL
Транзакционный -- Node.js

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..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Ответы

Онбординг
Транзакционный

200 OK

{
  "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 для включения или изменения возможностей.

Поле	Тип	Описание
`id`	string (UUID)	Идентификатор процесса. Используйте с Получением процесса для повторных запросов.
`status`	integer	`1` (обработка), `3` (завершён успешно), `5` (ошибка).
`unicoId.result`	string	`yes`, `no`, `inconclusive` -- см. Проверка личности.
`riskLevel.result`	string	`approved`, `reproved`, `risk-critical`, `risk-high`, `inconclusive` -- см. возможные значения ниже или Классификация рисков мошенничества.
`idFace.result`	string	`FOUND`, `NOT_FOUND` — см. Идентификатор лица.
`idFace.personId`	string	Стабильный непрозрачный идентификатор лица. Присутствует только при `idFace.result = FOUND`.
`identityFraudsters.result`	string	Устарело. Используйте вместо него `riskLevel`. Клиенты с текущими интеграциями могут продолжать использовать это поле, согласовывая миграцию с командой проекта.
`government.serpro`	integer	Оценка сходства Serpro (0--100, -1, -2). Доступно только в Бразилии. См. Результат проверки сходства Serpro.
`liveness`	integer	`1` (пройдено), `2` (не пройдено) -- см. Проверка живости.

riskLevel.result — возможные значения

Значение	Описание
`approved`	Это лицо владельца удостоверения личности, и никаких признаков мошенничества не обнаружено.
`reproved`	Рекомендуется отказ, поскольку обнаружено несколько индикаторов мошенничества.
`risk-critical`	Рекомендуется отказ, однако окончательное решение остаётся за вами. Критический риск означает, что обнаружено не менее 2 веских признаков мошенничества.
`risk-high`	Отказ также рекомендуется, однако решение остаётся за вами. Высокий риск означает, что обнаружен как минимум один весомый признак мошенничества.
`inconclusive`	Веских признаков мошенничества не обнаружено. Поэтому невозможно сделать однозначный вывод о наличии существенного риска.

информация

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

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

Поле	Тип	Описание
`id`	string (UUID)	Идентификатор процесса.
`status`	integer	`3` (завершён успешно), `5` (ошибка). Все возможные значения см. в Получении процесса.
`biometryToken.result`	boolean	`true`, если переданное лицо совпадает с ссылочным процессом; `false` в противном случае.
`liveness`	integer	`1` (пройдено), `2` (не пройдено) -- см. Проверка живости.

400 Bad Request

Тело запроса содержит ошибки, изображение недействительно или обязательные поля отсутствуют. См. Коды ошибок ниже.

403 Forbidden

Bearer-токен или APIKEY отсутствует, истёк или недействителен. См. Аутентификация.

409 Conflict

Указанный processId уже существует для данного тенанта. См. Коды ошибок ниже.

429 Too Many Requests

Достигнут лимит запросов. Когда ваша система получает ошибку HTTP 429, необходимо реализовать механизмы для предотвращения каскадных сбоев и ухудшения ограничения.

Лучшие практики:

Период ожидания (backoff): Немедленно остановите или ограничьте последующие запросы из вашей системы. Не повторяйте неудачные запросы непрерывно в плотном цикле.
Очередь и ограничение: Буферизуйте или ставьте в очередь исходящие запросы на вашей стороне для управления потоком трафика перед повторной отправкой.
Экспоненциальный backoff с jitter: При повторных попытках увеличивайте время ожидания экспоненциально между попытками (например, 1 с, 2 с, 4 с, 8 с) и добавляйте небольшую случайную задержку ("jitter"), чтобы предотвратить эффект стада, когда все поставленные в очередь запросы повторяются в один и тот же момент.

предупреждение

Непрерывные запросы к эндпоинту с ограничением без отступления могут продлить период ограничения и серьёзно повлиять на операционную пропускную способность вашей системы. Правильное ограничение запросов на вашей стороне обеспечивает более плавную и устойчивую интеграцию.

Для получения информации о лимитах по умолчанию, увеличении запросов и дополнительных деталях см. Лимиты запросов.

Коды ошибок

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

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

Код	Сообщение	Описание
`30017`	User does not have permission to perform this action.	Некорректный JWT или пользователь без разрешения на выполнение этой операции.
`10502`	O token informado está expirado.	Access-token истёк.
`10501`	O token informado é inválido.	Токен аутентификации недействителен.
`10201`	O AppKey informado é inválido.	APIKEY недействителен или не существует.

Код	Сообщение	Описание
`20073`	The processID already exists.	Указанный `processId` уже существует для данного тенанта.

Код	Сообщение	Описание
`99999`	Internal failure! Try again later	Внутренняя ошибка.

Что дальше

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

Эндпоинт​

Запрос​

Пример​

Ответы​

Коды ошибок​

Что дальше​