Obter Processo

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.idcloud.unico.app/client/v1/process/{processId}`
Sandbox	`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}`

Requisição

Headers

Header	Valor
`Authorization`	`Bearer <access_token>`

Parâmetros de caminho

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

Exemplo

cURL
Node.js

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN"

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.idcloud.unico.app/client/v1/process/${processId}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();

Respostas

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "callbackUri": "https://example.com/callback",
    "userRedirectUrl": "https://example.com/redirect",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_OK",
    "createdAt": "2024-01-01T10:00:00Z",
    "finishedAt": "2024-01-01T10:15:00Z",
    "expiresAt": "2024-01-08T10:00:00Z",
    "purpose": "VERIFICATION",
    "clientReference": "client-ref-abc",
    "useCase": "smart_revalidation",
    "capacities": ["liveness", "face_match"],
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "notifications": [
        {
          "notificationChannel": "email"
        }
      ]
    },
    "authenticationInfo": {
      "authenticationId": "auth-123",
      "livenessResult": "LIVENESS_RESULT_LIVE",
      "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
      "identityFraudstersResult": "TRUST_RESULT_INCONCLUSIVE",
      "bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
      "smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
      "idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
      "scoreEngineResult": {
        "scoreEnabled": "SCORE_ENABLED_TRUE",
        "score": 85.5
      }
    },
    "companyData": {
      "branchId": "branch-123",
      "countryCode": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "code": "CNH",
              "data": {
                "numero": "044589731564",
                "cpfNumero": "12345678909",
                "nomeCivil": "Luke Skywalker",
                "dataNascimento": "1990-05-12T00:00:00Z",
                "dataExpiracao": "2027-12-07T00:00:00Z",
                "categoria": "B"
              }
            }
          }
        ]
      }
    ]
  }
}

Campos de nível superior

Campo	Tipo	Descrição
`process.id`	string (UUID)	Identificador do processo.
`process.flow`	string	Identificador do fluxo enviado na criação.
`process.callbackUri`	string	URL de callback configurada para eventos do processo.
`process.userRedirectUrl`	string	URL para redirecionar o usuário após a conclusão da jornada.
`process.state`	enum	Estado atual do processo. Veja os valores abaixo.
`process.result`	enum	Resultado da verificação. Presente apenas quando `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	Timestamp ISO 8601 de quando o processo foi criado.
`process.finishedAt`	string (datetime)	Timestamp ISO 8601 de quando o processo foi finalizado. Presente apenas quando `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	Timestamp ISO 8601 de quando o processo expira.
`process.purpose`	string	Finalidade do processo conforme configurado no fluxo.
`process.clientReference`	string	Referência opcional do lado do cliente para indexação no portal.
`process.useCase`	string	Identificador do caso de uso associado ao fluxo.
`process.capacities`	array of strings	Lista de capacidades ativadas neste processo.
`process.token`	string	JWT assinado para integração com SDK.
`process.person`	object	Identificação fornecida na criação.
`process.person.notifications`	array	Canais de notificação configurados para a jornada (ex.: `email`).
`process.authenticationInfo`	object	Resultados por capacidade. Veja abaixo.
`process.companyData`	object	Contexto da empresa e filial.
`process.companyData.branchId`	string	Identificador da filial.
`process.companyData.countryCode`	string	Código de país ISO 3166-1 alpha-2.
`process.bioTokenData`	object	Informações do processo de referência — presente apenas em fluxos de Validação 1:1 e Revalidação Inteligente.
`process.services`	array	Envelopes assinados, documentos capturados e outras saídas de serviço. Veja abaixo.

Valores de process.state

Valor	Significado
`PROCESS_STATE_CREATED`	Processo criado; o usuário ainda não completou a jornada.
`AWAITING_FOR_DOCUMENT`	Processo criado sem documento de identificação; aguardando que seja definido via Definir Documento do Processo. Presente apenas quando o Fluxo Personalizado permite documento opcional.
`PROCESS_STATE_FINISHED`	Jornada concluída. Verifique `result` e `authenticationInfo`.
`PROCESS_STATE_FAILED`	Erro de processamento.

Inconsistência de nomenclatura de estado

AWAITING_FOR_DOCUMENT não segue a convenção de prefixo PROCESS_STATE_* usada pelos outros estados. Esta é uma inconsistência de nomenclatura conhecida na API atual.

Valores de process.result

Valor	Significado
`PROCESS_RESULT_OK`	Todas as capacidades retornaram resultados positivos.
`PROCESS_RESULT_INVALID_IDENTITY`	Pelo menos uma capacidade retornou um negativo definitivo (ex.: prova de vida falhou, identidade não correspondida).
`PROCESS_RESULT_ERROR`	Erro durante o processamento do resultado.
`PROCESS_RESULT_EXPIRED`	O processo expirou antes da conclusão da jornada.
`PROCESS_RESULT_UNSPECIFIED`	Processo ainda não finalizado.

Resultados de capacidades em authenticationInfo

Todos os campos são sempre retornados independentemente do fluxo. Campos para capacidades não utilizadas no fluxo retornam *_UNSPECIFIED.

Valores de enum abreviados

Valores abreviados (ex.: livenessResult = LIVE, authenticationResult = INCONCLUSIVE) mapeiam diretamente para os valores de enum completos documentados aqui (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — o prefixo é omitido por brevidade.

Campo	Capacidade	Valores possíveis
`authenticationId`	—	Identificador único para esta tentativa de autenticação.
`livenessResult`	Prova de Vida	`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED`
`authenticationResult`	Verificação de Identidade	`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED`
`identityFraudstersResult`	Classificação de Risco de Fraude	`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED`
`bioTokenEngineResult`	Validação 1:1	`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED`
`smartRevalidationResult`	Revalidação Inteligente	`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED`
`idAgeResult`	Verificação de Idade	`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED`
`scoreEngineResult.scoreEnabled`	Score de Risco	`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED`
`scoreEngineResult.score`	Score de Risco	Número de -100 a +100. Presente quando `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` e o Score de Risco está habilitado.
`serproResult.score`	Retorno de Semelhança do Serpro	`0`–`100` (similaridade); `-1` (sem face em arquivo para este CPF); `-2` (erro de integração).

Campos de process.services

Convenções de nomenclatura mistas em services

O array services utiliza camelCase para campos de nível de envelope (envelopeId, documentIds) e snake_case para campos de nível de documento (doc_id, consent_granted, face_match, etc.). Isso reflete a resposta real da API — ambas as convenções são intencionais e não constituem um erro de documentação.

Campo	Tipo	Descrição
`envelopeId`	string (UUID)	Identificador do envelope assinado.
`documentIds`	array of strings	IDs dos documentos capturados neste serviço.
`consent_granted`	boolean	Se o usuário concedeu consentimento de compartilhamento de dados.
`documents`	array	Documentos capturados com dados de OCR e resultados de validação.
`documents[].doc_id`	string	Identificador do documento.
`documents[].typified`	boolean	Se o tipo de documento foi identificado com sucesso.
`documents[].cpf_match`	boolean	Se o CPF no documento corresponde ao CPF fornecido.
`documents[].face_match`	boolean	Se a selfie corresponde à foto no documento.
`documents[].validate_doc`	boolean	Se o documento passou na validação de autenticidade.
`documents[].reused_doc`	boolean	Se este documento foi reutilizado de um processo anterior.
`documents[].signed_url`	string	URL pré-assinada para download do PDF do documento (válida por 5 minutos — refaça a consulta para renovar).
`documents[].doc.version`	integer	Versão do schema de OCR.
`documents[].doc.code`	string	Código do tipo de documento (ex.: `CNH`, `RG`).
`documents[].doc.data`	object	Campos de OCR extraídos. O conteúdo varia por tipo de documento e dados disponíveis. Os nomes dos campos dentro de `doc.data` (ex.: `nomeCivil`, `dataNascimento`) são retornados em português — esses são os valores reais produzidos pelo motor de OCR.

400 Bad Request

O parâmetro de caminho processId está ausente ou malformado.

401 Unauthorized

Bearer token ausente, expirado ou inválido.

404 Not Found

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

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.

Códigos de Erro

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

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

Código	Mensagem	Descrição
—	Jwt header is an invalid JSON	Quando o access token utilizado contém caracteres incorretos.
—	Jwt is expired	Quando o access token utilizado expirou.

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.

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

Polling vs webhook

Você pode consultar este endpoint para verificar o progresso, mas o padrão recomendado é assinar um webhook e usar este endpoint apenas como fallback. Veja Webhooks e Eventos.

Próximos passos

Para a selfie capturada, veja Obter Selfie.
Para o pacote de auditoria de evidências, veja Obter Conjunto de Evidências.

Endpoint​

Requisição​

Exemplo​

Respostas​

Códigos de Erro​

Polling vs webhook​

Próximos passos​