Создать процесс

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

Onboarding — устанавливает личность пользователя, сравнивая его лицо с базой данных Unico (требуется subject.code).
Transactional — проверяет, что это тот же человек, что и в предыдущем процессе, сравнивая лицо с лицом (требуется referenceProcessId ИЛИ массив references с selfie / process id).

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

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

Endpoint

Среда	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`

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

Onboarding
Transactional

Поле	Тип	Обязательное	Описание
`subject.code`	string	да	CPF (BR) или CURP (MX).
`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`.
`imageBase64`	string	да	Селфи, захваченное вашим фронтендом, в формате base64.

Поле	Тип	Обязательное	Описание
`references`	array	условно	Входные данные референса для сценариев валидации 1:1. Каждый элемент содержит `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` или `REFERENCE_TYPE_PROCESS_ID`) и `referenceContent` (изображение в base64 или UUID процесса).
`referenceProcessId`	string	условно	Устарело. Используйте вместо него `references`. Идентификатор референсного процесса Onboarding для сравнения. Если референс является процессом by-Unico, используйте `authenticationInfo.authenticationId`.
`imageBase64`	string	да	Селфи, захваченное вашим фронтендом, в формате base64.
`subject`	object	нет	Контейнер информации о пользователе.
`subject.code`	string	нет	CPF (BR) или CURP (MX).
`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	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.

информация

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

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

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

Пример

Onboarding — cURL
Onboarding — Node.js
Transactional — cURL
Transactional — 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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Ответы

Onboarding
Transactional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Поле	Тип	Описание
`id`	string (UUID)	Идентификатор процесса. Используйте с Get Process для повторных запросов.
`status`	integer	`1` (обработка), `3` (завершён успешно), `5` (ошибка). Все возможные значения см. в разделе Get Process.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — см. Проверка личности.
`identityFraudsters.result`	string	`yes`, `inconclusive` — см. Классификация риска мошенничества.
`government.serpro`	integer	Оценка сходства Serpro (0–100, -1, -2). См. Результат проверки сходства Serpro.
`liveness`	integer	`1` (пройдено), `2` (не пройдено) — см. Проверка живости.

информация

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

200 OK

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

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

400 Bad Request

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

403 Forbidden

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

409 Conflict

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

429 Too Many Requests

Достигнут лимит запросов. Повторите попытку через интервал, указанный в заголовке ответа Retry-After. См. Ограничения частоты запросов.

Коды ошибок

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` недействителен (международный код + код региона + номер, 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.	Срок действия токена доступа истёк.
`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	Внутренняя ошибка.

Дальнейшие шаги

Для запроса результата процесса Onboarding см. Get Process.
Для операций верификации документов и возраста см. соответствующие страницы этого раздела.

Endpoint​

Запрос​

Пример​

Ответы​

Коды ошибок​

Дальнейшие шаги​