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 path

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": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "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 de strings	Lista de capacidades ativadas neste processo.
`process.token`	string	JWT assinado para integração com o 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 de 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 concluiu a jornada.
`AWAITING_FOR_DOCUMENT`	Processo criado sem documento de identificação; aguardando que ele 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 na nomenclatura de estados

AWAITING_FOR_DOCUMENT não segue a convenção de prefixo PROCESS_STATE_* utilizada pelos demais estados. Trata-se de 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`	Ao menos uma capacidade retornou resultado negativo definitivo (ex.: liveness reprovado, identidade não correspondida).
`PROCESS_RESULT_ERROR`	Erro durante o processamento do resultado.
`PROCESS_RESULT_EXPIRED`	Processo expirou antes de a jornada ser concluída.
`PROCESS_RESULT_UNSPECIFIED`	Processo ainda não finalizado.

Resultados de capacidade em authenticationInfo

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

Valores de enum abreviados

Os valores abreviados (ex.: livenessResult = LIVE, authenticationResult = INCONCLUSIVE) correspondem diretamente aos valores completos documentados aqui (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — o prefixo é omitido por brevidade.

Campo	Capacidade	Valores possíveis
`authenticationId`	—	Identificador único desta 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 a Classificação de risco de fraude está habilitada.
`serproResult.score`	Retorno de Semelhança do Serpro	`0`–`100` (similaridade); `-1` (sem foto cadastrada para este CPF); `-2` (erro de integração).

Campos de process.services

Campo	Tipo	Descrição
`envelopeId`	string (UUID)	Identificador do envelope assinado.
`documentIds`	array de strings	IDs dos documentos capturados neste serviço.
`consent_granted`	boolean	Se o usuário concedeu consentimento para 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 reaproveitado de um processo anterior.
`documents[].signed_url`	string	URL pré-assinada para download do PDF do documento (válida por 5 minutos — busque novamente 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 extraídos por OCR. O conteúdo varia por tipo de documento e dados disponíveis.

400 Bad Request

O parâmetro de path 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

Rate limit atingido.

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.

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 está expirado.

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 fazer polling neste endpoint para verificar o andamento, mas o padrão recomendado é assinar um webhook e chamar este endpoint apenas como fallback. Consulte 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​