Pular para o conteúdo principal
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​

AmbienteURL
ProduçãoGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Requisição​

Headers
HeaderValor
AuthorizationBearer <access_token>
Parâmetros de caminho
ParâmetroTipoObrigatórioDescrição
processIdstring (UUID)simIdentificador do processo retornado por Criar Processo.

Exemplo​

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

Respostas​

200 OK
{
  "process": {
    "id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
    "flow": "id_r2",
    "callbackUri": "/",
    "userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_APPROVED",
    "createdAt": "2026-08-06T01:42:21.693615Z",
    "finishedAt": "2026-08-06T01:43:03.080508Z",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "40*******50",
      "friendlyName": "teste",
      "email": "",
      "phone": "5511999999999",
      "notifications": [
        { "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
      ],
      "phoneCountryCodeAlpha3": ""
    },
    "purpose": "personAuthentication",
    "services": [],
    "authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
    "capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
    "expiresAt": "2026-08-13T01:42:21.536500Z",
    "token": "",
    "companyData": { "branchId": "", "countryCode": "BRA" },
    "simulated": false
  }
}
Campos do processo
CampoSignificado
idUUID do processo; a chave usada para consultar e acompanhar o fluxo.
flowTipo de jornada executada (ex.: id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriURI de callback para a qual o aplicativo cliente é redirecionado ao final do fluxo.
userRedirectUrlURL completa da página CbU que o usuário abre para executar a jornada (contém o id e flags de comportamento).
stateEstado do ciclo de vida do processo. Valores PROCESS_STATE_* (ex.: CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, UNSPECIFIED).
resultVeredito final da avaliação. Valores PROCESS_RESULT_* (ex.: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Só é conclusivo quando state = PROCESS_STATE_FINISHED.
createdAtTimestamp de criação do processo (UTC).
finishedAtTimestamp de conclusão do processo (UTC).
personSubobjeto com os dados da pessoa sendo verificada.
purposeFinalidade do processo (ex.: personAuthentication, cadastro de pessoa).
servicesLista de serviços adicionais associados ao processo; vazia quando não há nenhum.
authenticationInfo.authenticationIdID do evento de autenticação de identidade gerado pelo fluxo.
capacitiesCapacidades/produtos utilizados. Valores PROCESS_CAPACITY_* (ex.: IDCLOUDONE).
expiresAtTimestamp de expiração do processo/link (UTC).
tokenToken de sessão/acesso associado ao processo (pode estar vazio).
companyDataSubobjeto com os dados da empresa/tenant proprietário do processo.
simulatedBooleano; indica se este é um processo de simulação/sandbox (true) ou real (false).
Campos da pessoa
CampoSignificado
duiTypeTipo do documento único de identificação. Valores DUI_TYPE_* (ex.: BR_CPF).
duiValueValor do documento (ex.: o número do CPF).
friendlyNameNome amigável/apelido da pessoa (texto livre, não validado).
emailE-mail da pessoa; pode estar vazio.
phoneNúmero de telefone no formato E.164 (código do país + código de área + número).
notificationsLista de canais de notificação. Cada item carrega notificationChannel com valores NOTIFICATION_CHANNEL_* (ex.: WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3Código de país ISO alpha-3 do número de telefone (ex.: BRA); pode estar vazio.
Campos de dados da empresa
CampoSignificado
branchIdIdentificador da filial do tenant; vazio quando não há segmentação por filial.
countryCodePaís da empresa em ISO alpha-3 (ex.: BRA).
Tipos de documento e campos de OCR

process.services[].documents[].doc.code reporta o tipo do documento como um código curto em maiúsculas. unico.moja.dictionary.br.cnh.v2.Cnh vira CNH. O código não carrega nem o país nem a versão do schema; a versão é retornada separadamente em doc.version.

Os tipos de documento que usam o schema unificado — unified_schema na referência de campos — são reportados como o tipo identificado na captura, em maiúsculas: IDCARD, DRIVERLICENSE, PASSPORT ou VOTERID. Os passaportes dos EUA mantêm a variante em vez de serem agrupados em PASSPORT, então valores como POLYCARBONATEPASSPORT, PASSPORTCARD e PAPERPASSPORT também são retornados. Por exemplo, unico.moja.dictionary.ar.generic.v1.IdCard e unico.moja.dictionary.us.generic.v1.PolycarbonatePassport são reportados como IDCARD e POLYCARBONATEPASSPORT.

Schemas específicos

Os tipos de documento que usam o próprio schema de campos — listados em specific_document_schemas na referência de campos — são mostrados na tabela abaixo. Use o tipo do dicionário para consultar cada schema nesse arquivo.

Paísdoc.codeTipo do dicionárioDocumento
BRRGunico.moja.dictionary.br.rg.v2.RgRG
BRCNHunico.moja.dictionary.br.cnh.v2.CnhCNH (carteira de habilitação)
BRCINunico.moja.dictionary.br.cin.v1.CinCIN
BRPASSAPORTEunico.moja.dictionary.br.passaporte.v1.PassaportePassaporte
MXINEunico.moja.dictionary.mx.ine.v1.IneCredencial de eleitor INE
MXLPCunico.moja.dictionary.mx.lpc.v1.LpcLicencia para conducir (carteira de habilitação)
MXPASAPORTEunico.moja.dictionary.mx.pasaporte.v1.PasaportePassaporte
—UNKNOWNunico.moja.dictionary.other.unknown.v1.UnknownO tipo não pôde ser identificado — doc.data está vazio
PASSAPORTE e PASAPORTE são documentos diferentes

O passaporte brasileiro é PASSAPORTE (com dois S) e o mexicano é PASAPORTE (com um S), cada um espelhando a grafia do próprio dicionário. Não é um erro de digitação — não trate os dois valores como equivalentes.

Nenhuma extração de OCR é realizada e nenhum campo é reportado em doc.data quando doc.code é UNKNOWN.

BrazilClientes no Brasil podem receber o payload completo do processo

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

Integrações no Brasil podem receber o objeto de processo completo abaixo, com resultados por capacidade em authenticationInfo.

{
  "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
CampoTipoDescrição
process.idstring (UUID)Identificador do processo.
process.flowstringIdentificador do fluxo enviado na criação.
process.callbackUristringURL de callback configurada para eventos do processo.
process.userRedirectUrlstringURL para redirecionar o usuário após a conclusão da jornada.
process.stateenumEstado atual do processo. Veja os valores abaixo.
process.resultenumResultado da verificação. Presente apenas quando state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)Timestamp ISO 8601 de quando o processo foi criado.
process.finishedAtstring (datetime)Timestamp ISO 8601 de quando o processo foi finalizado. Presente apenas quando state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)Timestamp ISO 8601 de quando o processo expira.
process.purposestringFinalidade do processo conforme configurado no fluxo.
process.clientReferencestringReferência opcional do lado do cliente para indexação no portal.
process.useCasestringIdentificador do cenário associado ao fluxo.
process.capacitiesarray of stringsLista de capacidades ativadas neste processo.
process.tokenstringJWT assinado para integração com SDK.
process.personobjectIdentificação fornecida na criação.
process.person.notificationsarrayCanais de notificação configurados para a jornada (ex.: email).
process.authenticationInfoobjectResultados por capacidade. Veja abaixo.
process.companyDataobjectContexto da empresa e filial.
process.companyData.branchIdstringIdentificador da filial.
process.companyData.countryCodestringCódigo de país ISO 3166-1 alpha-2.
process.bioTokenDataobjectInformações do processo de referência — presente apenas em fluxos de Validação 1:1 e Revalidação Inteligente.
process.servicesarrayEnvelopes assinados, documentos capturados e outras saídas de serviço. Veja abaixo.
Valores de process.state
ValorSignificado
PROCESS_STATE_CREATEDProcesso criado; o usuário ainda não completou a jornada.
AWAITING_FOR_DOCUMENTProcesso 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_FINISHEDJornada concluída. Verifique result e authenticationInfo.
PROCESS_STATE_FAILEDErro 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
ValorSignificado
PROCESS_RESULT_OKTodas as capacidades retornaram resultados positivos.
PROCESS_RESULT_INVALID_IDENTITYPelo menos uma capacidade retornou um negativo definitivo (ex.: prova de vida falhou, identidade não correspondida).
PROCESS_RESULT_ERRORErro durante o processamento do resultado.
PROCESS_RESULT_EXPIREDO processo expirou antes da conclusão da jornada.
PROCESS_RESULT_UNSPECIFIEDProcesso 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.

CampoCapacidadeValores possíveis
authenticationId—Identificador único para esta tentativa de autenticação.
livenessResultProva de VidaLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultVerificação de IdentidadeAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultClassificação de Risco de FraudeTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResultValidação 1:1BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultRevalidação InteligenteSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultVerificação de IdadeID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.scoreEnabledScore de RiscoSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.scoreScore de RiscoNúmero de -100 a +100. Presente quando authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE e o Score de Risco está habilitado.
serproResult.scoreRetorno de Semelhança do Serpro0–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.

CampoTipoDescrição
envelopeIdstring (UUID)Identificador do envelope assinado.
documentIdsarray of stringsIDs dos documentos capturados neste serviço.
consent_grantedbooleanSe o usuário concedeu consentimento de compartilhamento de dados.
documentsarrayDocumentos capturados com dados de OCR e resultados de validação.
documents[].doc_idstringIdentificador do documento.
documents[].typifiedbooleanSe o tipo de documento foi identificado com sucesso.
documents[].cpf_matchbooleanSe o CPF no documento corresponde ao CPF fornecido (apenas Brasil).
documents[].face_matchbooleanSe a selfie corresponde à foto no documento.
documents[].validate_docbooleanSe o documento passou na validação de autenticidade.
documents[].reused_docbooleanSe este documento foi reutilizado de um processo anterior.
documents[].signed_urlstringURL pré-assinada para download do PDF do documento (válida por 5 minutos — refaça a consulta para renovar).
documents[].doc.versionintegerVersão do schema de OCR.
documents[].doc.codestringCódigo curto do tipo de documento (ex.: CNH). Consulte Tipos de documento e campos de OCR para todos os valores e como o código é derivado.
documents[].doc.dataobjectCampos de OCR extraídos. O conteúdo varia por tipo de documento — veja a referência completa de campos para o catálogo completo. Os nomes dos campos dentro de doc.data (ex.: nomeCivil, dataNascimento) são os nomes reais produzidos pelo motor de OCR — já em português.

Códigos de Erro​

CódigoMensagemDescrição
3process id is invalidQuando o ID do processo é inválido.

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​

Última atualização em