Pular para o conteúdo principal
Obter ProcessoGET

Recupere um processo existente pelo seu identificador. Conforme 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.

Markdown
aviso

Antes de recuperar o processo, revise nossa configuração de webhook e as 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 path
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 process
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 a aplicação cliente é redirecionada ao final do fluxo.
userRedirectUrlURL completa da página de CbU que o usuário abre para executar a jornada (carrega o id e flags de comportamento).
stateEstado do ciclo de vida do processo (ex.: PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED).
resultVeredito final da avaliação. Valores PROCESS_RESULT_* (ex.: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Só é conclusivo quando state = PROCESS_STATE_FINISHED.
createdAtTimestamp (UTC) de criação do processo.
finishedAtTimestamp (UTC) de conclusão do processo.
personSubobjeto com os dados da pessoa sendo verificada.
purposeFinalidade do processo (ex.: personAuthentication, cadastro de pessoa).
servicesLista de serviços adicionais vinculados 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 (UTC) de expiração do processo/link.
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 do person
CampoSignificado
duiTypeTipo do documento de identificação único. 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 + DDD + 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 do companyData
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 de documento em uma de duas formas. Documentos processados pelo módulo de documentos da Unico, inclusive documentos reutilizados, carregam um código curto em maiúsculas (CNH). Processos criados somente pela API costumam carregar o tipo completo do dicionário (unico.moja.dictionary.br.cnh.v2.Cnh), mas também podem carregar um código curto. Trate as duas formas em qualquer caminho de integração. O código curto não carrega o país nem a versão do schema; a versão é retornada separadamente em doc.version.

Na forma curta, tipos de documento que usam o schema unificado — unified_schema na referência de campos — são reportados como o identificador de tipo em maiúsculas identificado durante a captura. Os valores mais comuns são IDCARD, DRIVERLICENSE, PASSPORT e VOTERID, mas a lista é aberta: outros tipos identificados durante a captura são retornados como estão, em maiúsculas. Trate valores fora desta lista. Passaportes dos EUA mantêm sua variante em vez de colapsar para PASSPORT: POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT e REFUGEEPASSPORT 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

Tipos de documento que usam seu 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 motorista)
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 motorista)
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​PasaportePassaporte
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​UnknownTipo não pôde ser identificado, ou é um tipo brasileiro ou mexicano sem schema próprio — doc.data está vazio

Documentos brasileiros e mexicanos usam apenas os schemas específicos acima. Um documento brasileiro ou mexicano de qualquer outro tipo — por exemplo, uma carteira de residente mexicana — é reportado como UNKNOWN, e não com o schema unificado.

PASSAPORTE e PASAPORTE são documentos diferentes

O passaporte brasileiro é PASSAPORTE (com S duplo) e o mexicano é PASAPORTE (com S simples), cada um espelhando a grafia do seu próprio dicionário. Isso 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 completo do processo abaixo, com resultados por capacidade em authenticationInfo.

{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"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": "USE_CASE_LOGIN",
"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_UNSPECIFIED",
"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": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"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 criação do processo.
process.finishedAtstring (datetime)Timestamp ISO 8601 de conclusão do processo. Presente apenas quando state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)Timestamp ISO 8601 de expiração do processo.
process.purposestringFinalidade do processo conforme configurada 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 de stringsLista de capacidades ativadas neste processo.
process.tokenstringJWT assinado para integração via 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 de empresa e filial.
process.​companyData.​branchIdstringIdentificador da filial.
process.​companyData.​countryCodestringCódigo de país ISO 3166-1 alpha-3 (ex.: BRA).
process.​bioTokenDataobjectInformações do processo de referência — presente apenas em fluxos de 1:1 Validation e Smart Revalidation.
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 concluiu a jornada.
PROCESS_STATE_AWAITING_FOR_DOCUMENTProcesso criado sem documento de identificação. Presente apenas quando o Custom Flow permite documento opcional. Envie o documento com Definir Documento do Processo.
PROCESS_STATE_FINISHEDJornada concluída. Verifique result e authenticationInfo.
PROCESS_STATE_FAILEDErro de processamento.
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.: liveness falhou, identidade não correspondida).
PROCESS_RESULT_ERRORErro durante o processamento do resultado.
PROCESS_RESULT_EXPIREDProcesso expirou antes da conclusão da jornada.
PROCESS_RESULT_UNSPECIFIEDProcesso ainda não finalizado.
Resultados de capacidade em authenticationInfo

