Obtener Proceso

advertencia

Antes de recuperar el proceso, revisa la configuración de nuestro webhook y las estrategias de fallback — haz clic aquí.

Endpoint

Entorno	URL
Producción	`GET https://api.idcloud.unico.app/client/v1/process/{processId}`
Sandbox	`GET https://api.idcloud.uat.unico.app/client/v1/process/{processId}`

Solicitud

Cabeceras

Cabecera	Valor
`Authorization`	`Bearer <access_token>`

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`processId`	string (UUID)	sí	Identificador del proceso devuelto por Crear Proceso.

Ejemplo

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();

Respuestas

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 nivel superior

Campo	Tipo	Descripción
`process.id`	string (UUID)	Identificador del proceso.
`process.flow`	string	Identificador del flujo enviado en la creación.
`process.callbackUri`	string	URL de callback configurada para los eventos del proceso.
`process.userRedirectUrl`	string	URL para redirigir al usuario una vez completada la jornada.
`process.state`	enum	Estado actual del proceso. Ver valores a continuación.
`process.result`	enum	Resultado de la verificación. Presente solo cuando `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	Timestamp ISO 8601 de cuándo se creó el proceso.
`process.finishedAt`	string (datetime)	Timestamp ISO 8601 de cuándo finalizó el proceso. Presente solo cuando `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	Timestamp ISO 8601 de cuándo expira el proceso.
`process.purpose`	string	Propósito del proceso según lo configurado en el flujo.
`process.clientReference`	string	Referencia opcional del lado del cliente para indexación en el portal.
`process.useCase`	string	Identificador del caso de uso asociado al flujo.
`process.capacities`	array de strings	Lista de capacidades activadas en este proceso.
`process.token`	string	JWT firmado para integración con el SDK.
`process.person`	object	Identificación proporcionada en la creación.
`process.person.notifications`	array	Canales de notificación configurados para la jornada (por ejemplo, `email`).
`process.authenticationInfo`	object	Resultados por capacidad. Ver a continuación.
`process.companyData`	object	Contexto de empresa y sucursal.
`process.companyData.branchId`	string	Identificador de la sucursal.
`process.companyData.countryCode`	string	Código de país ISO 3166-1 alpha-2.
`process.bioTokenData`	object	Información del proceso de referencia — presente solo en flujos de validación 1:1 y Smart Revalidation.
`process.services`	array	Sobres firmados, documentos capturados y otras salidas del servicio. Ver a continuación.

Valores de process.state

Valor	Significado
`PROCESS_STATE_CREATED`	Proceso creado; el usuario aún no ha completado la jornada.
`AWAITING_FOR_DOCUMENT`	Proceso creado sin documento de identificación; esperando que se establezca mediante Establecer Documento del Proceso. Solo presente cuando el Custom Flow permite documento opcional.
`PROCESS_STATE_FINISHED`	Jornada completada. Verificar `result` y `authenticationInfo`.
`PROCESS_STATE_FAILED`	Error de procesamiento.

Inconsistencia en el nombre del estado

AWAITING_FOR_DOCUMENT no sigue la convención de prefijo PROCESS_STATE_* utilizada por los demás estados. Esta es una inconsistencia conocida en la API actual.

Valores de process.result

Valor	Significado
`PROCESS_RESULT_OK`	Todas las capacidades devolvieron resultados positivos.
`PROCESS_RESULT_INVALID_IDENTITY`	Al menos una capacidad devolvió un resultado negativo definitivo (por ejemplo, detección de vida fallida, identidad no coincidente).
`PROCESS_RESULT_ERROR`	Error durante el procesamiento del resultado.
`PROCESS_RESULT_EXPIRED`	El proceso expiró antes de que se completara la jornada.
`PROCESS_RESULT_UNSPECIFIED`	El proceso aún no ha finalizado.

Resultados de capacidades en authenticationInfo

Todos los campos se devuelven siempre independientemente del flujo. Los campos para capacidades no utilizadas en el flujo devuelven *_UNSPECIFIED.

Valores de enum abreviados

