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

Encabezados

Encabezado	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": "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 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 eventos del proceso.
`process.userRedirectUrl`	string	URL para redirigir al usuario después de completar el recorrido.
`process.state`	enum	Estado actual del proceso. Consulte los valores a continuación.
`process.result`	enum	Resultado de la verificación. Presente solo cuando `state = PROCESS_STATE_FINISHED`.
`process.createdAt`	string (datetime)	Marca de tiempo ISO 8601 de cuando se creó el proceso.
`process.finishedAt`	string (datetime)	Marca de tiempo ISO 8601 de cuando finalizó el proceso. Presente solo cuando `state = PROCESS_STATE_FINISHED`.
`process.expiresAt`	string (datetime)	Marca de tiempo ISO 8601 de cuando 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 of strings	Lista de capacidades activadas en este proceso.
`process.token`	string	JWT firmado para integración con SDK.
`process.person`	object	Identificación proporcionada en la creación.
`process.person.notifications`	array	Canales de notificación configurados para el recorrido (por ejemplo, `email`).
`process.authenticationInfo`	object	Resultados por capacidad. Consulte a continuación.
`process.companyData`	object	Contexto de empresa y sucursal.
`process.companyData.branchId`	string	Identificador de sucursal.
`process.companyData.countryCode`	string	Código de país ISO 3166-1 alfa-2.
`process.bioTokenData`	object	Información del proceso de referencia, presente solo en flujos de Validación 1:1 y Revalidación Inteligente.
`process.services`	array	Sobres firmados, documentos capturados y otras salidas de servicio. Consulte a continuación.

Valores de process.state

Valor	Significado
`PROCESS_STATE_CREATED`	Proceso creado; el usuario aún no ha completado el recorrido.
`AWAITING_FOR_DOCUMENT`	Proceso creado sin documento de identificación; esperando que se establezca mediante Establecer documento del proceso. Solo presente cuando el flujo personalizado permite documento opcional.
`PROCESS_STATE_FINISHED`	Recorrido completado. Verifique `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 de nomenclatura 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 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 completar el recorrido.
`PROCESS_RESULT_UNSPECIFIED`	Proceso aún no 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 (por ejemplo, livenessResult = LIVE, authenticationResult = INCONCLUSIVE) se mapean directamente a 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 Score de Riesgo está habilitado.
`serproResult.score`	Retorno de Similitud Serpro	`0`-`100` (similitud); `-1` (sin rostro en archivo para este CPF); `-2` (error de integración).

Campos de process.services

Convenciones de nomenclatura mixtas en services

El array services utiliza camelCase para los campos a nivel de sobre (envelopeId, documentIds) y snake_case para los campos a nivel de documento (doc_id, consent_granted, face_match, etc.). Esto refleja la respuesta real de la API — ambas convenciones son intencionales y no constituyen un error de documentación.

Campo	Tipo	Descripción
`envelopeId`	string (UUID)	Identificador del sobre firmado.
`documentIds`	array of strings	IDs de 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 exitosamente.
`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; vuelva a consultar 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. Los nombres de campo dentro de `doc.data` (por ejemplo, `nomeCivil`, `dataNascimento`) se devuelven en portugués — estos son los valores reales producidos por el motor OCR.

400 Bad Request

El parámetro de ruta processId falta o está malformado.

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. Cuando su sistema recibe un error HTTP 429, debe implementar mecanismos para prevenir fallos en cascada y evitar empeorar la restricción.

Mejores prácticas:

Período de espera (backoff): Detenga o limite inmediatamente las solicitudes subsecuentes de su sistema. No reintente continuamente solicitudes fallidas en un bucle cerrado.
Cola y limitación: Almacene en buffer o encole las solicitudes salientes de su lado para controlar el flujo de tráfico antes de reenviarlas.
Backoff exponencial con jitter: Al reintentar, aumente el tiempo de espera exponencialmente entre intentos (por ejemplo, 1 s, 2 s, 4 s, 8 s) y agregue un pequeño retraso aleatorio ("jitter") para prevenir un efecto manada donde todas las solicitudes en cola reintentan en el mismo milisegundo.

advertencia

Golpear continuamente un endpoint con límite de tasa sin aplicar backoff puede prolongar el período de restricción e impactar severamente el rendimiento operativo de su sistema. Limitar adecuadamente las solicitudes de su lado asegura una integración más fluida y resiliente.

Para límites predeterminados, solicitudes de aumento y detalles adicionales, consulte Límites de tasa.

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.

Código	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 hay 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 solo llamar a este endpoint como respaldo. Consulte Webhooks y eventos.

Qué sigue

Para el selfie capturado, consulte Get Selfie.
Para el paquete de evidencia de auditoría, consulte Get Evidence Set.

Endpoint​

Solicitud​

Ejemplo​

Respuestas​

Códigos de error​

Polling vs webhook​

Qué sigue​