Создание процесса | Unico Developer Portal

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

Запустите процесс и получите Human Token и аналитику по человеку.

POST /v1/processes

Запускает процесс с одним из потоков и отвечает полями id, state и результатом в data: Human Token и аналитикой по человеку, data.ndocs.

Перед вызовом

Human Plugin запущен, и GET /health/ready отвечает 200.
Ваш ключ доступа включён для потока, который вы используете.
Если вы передаёте документ, его type есть в каталоге атрибутов.

Потоки

Поле flow определяет, что делает процесс. Human Plugin выполняет эти потоки в двух моделях интеграции:

API Only: ваш бэкенд отправляет селфи в imageBase64, и создание сразу отвечает результатом.
Human Token Journey: человек делает селфи в процессе захвата и возвращается на ваш callbackUri. Создание отвечает token и link, а результат вы читаете через Получение процесса.

Flow	Description	Possible result	Integration components required
`api+humantoken`	Принимает селфи через ваш бэкенд и генерирует Human Token — уникальный идентификатор лица. Ответ окончательный: без захвата и без второго вызова.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
`humantoken`	Делает селфи в процессе захвата с проверкой живости и генерирует Human Token. Создание возвращает `token` и `link`; результат читается после завершения захвата.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
`humantoken+revalidation`	Делает селфи и сравнивает лицо с ожидаемым Human Token. Возвращает, тот же это человек или нет, например перед чувствительным действием.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId и credential одинаковы во всех потоках.

Запрос

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

Общие поля

Поле	Обязательное	Лимит (байты)	Примечания
`flow`	Да	64	Один из потоков
`clientId`	Да	128	Ваш идентификатор клиента. Аналитика считает различные значения
`correlationId`	Да	128	Ваша ссылка на этот процесс. Уникальный: значение, которое уже есть у другого процесса в любом состоянии, отклоняется ответом `409`
`credential`	Да, но может быть пустым		Ключ должен присутствовать. См. ниже
`credential.type`	При наличии документа		Код из каталога атрибутов, точный и чувствительный к регистру
`credential.value`	При наличии документа	64	Номер документа

flow, clientId и correlationId должны быть строками без управляющих символов и без пробелов в начале и в конце. Недопустимые значения отклоняются и никогда не исправляются автоматически.

Поле `credential`

С документом: объект ровно с полями type и value, оба — строки, передаются вместе.
Без документа: null или {}. Процесс всё равно учитывается в аналитике как транзакция и как клиент.
Пропущено или объект с пустыми строками: отклоняется ответом 400 MISSING_CREDENTIAL_TYPE. Так опечатка в ключе обнаруживается до начала обработки.
Любой другой ключ внутри credential отклоняется.

Поля потоков

Что каждый поток добавляет к общим полям:

Поле	Поток	Обязательное	Значение
`imageBase64`	`api+humantoken`	Да	Селфи в base64. PNG, JPEG или WebP, до 800 КБ
`callbackUri`	`humantoken`, `humantoken+revalidation`	Да	Куда человек возвращается после завершения захвата: ваша страница или URL-схема вашего приложения
`references`	`humantoken+revalidation`	Да	Один элемент с ожидаемым Human Token, как в примере выше

Human Plugin не сохраняет эти поля, а опечатка в необязательном поле может быть проигнорирована без ошибки.

Для api+humantoken используйте фронтальное, хорошо освещённое селфи с одним лицом. Значение, которое не является изображением, отклоняется, а процесс сохраняется как завершившийся ошибкой: см. Отказы потоков.

В потоке humantoken+revalidation результат содержит humanTokenMatch вместо humanToken:

"true": это тот же человек. Процесс засчитывается для этого человека, а ndocs описывает его.
Любое другое значение или неживой захват: совпадение не подтверждено. Процесс не засчитывается никому, и ndocs отсутствует.

В обоих случаях возвращается PROCESS_STATE_FINISHED: читайте humanTokenMatch. См. Получение процесса.

Ряд имён зарезервирован Human Plugin и отклоняется ответом 400 INVALID_REQUEST, например clientReference. То же относится к другим написаниям собственных полей Human Plugin, таким как client_id, correlation_id или Flow: читаются только flow, clientId, correlationId и credential, записанные именно так.

