Obter Processo

aviso

Antes de recuperar o processo, revise nossa configuração de webhook e estratégias de fallback — clique aqui.

No contrato API, a resposta do POST /processes/v1 já é o resultado final. Este endpoint existe para re-consultas — por exemplo, quando você precisa inspecionar um processo que persistiu anteriormente, ou auditar uma transação anterior. No contrato de API, a resposta do POST /processes/v1 já é o resultado final. Este endpoint existe para reconsultas — por exemplo, quando você precisa inspecionar um processo que persistiu anteriormente, ou auditar uma transação anterior.

Endpoint

Ambiente	URL
Produção	GET https://api.id.unico.app/processes/v1/{processId}
Sandbox	GET https://api.id.uat.unico.app/processes/v1/{processId}

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token>
APIKEY	Chave de API provisionada.

Parâmetros de caminho

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

Exemplo

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

Respostas

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Os campos da resposta dependem da sua APIKey

O exemplo acima exibe todos os campos de capacidades possíveis. Sua resposta real incluirá apenas os campos das capacidades habilitadas na configuração da sua APIKey — campos de capacidades desabilitadas são omitidos. Entre em contato com o gerente de projetos da Unico para habilitar ou ajustar capacidades.

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo.
status	integer	1 (processando), 2 (divergência), 3 (finalizado com sucesso), 4 (cancelado), 5 (erro).
unicoId.result	string	yes, no, inconclusive — veja Verificação de Identidade.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive — veja Classificação de Risco de Fraude.
idFace.result	string	FOUND, NOT_FOUND — veja Identificador Facial.
idFace.personId	string	Identificador opaco estável para o rosto. Presente apenas quando idFace.result = FOUND.
identityFraudsters.result	string	Obsoleto. Use riskLevel em vez disso. Clientes com integrações em andamento podem continuar utilizando enquanto alinham a migração com a equipe responsável pelo projeto.
government.serpro	integer	Score de similaridade Serpro (0–100, -1, -2). Disponível apenas no Brasil. Veja Retorno de Semelhança do Serpro.
liveness	integer	1 (aprovado), 2 (reprovado) — veja Prova de Vida.
score	integer	Score de risco probabilístico. Presente quando unicoId.result = inconclusive e a orquestração de score de risco está ativa. Valores positivos indicam maior probabilidade de ser o titular; valores negativos indicam maior risco. Disponível apenas no Brasil.

400 Bad Request

O parâmetro de caminho processId está ausente ou malformado. Veja Códigos de Erro abaixo.

403 Forbidden

Bearer token ou APIKEY ausente, expirado ou inválido.

404 Not Found

O processId não existe ou não pertence ao tenant autenticado.

410 Gone

O processo existe mas resultou em erro. Retorna apenas id e status: 5.

429 Too Many Requests

Limite de requisições atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar agravar a restrição.

Boas práticas:

• Período de espera (backoff): Interrompa ou limite imediatamente as requisições subsequentes do seu sistema. Não tente reenviar requisições falhas continuamente em um loop apertado.
• Enfileiramento e controle de fluxo: Armazene 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 tentar novamente, aumente o tempo de espera exponencialmente entre as tentativas (ex.: 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito manada onde todas as requisições enfileiradas tentam novamente no exato mesmo milissegundo.

aviso

Continuar acessando um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a taxa de transferência operacional do seu sistema. Controlar 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, veja Limites de Taxa.

500 Internal Server Error

Erro inesperado no servidor.

Quando usar este endpoint

O contrato de API retorna resultados de forma síncrona, então a maioria das integrações não precisa deste endpoint. Use-o quando:

• Você persistiu apenas o processId e precisa recuperar o resultado completo posteriormente (auditoria, suporte).
• Você suspeita que a resposta original foi perdida em trânsito (erro de rede após a plataforma completar o processamento).
• Você está construindo uma ferramenta de back-office que revisa processos históricos.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
20023	O parâmetro processId não foi informado.	O parâmetro de ID do processo está ausente.
20002	O parâmetro APIKey não foi informado.	O parâmetro APIKEY está ausente no header da requisição.
20001	O parâmetro authtoken não foi informado.	O parâmetro de token de integração está ausente no header da requisição.

404 Not Found

Código	Mensagem	Descrição
50001	O processo informado não foi encontrado.	O processo não existe no banco de dados.

403 Forbidden

Código	Mensagem	Descrição
30017	User does not have permission to perform this action.	JWT malformado ou usuário sem permissão para executar esta operação.
10502	O token informado está expirado.	Quando o access-token utilizado expirou.
10501	O token informado é inválido.	O token de autenticação é inválido.
10201	O AppKey informado é inválido.	O parâmetro APIKEY não foi informado ou não existe.

410 Gone

O processo existe mas resultou em erro. Retorna apenas id e status: 5.

500 Internal Server Error

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