--- title: Создание процесса description: POST /v1/processes — общие поля, ограничения валидации, поля потоков и ответ 201 с Human Token и аналитикой. canonical: https://developer.unico.io/ru/human-plugin/api-reference/create-process locale: ru generated_by: markdown-export --- # Создание процесса Запустите процесс и получите Human Token и аналитику по человеку. `POST /v1/processes` Запускает процесс с одним из [потоков](#flows) и отвечает полями `id`, `state` и результатом в `data`: Human Token и [аналитикой](/ru/human-plugin/get-started/intelligence) по человеку, `data.ndocs`. ## Перед вызовом - Human Plugin запущен, и `GET /health/ready` отвечает `200`. - Ваш ключ доступа включён для [потока](#flows), который вы используете. - Если вы передаёте документ, его `type` есть в [каталоге атрибутов](/ru/human-plugin/additional-resources/attribute-catalog). ## Потоки Поле `flow` определяет, что делает процесс. Human Plugin выполняет эти потоки в двух моделях интеграции: - **API Only**: ваш бэкенд отправляет селфи в `imageBase64`, и создание сразу отвечает результатом. - **Human Token Journey**: человек делает селфи в процессе захвата и возвращается на ваш `callbackUri`. Создание отвечает `token` и `link`, а результат вы читаете через [Получение процесса](/ru/human-plugin/api-reference/get-process). | Flow | Description | Possible result | Integration components required | | --- | --- | --- | --- | | `api+humantoken` | Принимает селфи через ваш бэкенд и генерирует Human Token — уникальный идентификатор лица. Ответ окончательный: без захвата и без второго вызова. | `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API | | `humantoken` | Делает селфи в процессе захвата с проверкой живости и генерирует Human Token. Создание возвращает `token` и `link`; результат читается после завершения захвата. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web | | `humantoken+revalidation` | Делает селфи и сравнивает лицо с ожидаемым Human Token. Возвращает, тот же это человек или нет, например перед чувствительным действием. | `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED` | API, Web | `clientId`, `correlationId` и `credential` одинаковы во всех потоках. ## Запрос ```json { "flow": "api+humantoken", "clientId": "client-a", "correlationId": "onboarding-001", "credential": { "type": "DUI_TYPE_NG_BVN", "value": "" }, "imageBase64": "" } ``` ### Общие поля | Поле | Обязательное | Лимит (байты) | Примечания | | --- | --- | --- | --- | | `flow` | Да | 64 | Один из [потоков](#flows) | | `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` используйте фронтальное, хорошо освещённое селфи с одним лицом. Значение, которое не является изображением, отклоняется, а процесс сохраняется как завершившийся ошибкой: см. [Отказы потоков](#flow-refusals). В потоке `humantoken+revalidation` результат содержит `humanTokenMatch` вместо `humanToken`: - `"true"`: это тот же человек. Процесс засчитывается для этого человека, а `ndocs` описывает его. - Любое другое значение или неживой захват: совпадение не подтверждено. Процесс не засчитывается никому, и `ndocs` отсутствует. В обоих случаях возвращается `PROCESS_STATE_FINISHED`: читайте `humanTokenMatch`. См. [Получение процесса](/ru/human-plugin/api-reference/get-process#finished-and-failed-processes). Ряд имён зарезервирован 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/`. ```json { "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` — локальный статус. См. [жизненный цикл](/ru/human-plugin/api-reference/process-lifecycle). - `humantoken` и `humantoken+revalidation` отвечают `PROCESS_STATE_CREATED` с `token` и `link`. Они возвращаются **один раз** и никогда не сохраняются: сохраните их у себя. См. [Human Token Journey](/ru/human-plugin/integrations/human-token-journey) и руководство по захвату для вашей платформы. - `data.ndocs` — аналитика по человеку. Она может отсутствовать: см. [Аналитика](/ru/human-plugin/get-started/intelligence). ### Результат в `data` У завершённого процесса в `data` есть следующие поля. Потоки Journey возвращают их, когда вы [читаете процесс](/ru/human-plugin/api-reference/get-process) после захвата. | Поле | Когда | Значение | | --- | --- | --- | | `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` | Когда по человеку есть аналитика | [Аналитика](/ru/human-plugin/get-started/intelligence) по человеку | Результат Journey выглядит так: ```json { "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_`, `INVALID_` | Обязательное поле отсутствует или некорректно, например `MISSING_CLIENT_ID` | | 401 | Пусто (`""`) | Unico отклонил ваш ключ доступа: он отсутствует, неверен или больше недействителен. Процесс сохраняется как завершившийся ошибкой. Проверьте `HUMAN_API_ACCESS_KEY` | | 409 | `CORRELATION_ID_ALREADY_USED` | У другого процесса уже есть такой `correlationId`. Ничего не сохраняется и не отправляется | | 422 | `ATTRIBUTE_TYPE_NOT_SUPPORTED` | `credential.type` нет в каталоге. Ничего не сохраняется и не отправляется | | 4xx | `message` потока | Поток отклонил запрос, например из-за недопустимого изображения. См. [Отказы потоков](#flow-refusals) | | 502 | `UPSTREAM_UNAVAILABLE` | Процесс не удалось подтвердить вовремя | | 503 | `DATABASE_UNAVAILABLE` | Сбой базы данных. Ничего не было обработано | | 500 | `INTERNAL` | Непредвиденная ошибка | ### Отказы потоков Когда поток отклоняет запрос, создание отвечает `4xx` с причиной в `message` в обычном [формате ошибки](/ru/human-plugin/api-reference/errors-and-retries). Наиболее частые случаи: | `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`. Прочитайте [Ошибки и повторные попытки](/ru/human-plugin/api-reference/errors-and-retries), прежде чем добавлять логику повторов: для новой попытки нужен новый `correlationId`. ## Далее [Получение процесса](/ru/human-plugin/api-reference/get-process)