Obter ProcessoGET

Recupere um processo de Human Token pelo seu identificador — depois que o usuário retorna da Human Token Journey, ou para consultar novamente um resultado de API Only.

Markdown

Endpoint

Ambiente	URL
Produção	GET https://humantoken.unico.app/client/v1/process/{processId}

Requisição

Headers

Header	Valor
x-unico-accesskey	<your_access_key> (veja Autenticação)

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
processId	string (UUID)	sim	Identificador do processo retornado por Criar Processo.

Exemplo

cURL

curl -X GET https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://humantoken.unico.app/client/v1/process/${processId}`,
  { headers: { 'x-unico-accesskey': process.env.UNICO_ACCESS_KEY } }
);
const result = await res.json();
// result.data.humanToken.value

Respostas

200 OK

A resposta tem o mesmo formato de Criar Processo. O formato de data depende do fluxo utilizado quando o processo foi criado.

Fluxos padrão (api+humantoken, api+liveness+humantoken, humantoken):

{
  "id": "6ed74799-4c2f-4023-b43f-a73cf7c847b2",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": {
      "value": "3f9a1c7e5b2d4086a1e3c5f7092b4d6e8a0c2e4f6183a5c7e9b1d3f5072a4c6e",
      "status": "validated"
    }
  }
}

Fluxos de revalidação (api+liveness+humantoken+revalidation, humantoken+revalidation):

{
  "id": "cb0472c0-6dbc-46c6-b830-2be7edc35424",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanTokenMatch": "true"
  }
}

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo.
state	string	Estado do processo — veja valores de state.
data.​humanToken.​value	string	Apenas fluxos padrão. Identificador estável e opaco do rosto (até 100 caracteres). A mesma pessoa sempre resolve para o mesmo valor.
data.​humanTokenMatch	string	Apenas fluxos de revalidação. "true" se a selfie corresponde ao humanToken referenciado, "false" caso contrário.

Valores de state

Valor	Significado
PROCESS_STATE_UNSPECIFIED	Estado não definido.
PROCESS_STATE_CREATED	O processo foi criado e ainda aceita novas sessões. data vem {}.
PROCESS_STATE_FINISHED	O processo foi finalizado e não aceita mais novas sessões. Para fluxos padrão, data.humanToken vem preenchido quando um Human Token foi gerado; para fluxos de revalidação, data.humanTokenMatch indica se a selfie correspondeu ao token referenciado. Caso contrário, data vem {}.
PROCESS_STATE_FAILED	O processo falhou. data vem {}.
PROCESS_STATE_CANCELED	O processo foi cancelado. data vem {}.
PROCESS_STATE_AWAITING_FOR_DOCUMENT	O processo aguarda um documento de identificação. data vem {}.

aviso

Sempre verifique se data.humanToken.value não está vazio antes de usá-lo.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
3	process id is invalid	Quando o ID do processo é inválido.

401 Unauthorized

Access key ausente ou inválida no header x-unico-accesskey. Veja Autenticação.

404 Not Found

Código	Mensagem	Descrição
5	error getting process: rpc error: code = NotFound desc = process not found	Quando o ID do processo não foi encontrado.

429 Too Many Requests

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.

aviso

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.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later	Quando ocorre um erro interno.

Próximos passos

• Volte para Criar Processo para enviar uma nova selfie.
• Para entender o que o humanToken representa e quando ele não é gerado, veja a visão geral do Human Token.