Los valores abreviados (p. ej. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) se corresponden directamente con los valores de enum completos documentados aquí (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — el prefijo se omite por brevedad.

Campo	Capacidad	Valores posibles
`authenticationId`	—	Identificador único para este intento de autenticación.
`livenessResult`	Detección de Vida	`LIVENESS_RESULT_LIVE`, `LIVENESS_RESULT_NOT_LIVE`, `LIVENESS_RESULT_UNSPECIFIED`
`authenticationResult`	Verificación de Identidad	`AUTHENTICATION_RESULT_POSITIVE`, `AUTHENTICATION_RESULT_NEGATIVE`, `AUTHENTICATION_RESULT_INCONCLUSIVE`, `AUTHENTICATION_RESULT_UNSPECIFIED`
`identityFraudstersResult`	Clasificación de riesgo de fraude	`TRUST_RESULT_YES`, `TRUST_RESULT_INCONCLUSIVE`, `TRUST_RESULT_UNSPECIFIED`
`bioTokenEngineResult`	Validación 1:1	`BIO_TOKEN_ENGINE_RESULT_POSITIVE`, `BIO_TOKEN_ENGINE_RESULT_NEGATIVE`, `BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED`
`smartRevalidationResult`	Revalidación Inteligente	`SMART_REVALIDATION_RESULT_POSITIVE`, `SMART_REVALIDATION_RESULT_NEGATIVE`, `SMART_REVALIDATION_RESULT_UNSPECIFIED`
`idAgeResult`	Verificación de Edad	`ID_AGE_RESULT_POSITIVE`, `ID_AGE_RESULT_NEGATIVE`, `ID_AGE_RESULT_INCONCLUSIVE`, `ID_AGE_RESULT_UNSPECIFIED`
`scoreEngineResult.scoreEnabled`	Score de Riesgo	`SCORE_ENABLED_TRUE`, `SCORE_ENABLED_FALSE`, `SCORE_ENABLED_UNSPECIFIED`
`scoreEngineResult.score`	Score de Riesgo	Número de -100 a +100. Presente cuando `authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE` y la Clasificación de riesgo de fraude está habilitada.
`serproResult.score`	Retorno de Similitud Serpro	`0`–`100` (similitud); `-1` (sin rostro en el archivo para este CPF); `-2` (error de integración).

Campos de process.services

Campo	Tipo	Descripción
`envelopeId`	string (UUID)	Identificador del sobre firmado.
`documentIds`	array de strings	IDs de los documentos capturados en este servicio.
`consent_granted`	boolean	Si el usuario otorgó consentimiento para compartir datos.
`documents`	array	Documentos capturados con datos OCR y resultados de validación.
`documents[].doc_id`	string	Identificador del documento.
`documents[].typified`	boolean	Si el tipo de documento fue identificado correctamente.
`documents[].cpf_match`	boolean	Si el CPF del documento coincide con el CPF proporcionado.
`documents[].face_match`	boolean	Si el selfie coincide con la foto del documento.
`documents[].validate_doc`	boolean	Si el documento pasó la validación de autenticidad.
`documents[].reused_doc`	boolean	Si este documento fue reutilizado de un proceso anterior.
`documents[].signed_url`	string	URL pre-firmada para descargar el PDF del documento (válida por 5 minutos — volver a solicitar para renovar).
`documents[].doc.version`	integer	Versión del esquema OCR.
`documents[].doc.code`	string	Código del tipo de documento (por ejemplo, `CNH`, `RG`).
`documents[].doc.data`	object	Campos OCR extraídos. El contenido varía según el tipo de documento y los datos disponibles.

400 Bad Request

El parámetro de ruta processId está ausente o tiene un formato incorrecto.

401 Unauthorized

Token Bearer ausente, expirado o inválido.

404 Not Found

El processId no existe o no pertenece al tenant autenticado.

429 Too Many Requests

Límite de tasa alcanzado.

Códigos de Error

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

Código	Mensaje	Descripción
`3`	process id is invalid	Cuando el ID del proceso es inválido.

Mensaje	Descripción
Jwt header is an invalid JSON	Cuando el token de acceso utilizado contiene caracteres incorrectos.
Jwt is expired	Cuando el token de acceso utilizado ha expirado.

Código	Mensaje	Descripción
`5`	error getting process: rpc error: code = NotFound desc = process not found	Cuando no se encontró el ID del proceso.

Código	Mensaje	Descripción
`99999`	Internal failure! Try again later	Cuando se produce un error interno.

Polling vs webhook

Puede consultar este endpoint para verificar el progreso, pero el patrón recomendado es suscribirse a un webhook y llamar a este endpoint solo como alternativa. Ver Webhooks y Eventos.

Próximos pasos

Para el selfie capturado, consulta Obtener Selfie.
Para el paquete de auditoría de evidencias, consulta Obtener Conjunto de Evidencias.

Endpoint​

Solicitud​

Ejemplo​

Respuestas​

Códigos de Error​

Polling vs webhook​

Próximos pasos​