Obter ProcessoGET

Recupere um processo existente pelo seu identificador. De acordo com o contrato da API, o resultado já é retornado de forma síncrona na criação do processo — use este endpoint para reconsultas, auditoria e suporte.

aviso

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

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

O contrato é único — o campo idCloud.result carrega o veredito consolidado das capacidades utilizadas.

A Unico consolida os resultados das capacidades executadas em um único idCloud.result, pronto para decidir o próximo passo do seu fluxo — sem necessidade de orquestrar resultados individuais.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

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).

Valores possíveis de resultado

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

Os valores retornados dependem da receita configurada na sua APIKey. Veja Fluxos os valores de resultado que cada receita pode retornar.

Clientes no Brasil podem receber a resposta por capacidade

A estrutura geral da resposta permanece a mesma — o resultado único é o padrão.

Integrações no Brasil podem receber os resultados abertos, por capacidade. Cada capacidade habilitada na APIKey adiciona seu próprio bloco à resposta — campos de capacidades desabilitadas são omitidos.

{
  "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,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

Campo	Tipo	Descrição
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 — veja Identificador Facial.
idFace.personId	string	Identificador opaco estável para o rosto, retornado junto com idFace.result = FOUND. Quando nenhum rosto pode ser identificado na imagem, o processo retorna o erro 20532 em vez de um bloco idFace.
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.
idAge.result	string	yes, no, inconclusive — veja Verificação de Idade. Disponível apenas no Brasil.
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.
cardholderVerification.result	string	approved, unsure — veja Cardholder Verification. Ausente enquanto status ainda não é 3 (finalizado). Disponível apenas no Brasil.

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.

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

aviso

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

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

Fluxos

Uma receita é a combinação de capacidades (prova de vida, verificação de identidade, sinais de risco, documentos...) configurada na APIKey do seu projeto. Ela define o que a Unico executa em cada processo e como os resultados são consolidados no result único — você não precisa orquestrar nada do seu lado.

A Unico mantém um catálogo de receitas pré-estabelecidas, nomeadas e versionadas (ex. byunico-idlive-idunico-oneresponse-std). Algumas são exclusivas do Brasil, como as que incluem Score, Serpro ou verificação de idade.

Quais capacidades o seu processo executa?

A combinação de capacidades — o fluxo do seu projeto — é definida na configuração da sua APIKey. Consulte as receitas pré-estabelecidas ou fale com o contato do seu projeto na Unico para personalizá-la.