Crie um processo de Human Token a partir do seu back-end e obtenha o humanToken em data.humanToken.
O Human Token é executado no endpoint POST /client/v1/process da Human API. Com os fluxos API Only (api+humantoken, api+liveness+humantoken e api+liveness+humantoken+revalidation), o processo é criado e finalizado em uma única chamada: a resposta já traz o resultado em data.humanToken. Com os fluxos Human Token Journey (humantoken e humantoken+revalidation), a resposta traz o id do processo, um token e o link da jornada, e o resultado fica disponível depois que o usuário conclui a jornada. Os fluxos +revalidation exigem um array references com um humanToken obtido anteriormente para revalidação.
Fluxos
O Human Token é executado em dois modelos de integração:
- API Only — seu back-end envia a selfie em
imageBase64. - Human Token Journey — o usuário percorre a jornada da Unico na Web e retorna ao seu
callbackUri.
| Flow | Capabilities | Possible result | Integration components required | Example |
|---|---|---|---|---|
api+humantoken | Human Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken | LivenessHuman Token | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
api+liveness+humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED | API | |
humantoken | LivenessHuman Token | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb | |
humantoken+revalidation | LivenessHuman TokenRevalidation | PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILEDPROCESS_STATE_CANCELED | APIWeb |
Endpoint
| Ambiente | URL |
|---|---|
| Produção | POST https://humantoken.unico.app/client/v1/process |
Requisição
| Header | Valor |
|---|---|
x-unico-accesskey | <your_access_key> (veja Autenticação) |
Content-Type | application/json |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
flow | string | sim | Fluxo de Human Token: api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation (API Only) ou humantoken, humantoken+revalidation (Human Token Journey). Veja Fluxos. |
imageBase64 | string | API Only | A selfie, capturada pelo seu front-end e enviada diretamente, em base64. PNG, JPEG ou WebP, até 800 KB. Siga o Padrão de Captura. |
callbackUri | string | Human Token Journey | URL para a qual o usuário é redirecionado após o fim da jornada. |
companyBranchId | string | não | Identificador do branch. Quando fornecido, o processo utiliza a configuração do branch especificado. |
references | array | Fluxos de revalidação | Array de objetos de referência. Obrigatório para fluxos +revalidation. Cada objeto possui referenceType (REFERENCE_TYPE_HUMAN_TOKEN) e referenceContent (o valor do humanToken obtido anteriormente). |
Respostas
| Campo | Tipo | Descrição |
|---|---|---|
id | string (UUID) | Identificador do processo. Use-o para consultar o processo novamente via Obter Processo. |
state | string | Estado do processo — veja Interpretando o resultado. Só nos fluxos API Only. |
token | string | Token do processo criado, você pode usá-lo para abrir a experiência do Journey SDK. Apenas nos fluxos Human Token Journey (humantoken, humantoken+revalidation). |
link | string | URL da Human Token Journey: envie o usuário para ela. Só nos fluxos Human Token Journey (humantoken, humantoken+revalidation). |
data.humanToken.value | string | Identificador estável e opaco do rosto (até 100 caracteres). A mesma pessoa sempre resolve para o mesmo valor. Só nos fluxos API Only (sem revalidação). |
data.humanTokenMatch | string | "true" se a selfie corresponder ao humanToken referenciado, "false" caso contrário. Só no fluxo +revalidation API Only. |
state | Significado | O que fazer |
|---|---|---|
PROCESS_STATE_FINISHED | data.humanToken.value preenchido: pessoa real, com Human Token. | Procure o value nos seus registros: se existir, é um usuário recorrente ou uma possível duplicidade; se não existir, é uma nova pessoa. |
PROCESS_STATE_FINISHED | Sem data.humanToken, ou com value vazio: inconclusivo. | Trate como inconclusivo. Nunca armazene nem compare um value vazio; refaça o processo ou rejeite, conforme suas regras de negócio. |
PROCESS_STATE_FAILED | Falha durante o processo de identificação. | Tente o processo novamente ou rejeite, conforme suas regras de negócio. |
PROCESS_STATE_CREATED | Processo criado. | Aguarde. Consulte o resultado mais tarde com Obter Processo. |
PROCESS_STATE_CANCELED | O processo foi cancelado. | Crie um novo processo, se o usuário ainda precisar ser verificado. |
Sempre verifique se data.humanToken.value não está vazio antes de usá-lo.
Códigos de Erro
O status HTTP retornado quando a access key no header x-unico-accesskey está ausente ou é inválida ainda está sendo confirmado. Veja Autenticação.
- 400 Bad Request
- 403 Forbidden
- 429 Too Many Requests
- 500 Internal Server Error
| Código | Mensagem | Descrição |
|---|---|---|
3 | invalid flow | Quando o fluxo especificado não existe. |
3 | INVALID_IMAGE | Quando a imagem não é um base64 válido, ou parece uma tentativa de injeção. |
3 | IMAGE_TOO_LARGE | Quando a imagem excede o tamanho máximo de 800 KB. |
3 | UNSUPPORTED_IMAGE_FORMAT | Quando o formato da imagem não é PNG, JPEG ou WebP. |
3 | MISSING_IMAGE | Quando a imagem é obrigatória para este fluxo e não foi enviada. |
3 | INVALID_REQUEST | Quando o body da requisição é nulo ou não pode ser interpretado. |
9 | monthly process limit of <monthly_limit> reached for this tenant | Quando o limite mensal de uso foi atingido. |
9 | PROCESS_FAILED | Quando o processo atingiu uma falha terminal durante a criação. |
| Código | Mensagem | Descrição |
|---|---|---|
7 | PERMISSION_DENIED | Quando as credenciais são válidas, mas não têm permissão para esta ação. |
Limite de taxa atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar o agravamento da restrição.
Boas práticas:
- Período de resfriamento (backoff): Interrompa ou reduza imediatamente as requisições subsequentes do seu sistema. Não reenvie continuamente requisições com falha em um loop curto.
- Filas e limitação (Queueing & throttling): Armazene em buffer ou enfileire as requisições de saída do seu lado para controlar o fluxo de tráfego antes de reenviá-las.
- Backoff exponencial com jitter: Ao retentar, aumente o tempo de espera exponencialmente entre as tentativas (por exemplo, 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito de manada onde todas as requisições enfileiradas retentam exatamente no mesmo milissegundo.
Enviar requisições continuamente a um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a capacidade operacional do seu sistema. Limitar adequadamente as requisições do seu lado garante uma integração mais suave e resiliente.
Para limites padrão, aumento de requisições e detalhes adicionais, consulte Limites de taxa.
| Código | Mensagem | Descrição |
|---|---|---|
13 | Internal failure! Try again later | Quando ocorre um erro interno. |
Para a lista completa de códigos deste endpoint, veja a referência Criar Processo da Human API.
Próximos passos
- Armazene o valor do
humanTokenjunto ao registro do usuário para reconhecer a mesma pessoa em chamadas futuras do Human Token. - Para consultar o processo novamente, para auditoria ou suporte, use Obter Processo.