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.

MarkdownChatGPTClaude

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	Significado	Ação recomendada
approved	Pessoa real e identidade validada.	Prossiga com o fluxo.
denied	Identidade não validada, falha na prova de vida, ou risco extremo identificado.	Encerre o fluxo ou redirecione para um fluxo alternativo.
critical-risk	Nível de risco crítico identificado.	Encerre o fluxo ou encaminhe para revisão manual.
high-risk	Nível de risco alto identificado.	Encaminhe para revisão manual ou para um fluxo alternativo.
retry	Captura ou score insuficiente para avaliação.	Solicite uma nova captura ao usuário.
inconclusive	Evidências insuficientes para um veredito.	Encaminhe para revisão manual ou para um fluxo alternativo.

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.

Clientes no México podem receber o bloco de Verificação RENAPO

A resposta mantém a mesma estrutura e acrescenta o bloco idGov.

Integrações no México com a Verificação RENAPO habilitada recebem um bloco idGov adicional com o registro que o RENAPO mantém para a CURP do usuário. É uma resposta separada do resultado de identidade.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Campo	Tipo	Descrição
idGov	object	Registro do RENAPO para a CURP. Ausente quando a capability não está habilitada. {} quando o RENAPO não respondeu. Apenas México. Veja Verificação RENAPO.

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

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