Перейти к основному содержимому
Создать процессPOST

Создайте процесс Human Token со своего бэкенда и получите humanToken в data.humanToken.

Markdown

Human Token работает на эндпоинте Human API POST /client/v1/process. С потоками API Only (api+humantoken, api+liveness+humantoken и api+liveness+humantoken+revalidation) процесс создаётся и завершается за один вызов: ответ уже содержит результат в data.humanToken. С потоками Human Token Journey (humantoken и humantoken+revalidation) ответ содержит id процесса, token и link сценария, а результат становится доступен после того, как пользователь пройдёт сценарий. Потоки +revalidation требуют массив references с ранее полученным humanToken для повторной валидации.

Потоки​

Human Token работает в двух моделях интеграции:

  • API Only — ваш бэкенд отправляет селфи в imageBase64.
  • Human Token Journey — пользователь проходит сценарий Unico в Web и возвращается на ваш callbackUri.
FlowCapabilitiesPossible resultIntegration components
required		Example
api+humantokenHuman TokenPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPI
api+liveness+humantokenLivenessHuman TokenPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPI
api+liveness+humantoken+revalidationLivenessHuman TokenRevalidationPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDAPI
humantokenLivenessHuman TokenPROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELEDAPIWeb
humantoken+revalidationLivenessHuman TokenRevalidationPROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELEDAPIWeb

Эндпоинт​

СредаURL
ProductionPOST https://humantoken.unico.app/client/v1/process

Запрос​

Заголовки
ЗаголовокЗначение
x-unico-accesskey<your_access_key> (см. Аутентификация)
Content-Typeapplication/json
Параметры тела запроса
ПолеТипОбязательноОписание
flowstringдаПоток Human Token: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) или humantoken, humantoken+revalidation (Human Token Journey). См. Потоки.
imageBase64stringAPI OnlyСелфи, захваченное вашим фронтендом и отправленное напрямую, в base64. PNG, JPEG или WebP, до 800 КБ. Следуйте стандарту захвата.
callbackUristringHuman Token JourneyURL, на который перенаправляется пользователь после завершения сценария.
companyBranchIdstringнетИдентификатор ветки. При указании процесс использует конфигурацию указанной ветки.
referencesarrayПотоки повторной валидацииМассив объектов-ссылок. Обязателен для потоков +revalidation. Каждый объект содержит referenceType (REFERENCE_TYPE_HUMAN_TOKEN) и referenceContent (ранее полученное значение humanToken).

Ответы​

200 OK
ПолеТипОписание
idstring (UUID)Идентификатор процесса. Используйте его, чтобы повторно получить процесс через Получение процесса.
statestringСостояние процесса — см. Интерпретация результата. Только в потоках API Only.
tokenstringТокен созданного процесса, его можно использовать для открытия интерфейса Journey SDK. Только в потоках Human Token Journey (humantoken, humantoken+revalidation).
linkstringURL сценария Human Token Journey: направьте пользователя по нему. Только в потоках Human Token Journey (humantoken, humantoken+revalidation).
data.​humanToken.​valuestringСтабильный непрозрачный идентификатор лица (до 100 символов). Один и тот же человек всегда соответствует одному и тому же значению. Только в потоках API Only (без повторной валидации).
data.​humanTokenMatchstring"true", если селфи совпадает с указанным humanToken, "false" в противном случае. Только в потоке +revalidation API Only.
Интерпретация результата
stateЗначениеЧто делать
PROCESS_STATE_FINISHEDdata.humanToken.value заполнено: реальный человек с Human Token.Найдите value в своих записях: если значение есть, это вернувшийся пользователь или возможный дубликат; если нет — это новый человек.
PROCESS_STATE_FINISHEDНет data.humanToken или value пустое: результат неопределённый.Считайте результат неокончательным. Никогда не сохраняйте и не сопоставляйте пустое value; повторите процесс или отклоните его в соответствии с вашими бизнес-правилами.
PROCESS_STATE_FAILEDПроцесс идентификации завершился ошибкой.Повторите процесс или отклоните его согласно вашим бизнес-правилам.
PROCESS_STATE_CREATEDПроцесс создан.Подождите. Получите результат позже через Получение процесса.
PROCESS_STATE_CANCELEDПроцесс был отменён.Создайте новый процесс, если пользователя всё ещё нужно проверить.
предупреждение

Всегда проверяйте, что data.humanToken.value не пусто, прежде чем использовать его.

Коды ошибок​

примечание

HTTP-статус, который возвращается, когда ключ доступа в заголовке x-unico-accesskey отсутствует или недействителен, ещё уточняется. См. Аутентификация.

КодСообщениеОписание
3invalid flowКогда указанный поток не существует.
3INVALID_IMAGEКогда изображение не является корректным base64 или похоже на попытку инъекции.
3IMAGE_TOO_LARGEКогда изображение превышает максимальный размер 800 КБ.
3UNSUPPORTED_IMAGE_FORMATКогда формат изображения не PNG, JPEG или WebP.
3MISSING_IMAGEКогда изображение обязательно для этого потока, но не было отправлено.
3INVALID_REQUESTКогда тело запроса равно null или не может быть интерпретировано.
9monthly process limit of <monthly_limit> reached for this tenantКогда достигнут ежемесячный лимит использования.
9PROCESS_FAILEDКогда процесс завершился терминальной ошибкой во время создания.

Полный список кодов этого эндпоинта см. в справочнике Human API Создать процесс.

Что дальше​

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