--- title: Obter Processo description: Recupere o estado atual e o resultado de um processo de verificação. canonical: https://developer.unico.io/pt-BR/developers/api-reference/get-process locale: pt-BR generated_by: markdown-export --- - [/pt-BR/](/pt-BR/) - Referência de API - Obter Processo **Nesta páginaObter ProcessoGETRecupere 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. avisoAntes de recuperar o processo, revise nossa configuração de webhook e as estratégias de fallback — [clique aqui](/pt-BR/developers/webhooks-and-events/setup). ### Endpoint​ AmbienteURL**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 HeaderValor`Authorization``Bearer ` Parâmetros de path ParâmetroTipoObrigatórioDescrição`processId`string (UUID)simIdentificador do processo retornado por [Criar Processo](/pt-BR/developers/api-reference/post-processes). ### Exemplo​ cURLNode.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": "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`id`UUID do processo; a chave usada para consultar e acompanhar o fluxo.`flow`Tipo de jornada executada (ex.: `id_r2`, `idlivetrust_r2`, `idtrust_r2`, ...).`callbackUri`URI de callback para a qual a aplicação cliente é redirecionada ao final do fluxo.`userRedirectUrl`URL completa da página de CbU que o usuário abre para executar a jornada (carrega o `id` e flags de comportamento).`state`Estado do ciclo de vida do processo. Valores `PROCESS_STATE_*` (ex.: `CREATED`, `FAILED`, `FINISHED`, `AWAITING_FOR_DOCUMENT`, `UNSPECIFIED`).`result`Veredito final da avaliação. Valores `PROCESS_RESULT_*` (ex.: `APPROVED`, `AUTHENTICATED`, `NOT_APPROVED`, ...). Só é conclusivo quando `state = PROCESS_STATE_FINISHED`.`createdAt`Timestamp (UTC) de criação do processo.`finishedAt`Timestamp (UTC) de conclusão do processo.`person`Subobjeto com os dados da pessoa sendo verificada.`purpose`Finalidade do processo (ex.: `personAuthentication`, cadastro de pessoa).`services`Lista de serviços adicionais vinculados ao processo; vazia quando não há nenhum.`authenticationInfo.​authenticationId`ID do evento de autenticação de identidade gerado pelo fluxo.`capacities`Capacidades/produtos utilizados. Valores `PROCESS_CAPACITY_*` (ex.: `IDCLOUDONE`).`expiresAt`Timestamp (UTC) de expiração do processo/link.`token`Token de sessão/acesso associado ao processo (pode estar vazio).`companyData`Subobjeto com os dados da empresa/tenant proprietário do processo.`simulated`Booleano; indica se este é um processo de simulação/sandbox (`true`) ou real (`false`). Campos do person CampoSignificado`duiType`Tipo do documento de identificação único. Valores `DUI_TYPE_*` (ex.: `BR_CPF`).`duiValue`Valor do documento (ex.: o número do CPF).`friendlyName`Nome amigável/apelido da pessoa (texto livre, não validado).`email`E-mail da pessoa; pode estar vazio.`phone`Número de telefone no formato E.164 (código do país + DDD + número).`notifications`Lista de canais de notificação. Cada item carrega `notificationChannel` com valores `NOTIFICATION_CHANNEL_*` (ex.: `WHATSAPP`, `SMS`, `EMAIL`).`phoneCountryCodeAlpha3`Código de país ISO alpha-3 do número de telefone (ex.: `BRA`); pode estar vazio. Campos do companyData CampoSignificado`branchId`Identificador da filial do tenant; vazio quando não há segmentação por filial.`countryCode`País da empresa em ISO alpha-3 (ex.: `BRA`). Tipos de documento e campos de OCR Tipos de documento que usam o schema unificado — `unified_schema` na [referência de campos](/pt-BR/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json) — são reportados como o identificador de tipo em maiúsculas identificado durante a captura: `IDCARD`, `DRIVERLICENSE`, `PASSPORT` ou `VOTERID`. Passaportes dos EUA mantêm sua variante em vez de colapsar para `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`. `process.services[].documents[].doc.code` reporta o tipo de documento como um código curto em maiúsculas. `unico.moja.dictionary.br.cnh.v2.Cnh` se torna `CNH`. O código não carrega o país nem a versão do schema; a versão é retornada separadamente em `doc.version`. Schemas específicos Tipos de documento que usam seu próprio schema de campos — listados em `specific_document_schemas` na [referência de campos](/pt-BR/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json) — são mostrados na tabela abaixo. Use o tipo do dicionário para consultar cada schema nesse arquivo. País`doc.code`Tipo do dicionárioDocumentoBR`RG``unico.​moja.​dictionary.​br.​rg.​v2.​Rg`RGBR`CNH``unico.​moja.​dictionary.​br.​cnh.​v2.​Cnh`CNH (carteira de motorista)BR`CIN``unico.​moja.​dictionary.​br.​cin.​v1.​Cin`CINBR`PASSAPORTE``unico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte`PassaporteMX`INE``unico.​moja.​dictionary.​mx.​ine.​v1.​Ine`Credencial de eleitor INEMX`LPC``unico.​moja.​dictionary.​mx.​lpc.​v1.​Lpc`Licencia para conducir (carteira de motorista)MX`PASAPORTE``unico.​moja.​dictionary.​mx.​pasaporte.​v1.​Pasaporte`Passaporte—`UNKNOWN``unico.​moja.​dictionary.​other.​unknown.​v1.​Unknown`Tipo não pôde ser identificado — `doc.data` está vazio `PASSAPORTE` e `PASAPORTE` são documentos diferentesO 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`. Clientes no Brasil podem receber o payload completo do processoA 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": "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 superiorCampoTipoDescrição`process.id`string (UUID)Identificador do processo.`process.flow`stringIdentificador do fluxo enviado na criação.`process.callbackUri`stringURL de callback configurada para eventos do processo.`process.​userRedirectUrl`stringURL para redirecionar o usuário após a conclusão da jornada.`process.state`enumEstado atual do processo. Veja os valores abaixo.`process.result`enumResultado da verificação. Presente apenas quando `state = PROCESS_STATE_FINISHED`.`process.createdAt`string (datetime)Timestamp ISO 8601 de criação do processo.`process.finishedAt`string (datetime)Timestamp ISO 8601 de conclusão do processo. Presente apenas quando `state = PROCESS_STATE_FINISHED`.`process.expiresAt`string (datetime)Timestamp ISO 8601 de expiração do processo.`process.purpose`stringFinalidade do processo conforme configurada no fluxo.`process.​clientReference`stringReferência opcional do lado do cliente para indexação no portal.`process.useCase`stringIdentificador do cenário associado ao fluxo.`process.capacities`array de stringsLista de capacidades ativadas neste processo.`process.token`stringJWT assinado para integração via SDK.`process.person`objectIdentificação fornecida na criação.`process.​person.​notifications`arrayCanais de notificação configurados para a jornada (ex.: `email`).`process.​authenticationInfo`objectResultados por capacidade. Veja abaixo.`process.companyData`objectContexto de empresa e filial.`process.​companyData.​branchId`stringIdentificador da filial.`process.​companyData.​countryCode`stringCódigo de país ISO 3166-1 alpha-2.`process.​bioTokenData`objectInformações do processo de referência — presente apenas em fluxos de 1:1 Validation e Smart Revalidation.`process.services`arrayEnvelopes assinados, documentos capturados e outras saídas de serviço. Veja abaixo.Valores de process.stateValorSignificado`PROCESS_STATE_CREATED`Processo criado; o usuário ainda não concluiu a jornada.`AWAITING_FOR_DOCUMENT`Processo criado sem documento de identificação. Presente apenas quando o Custom Flow permite documento opcional. Envie o documento com [Definir Documento do Processo](/pt-BR/developers/api-reference/set-process-document).`PROCESS_STATE_FINISHED`Jornada concluída. Verifique `result` e `authenticationInfo`.`PROCESS_STATE_FAILED`Erro de processamento.Inconsistência de nomenclatura do estado`AWAITING_FOR_DOCUMENT` não segue a convenção de prefixo `PROCESS_STATE_*` usada pelos demais estados. Esta é uma inconsistência de nomenclatura conhecida na API atual.Valores de process.resultValorSignificado`PROCESS_RESULT_OK`Todas as capacidades retornaram resultados positivos.`PROCESS_RESULT_INVALID_IDENTITY`Pelo menos uma capacidade retornou um negativo definitivo (ex.: liveness falhou, identidade não correspondida).`PROCESS_RESULT_ERROR`Erro durante o processamento do resultado.`PROCESS_RESULT_EXPIRED`Processo expirou antes da conclusão da jornada.`PROCESS_RESULT_UNSPECIFIED`Processo ainda não finalizado.Resultados de capacidade em authenticationInfoTodos os campos são sempre retornados independentemente do fluxo. Campos de capacidades não usadas no fluxo retornam `*_UNSPECIFIED`.Valores de enum abreviadosValores 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.`livenessResult`[Prova de Vida](/pt-BR/capabilities/liveness)`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED``authenticationResult`[Verificação de Identidade](/pt-BR/capabilities/identity-verification)`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED``identityFraudstersResult`[Classificação de Risco de Fraude](/pt-BR/capabilities/fraud-risk-classification)`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED``bioTokenEngineResult`[Validação 1:1](/pt-BR/capabilities/1-1-validation)`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED``smartRevalidationResult`[Revalidação Inteligente](/pt-BR/capabilities/smart-revalidation)`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED``idAgeResult`[Verificação de Idade](/pt-BR/capabilities/age-verification)`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED``scoreEngineResult.​scoreEnabled`[Score de Risco](/pt-BR/capabilities/risk-score)`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED``scoreEngineResult.​score`[Score de Risco](/pt-BR/capabilities/risk-score)Número de -100 a +100. Presente quando `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` e o Score de Risco está habilitado.`serproResult.score`[Semelhança do Serpro](/pt-BR/capabilities/serpro-similarity-return)`0`–`100` (semelhança); `-1` (nenhuma face registrada para este CPF); `-2` (erro de integração).Campos de process.servicesConvenções de nomenclatura mistas em `services`O array `services` usa 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 são um erro de documentação.CampoTipoDescrição`envelopeId`string (UUID)Identificador do envelope assinado.`documentIds`array de stringsIDs dos documentos capturados neste serviço.`consent_granted`booleanSe o usuário concedeu consentimento de compartilhamento de dados.`documents`arrayDocumentos capturados com dados de OCR e resultados de validação.`documents[].doc_id`stringIdentificador do documento.`documents[].​typified`booleanSe o tipo de documento foi identificado com sucesso.`documents[].​cpf_match`booleanSe o CPF no documento corresponde ao CPF fornecido (somente Brasil).`documents[].​face_match`booleanSe a selfie corresponde à foto do documento.`documents[].​validate_doc`booleanSe o documento passou pela validação de autenticidade.`documents[].​reused_doc`booleanSe este documento foi reutilizado de um processo anterior.`documents[].​signed_url`stringURL pré-assinada para download do PDF do documento (válida por 5 minutos — busque novamente para renovar).`documents[].​doc.​version`integerVersão do schema de OCR.`documents[].​doc.​code`stringCódigo curto do tipo de documento (ex.: `CNH`). Veja [Tipos de documento e campos de OCR](#document-type-values) para todos os valores e como o código é derivado.`documents[].​doc.​data`objectCampos de OCR extraídos. O conteúdo varia por tipo de documento — veja a [referência completa de campos](/pt-BR/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json) para o catálogo completo. 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. ### Códigos de Erro​ 400 Bad Request401 Unauthorized404 Not Found429 Too Many Requests500 Internal Server ErrorCódigoMensagemDescrição`3`process id is invalidQuando o ID do processo é inválido.CódigoMensagemDescrição—Jwt header is an invalid JSONQuando o access token utilizado contém caracteres incorretos.—Jwt is expiredQuando o access token utilizado expirou.CódigoMensagemDescrição`5`error getting process: rpc error: code = NotFound desc = process not foundQuando o ID do processo não foi encontrado.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. avisoEnviar 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](/pt-BR/developers/start/rate-limits).CódigoMensagemDescrição`99999`Internal failure! Try again laterQuando ocorre um erro interno. ### 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](/pt-BR/developers/webhooks-and-events). ### Próximos passos​ Para a selfie capturada, veja [Obter Selfie](/pt-BR/developers/api-reference/get-selfie). Para o pacote de auditoria de evidências, veja [Obter Conjunto de Evidências](/pt-BR/developers/api-reference/get-evidence-set). Última atualização em 8 de out. de 2026**