Todos os campos são sempre retornados independentemente do fluxo. Campos de capacidades não usadas 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 desta 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.scoreSemelhança do Serpro0–100 (semelhança); -1 (nenhuma face registrada para este CPF); -2 (erro de integração).
deviceMetadataMetadados do DispositivoObjeto com status (found, not_found, unavailable) e os dados do dispositivo. Ausente quando a capacidade não está habilitada no fluxo.
Campos de process.services
Um item por módulo

services contém um item por módulo concluído no processo: a execução concluída mais recente de cada módulo, e só enquanto o processo está PROCESS_STATE_FINISHED ou PROCESS_STATE_AWAITING_FOR_DOCUMENT. Processos criados somente pela API trazem o item de documento em qualquer estado. Um item de captura de documentos traz documents e consent_granted. Um item de assinatura eletrônica traz envelope_id e document_ids. Os itens não têm campo de tipo e a ordem deles não é estável: identifique cada um pelas suas chaves, não pela posição, e ignore os itens que você não reconhecer. As chaves são snake_case, exceto as de doc.data, que seguem o schema do documento (ex.: nomeCivil).

CampoTipoDescrição
consent_grantedbooleanItem de captura de documentos. Se o usuário concedeu consentimento para compartilhar os documentos com a sua empresa.
documentsarrayItem de captura de documentos. Documentos capturados com dados de OCR e resultados de validação.
documents[].doc_idstringIdentificador do documento.
documents[].​share_idstringIdentificador do compartilhamento que o usuário concedeu à sua empresa para este processo.
documents[].​typifiedbooleanSe o tipo de documento foi identificado.
documents[].​cpf_matchbooleanSomente Brasil. Se o CPF no documento corresponde ao CPF enviado na criação. Sempre presente para empresas com país definido como Brasil; omitido para outros países e para empresas sem país definido.
documents[].​validate_docbooleanSomente Brasil. Se o documento passou na validação de documentos da Unico. Sempre presente para empresas com país definido como Brasil (false quando a validação não foi executada); omitido para outros países e para empresas sem país definido.
documents[].​face_matchboolean ou nullSe a selfie corresponde à foto do documento. null significa que a verificação não foi executada — não é um resultado negativo.
documents[].​verifiedboolean ou nulltrue somente quando o tipo de documento é conhecido, o documento não foi excluído, face_match é true e o documento passou nas verificações de qualidade. false caso contrário, inclusive quando face_match não foi executado. null quando o processo não passou pelo módulo de documentos.
documents[].​reused_docbooleanSe este documento foi reutilizado de um processo anterior.
documents[].​signed_urlstringURL assinada de curta duração para download da imagem do documento. Ela expira: não a armazene nem conte com um tempo de validade fixo, e chame este endpoint novamente para obter uma nova.
documents[].​doc.​versionintegerVersão do dicionário do tipo de documento (ex.: 2 para unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringTipo de documento, como código curto (ex.: CNH) ou como tipo completo do dicionário (ex.: unico.moja.dictionary.br.cnh.v2.Cnh). Documentos processados pelo módulo de documentos carregam o código curto. Trate ambos. Veja 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 seguem o schema do documento: português para documentos brasileiros (ex.: nomeCivil, dataNascimento), espanhol para documentos mexicanos e inglês para o schema unificado.
envelope_idstring (UUID)Item de assinatura eletrônica. Identificador do envelope assinado.
document_idsarray de stringsItem de assinatura eletrônica. IDs dos documentos no envelope.
Processos criados somente pela API

Em um processo criado somente pela API, o item de documento vem da chamada à API, e não do módulo de documentos da Unico, e alguns valores diferem da tabela acima:

  • consent_granted é sempre false: a sua empresa coleta o consentimento, e a Unico não o acompanha.
  • share_id e signed_url vêm vazios.
  • face_match é sempre true ou false, nunca null.
  • verified é sempre null.
  • doc.version é 0.
  • doc.code costuma carregar o tipo completo do dicionário (ex.: unico.moja.dictionary.br.cnh.v2.Cnh), mas pode carregar um código curto.
  • doc.data vem null quando os dados de OCR não puderam ser lidos.

Códigos de Erro​

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

Polling vs. webhook​

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

Próximos passos​