Правила тела запроса

Один JSON-объект, не более 2 MiB (примерно столько нужно для селфи в base64). Более крупное тело отклоняется ответом 400 REQUEST_TOO_LARGE.
После JSON-объекта ничего не должно следовать.

Ответ

201 Created с заголовком Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

id — это UUID Human Plugin. Каждый принятый запрос создаёт новый.
state — локальный статус. См. жизненный цикл.
humantoken и humantoken+revalidation отвечают PROCESS_STATE_CREATED с token и link. Они возвращаются один раз и никогда не сохраняются: сохраните их у себя. См. Human Token Journey и руководство по захвату для вашей платформы.
data.ndocs — аналитика по человеку. Она может отсутствовать: см. Аналитика.

Результат в `data`

У завершённого процесса в data есть следующие поля. Потоки Journey возвращают их, когда вы читаете процесс после захвата.

Поле	Когда	Значение
`humanToken`	`api+humantoken`, `humantoken`	Кто этот человек: `value` — Human Token, а `status` равен `validated`, если он был сгенерирован
`humanTokenMatch`	`humantoken+revalidation`	`"true"`, если это тот же человек, что и в Human Token из `references`
`liveness`	Потоки с проверкой живости, например потоки Journey	`value` равно `live`, если захват выполнил живой человек, или `not_live`, если нет; `status` равен `validated`, если проверка выполнялась
`ndocs`	Когда по человеку есть аналитика	Аналитика по человеку

Результат Journey выглядит так:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

Проверяйте liveness, прежде чем доверять результату: при not_live считайте захват неудачным и попросите человека повторить. Процесс с not_live не учитывается в аналитике никого из людей.

Ошибки

Статус	`message`	Значение
400	`INVALID_REQUEST`, `REQUEST_TOO_LARGE`	Не один JSON-объект, зарезервированное поле, неверный тип или тело больше 2 MiB
400	`MISSING_<FIELD>`, `INVALID_<FIELD>`	Обязательное поле отсутствует или некорректно, например `MISSING_CLIENT_ID`
401	Пусто (`""`)	Unico отклонил ваш ключ доступа: он отсутствует, неверен или больше недействителен. Процесс сохраняется как завершившийся ошибкой. Проверьте `HUMAN_API_ACCESS_KEY`
409	`CORRELATION_ID_ALREADY_USED`	У другого процесса уже есть такой `correlationId`. Ничего не сохраняется и не отправляется
422	`ATTRIBUTE_TYPE_NOT_SUPPORTED`	`credential.type` нет в каталоге. Ничего не сохраняется и не отправляется
4xx	`message` потока	Поток отклонил запрос, например из-за недопустимого изображения. См. Отказы потоков
502	`UPSTREAM_UNAVAILABLE`	Процесс не удалось подтвердить вовремя
503	`DATABASE_UNAVAILABLE`	Сбой базы данных. Ничего не было обработано
500	`INTERNAL`	Непредвиденная ошибка

Отказы потоков

Когда поток отклоняет запрос, создание отвечает 4xx с причиной в message в обычном формате ошибки. Наиболее частые случаи:

`message`	Причина
`invalid flow`	`flow` не является потоком, включённым для вашей учётной записи
`INVALID_IMAGE` (`400`)	`api+humantoken` без `imageBase64`
`INVALID_REQUEST` (`400`)	`imageBase64` не является изображением в base64
`IMAGE_TOO_LARGE`	Изображение больше 800 КБ
`UNSUPPORTED_IMAGE_FORMAT`	Изображение не в формате PNG, JPEG или WebP
`PERMISSION_DENIED` (`403`)	Ваш ключ доступа не включён для этого потока

Отклонённый процесс сохраняется как завершившийся ошибкой. Исправьте запрос и создайте новый процесс с новым correlationId.

Прочитайте Ошибки и повторные попытки, прежде чем добавлять логику повторов: для новой попытки нужен новый correlationId.

Получение процесса

Перед вызовом​

Потоки​

Запрос​

Общие поля​

Поле credential​

Поля потоков​

Правила тела запроса​

Ответ​

Результат в data​

Ошибки​

Отказы потоков​

Далее​