Recupera un proceso existente por su identificador. Según el contrato de la API, el resultado ya se devuelve de forma sincrónica al crear el proceso; usa este endpoint para reconsultas, auditoría y soporte.
Antes de recuperar el proceso, revisa nuestra configuración de webhooks 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
| Header | Valor |
|---|---|
Authorization | Bearer <access_token> |
| Parámetro | Tipo | Obligatorio | 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
{
"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
}
}
| Campo | Significado |
|---|---|
id | UUID del proceso; la clave utilizada para consultar y rastrear el flow. |
flow | Tipo de recorrido ejecutado (ej.: id_r2, idlivetrust_r2, idtrust_r2, ...). |
callbackUri | URI de callback a la que se redirige la aplicación cliente al final del flow. |
userRedirectUrl | URL completa de la página del CbU que el usuario abre para realizar el recorrido (contiene el id y flags de comportamiento). |
state | Estado del ciclo de vida del proceso (ej.: PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED). |
result | Veredicto final de la evaluación. Valores PROCESS_RESULT_* (ej.: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Solo es concluyente cuando state = PROCESS_STATE_FINISHED. |
createdAt | Marca de tiempo de creación del proceso (UTC). |
finishedAt | Marca de tiempo de finalización del proceso (UTC). |
person | Subobjeto con los datos de la persona verificada. |
purpose | Propósito del proceso (ej.: personAuthentication, registro de persona). |
services | Lista de servicios adicionales adjuntos al proceso; vacía cuando no hay ninguno. |
authenticationInfo.authenticationId | ID del evento de autenticación de identidad generado por el flow. |
capacities | Capacidades/productos utilizados. Valores PROCESS_CAPACITY_* (ej.: IDCLOUDONE). |
expiresAt | Marca de tiempo de expiración del proceso/enlace (UTC). |
token | Token de sesión/acceso asociado al proceso (puede estar vacío). |
companyData | Subobjeto con los datos de la empresa/tenant propietaria del proceso. |
simulated | Booleano; indica si se trata de un proceso de simulación/sandbox (true) o uno real (false). |
| Campo | Significado |
|---|---|
duiType | Tipo del documento único de identificación. Valores DUI_TYPE_* (ej.: BR_CPF). |
duiValue | Valor del documento (ej.: el número de CPF). |
friendlyName | Nombre amigable/apodo de la persona (texto libre, no validado). |
email | Correo electrónico de la persona; puede estar vacío. |
phone | Número de teléfono en formato E.164 (código de país + código de área + número). |
notifications | Lista de canales de notificación. Cada elemento contiene notificationChannel con valores NOTIFICATION_CHANNEL_* (ej.: WHATSAPP, SMS, EMAIL). |
phoneCountryCodeAlpha3 | Código de país ISO alfa-3 del número de teléfono (ej.: BRA); puede estar vacío. |
| Campo | Significado |
|---|---|
branchId | Identificador de la sucursal del tenant; vacío cuando no se segmenta por sucursal. |
countryCode | País de la empresa en ISO alfa-3 (ej.: BRA). |
process.services[].documents[].doc.code reporta el tipo de documento en una de dos formas. Los documentos procesados por el módulo de documentos de Unico, incluidos los documentos reutilizados, traen un código corto en mayúsculas (CNH). Los procesos creados solo por API suelen traer el tipo de diccionario completo (unico.moja.dictionary.br.cnh.v2.Cnh), pero también pueden traer un código corto. Maneja ambas formas en cualquier vía de integración.
El código corto no contiene ni el país ni la versión del esquema; la versión se devuelve por separado en doc.version.
En la forma corta, los tipos de documento que usan el esquema unificado — unified_schema en la referencia de campos — se reportan como el identificador de tipo en mayúsculas detectado durante la captura. Los valores más comunes son IDCARD, DRIVERLICENSE, PASSPORT y VOTERID, pero la lista es abierta: otros tipos identificados durante la captura se devuelven tal cual, en mayúsculas. Maneja valores fuera de esta lista.
Los pasaportes de EE. UU. mantienen su variante en lugar de colapsar a PASSPORT: también se devuelven POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT y REFUGEEPASSPORT.
Por ejemplo, unico.moja.dictionary.ar.generic.v1.IdCard y unico.moja.dictionary.us.generic.v1.PolycarbonatePassport se reportan como IDCARD y POLYCARBONATEPASSPORT.
Los tipos de documento que usan su propio esquema de campos — listados en specific_document_schemas en la referencia de campos — se muestran en la tabla siguiente. Usa el tipo de diccionario para buscar cada esquema en ese archivo.
| País | doc.code | Tipo de diccionario | Documento |
|---|---|---|---|
| BR | RG | unico.moja.dictionary.br.rg.v2.Rg | RG |
| BR | CNH | unico.moja.dictionary.br.cnh.v2.Cnh | CNH (licencia de conducir) |
| BR | CIN | unico.moja.dictionary.br.cin.v1.Cin | CIN |
| BR | PASSAPORTE | unico.moja.dictionary.br.passaporte.v1.Passaporte | Pasaporte |
| MX | INE | unico.moja.dictionary.mx.ine.v1.Ine | Credencial de elector INE |
| MX | LPC | unico.moja.dictionary.mx.lpc.v1.Lpc | Licencia para conducir |
| MX | PASAPORTE | unico.moja.dictionary.mx.pasaporte.v1.Pasaporte | Pasaporte |
| — | UNKNOWN | unico.moja.dictionary.other.unknown.v1.Unknown | No se pudo identificar el tipo, o es un tipo brasileño o mexicano sin esquema propio — doc.data está vacío |
Los documentos brasileños y mexicanos usan solo los esquemas específicos anteriores. Un documento brasileño o mexicano de cualquier otro tipo — por ejemplo, una tarjeta de residente mexicana — se reporta como UNKNOWN, no con el esquema unificado.
PASSAPORTE y PASAPORTE son documentos diferentesEl pasaporte brasileño es PASSAPORTE (doble S) y el mexicano es PASAPORTE (una sola S), cada uno reflejando la ortografía de su propio diccionario. Esto no es un error de tipeo — no trates ambos valores como equivalentes.
No se realiza extracción por OCR ni se reporta ningún campo en doc.data cuando doc.code es UNKNOWN.
Los clientes en Brasil pueden recibir el payload completo del procesoLa estructura general de la respuesta se mantiene igual — el resultado único es el valor predeterminado.

La estructura general de la respuesta se mantiene igual — el resultado único es el valor predeterminado.
Las integraciones en Brasil pueden recibir el objeto de proceso completo a continuación, con resultados por capacidad en 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"
}
}
}
]
}
]
}
}
| Campo | Tipo | Descripción |
|---|---|---|
process.id | string (UUID) | Identificador del proceso. |
process.flow | string | Identificador del flow 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 después de completar el recorrido. |
process.state | enum | Estado actual del proceso. Ver valores más abajo. |
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 creación del proceso. |
process.finishedAt | string (datetime) | Marca de tiempo ISO 8601 de finalización del proceso. Presente solo cuando state = PROCESS_STATE_FINISHED. |
process.expiresAt | string (datetime) | Marca de tiempo ISO 8601 de expiración del proceso. |
process.purpose | string | Propósito del proceso según lo configurado en el flow. |
process.clientReference | string | Referencia opcional del lado del cliente para indexación en el portal. |
process.useCase | string | Identificador del escenario asociado al flow. |
process.capacities | array of strings | Lista de capacidades activadas en este proceso. |
process.token | string | JWT firmado para la integración del SDK. |
process.person | object | Identificación proporcionada en la creación. |
process.person.notifications | array | Canales de notificación configurados para el recorrido (ej.: email). |
process.authenticationInfo | object | Resultados por capacidad. Ver más abajo. |
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 alfa-3 (ej.: BRA). |
process.bioTokenData | object | Información del proceso de referencia — presente solo en flows de 1:1 Validation y Smart Revalidation. |
process.services | array | Envelopes firmados, documentos capturados y otros resultados de servicio. Ver más abajo. |
| Valor | Significado |
|---|---|
PROCESS_STATE_CREATED | Proceso creado; el usuario aún no completó el recorrido. |
PROCESS_STATE_AWAITING_FOR_DOCUMENT | Proceso creado sin documento de identificación. Presente solo cuando el Custom Flow permite documento opcional. Envía el documento con Definir Documento del Proceso. |
PROCESS_STATE_FINISHED | Recorrido completado. Verifica result y authenticationInfo. |
PROCESS_STATE_FAILED | Error de procesamiento. |
| Valor | Significado |
|---|---|
PROCESS_RESULT_OK | Todas las capacidades devolvieron resultados positivos. |
PROCESS_RESULT_INVALID_IDENTITY | Al menos una capacidad devolvió un negativo definitivo (ej.: liveness 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 | El proceso aún no ha finalizado. |
Todos los campos se devuelven siempre, sin importar el flow. Los campos de capacidades no usadas en el flow devuelven *_UNSPECIFIED.
Los valores abreviados (ej.: livenessResult = LIVE, authenticationResult = INCONCLUSIVE) se corresponden directamente con los valores completos de enum documentados aquí (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — el prefijo se omite por brevedad.
| Campo | Capacidad | Valores posibles |
|---|---|---|
authenticationId | — | Identificador único de este intento de autenticación. |
livenessResult | Liveness | LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED |
authenticationResult | Identity Verification | AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED |
identityFraudstersResult | Fraud Risk Classification | TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED |
bioTokenEngineResult | 1:1 Validation | BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED |
smartRevalidationResult | Smart Revalidation | SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED |
idAgeResult | Age Verification | ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED |
scoreEngineResult.scoreEnabled | Risk Score | SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED |
scoreEngineResult.score | Risk Score | Número de -100 a +100. Presente cuando authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE y Risk Score está habilitado. |
serproResult.score | Similitud Serpro | 0–100 (similitud); -1 (no hay rostro registrado para este CPF); -2 (error de integración). |
deviceMetadata | Metadatos del Dispositivo | Objeto con status (found, not_found, unavailable) y los datos del dispositivo. Ausente cuando la capacidad no está habilitada en el flujo. |
services contiene un elemento por cada módulo que finalizó en el proceso: la ejecución finalizada más reciente de cada módulo, y solo mientras el proceso está en PROCESS_STATE_FINISHED o PROCESS_STATE_AWAITING_FOR_DOCUMENT. Los procesos creados solo por API traen su elemento de documento en cualquier estado. Un elemento de captura de documentos incluye documents y consent_granted. Un elemento de firma electrónica incluye envelope_id y document_ids. Los elementos no tienen campo de tipo y su orden no es estable: identifica cada uno por sus claves, no por su posición, e ignora los elementos que no reconozcas. Las claves están en snake_case, excepto las de doc.data, que siguen el esquema del documento (ej.: nomeCivil).
| Campo | Tipo | Descripción |
|---|---|---|
consent_granted | boolean | Elemento de captura de documentos. Indica si el usuario otorgó el consentimiento para compartir los documentos con tu empresa. |
documents | array | Elemento de captura de documentos. Documentos capturados con datos de OCR y resultados de validación. |
documents[].doc_id | string | Identificador del documento. |
documents[].share_id | string | Identificador del permiso de compartición que el usuario otorgó a tu empresa para este proceso. |
documents[].typified | boolean | Indica si se identificó el tipo de documento. |
documents[].cpf_match | boolean | Solo Brasil. Indica si el CPF del documento coincide con el CPF enviado en la creación. Siempre presente para empresas cuyo país está definido como Brasil; se omite para otros países y para empresas sin país definido. |
documents[].validate_doc | boolean | Solo Brasil. Indica si el documento pasó la validación de documentos de Unico. Siempre presente para empresas cuyo país está definido como Brasil (false cuando la validación no se ejecutó); se omite para otros países y para empresas sin país definido. |
documents[].face_match | boolean or null | Indica si la selfie coincide con la foto del documento. null significa que la verificación no se ejecutó — no es un resultado negativo. |
documents[].verified | boolean or null | true solo cuando el tipo de documento es conocido, el documento no fue eliminado, face_match es true y el documento pasó las verificaciones de calidad. false en caso contrario, incluso cuando face_match no se ejecutó. null cuando el proceso no pasó por el módulo de documentos. |
documents[].reused_doc | boolean | Indica si este documento se reutilizó de un proceso anterior. |
documents[].signed_url | string | URL firmada de corta duración para descargar la imagen del documento. Expira: no la almacenes ni dependas de una duración fija, y vuelve a llamar a este endpoint para obtener una nueva. |
documents[].doc.version | integer | Versión del diccionario del tipo de documento (ej.: 2 para unico.moja.dictionary.br.cnh.v2.Cnh). |
documents[].doc.code | string | Tipo de documento, como código corto (ej.: CNH) o como el tipo de diccionario completo (ej.: unico.moja.dictionary.br.cnh.v2.Cnh). Los documentos procesados por el módulo de documentos traen el código corto. Maneja ambos. Ver Tipos de documento y campos de OCR para todos los valores y cómo se deriva el código. |
documents[].doc.data | object | Campos de OCR extraídos. El contenido varía según el tipo de documento — ver la referencia de campos completa para el catálogo completo. Los nombres de campo siguen el esquema del documento: portugués para documentos brasileños (ej.: nomeCivil, dataNascimento), español para documentos mexicanos e inglés para el esquema unificado. |
envelope_id | string (UUID) | Elemento de firma electrónica. Identificador del sobre firmado. |
document_ids | array of strings | Elemento de firma electrónica. IDs de los documentos del sobre. |
En un proceso creado solo por API, el elemento de documento proviene de la llamada a la API, no del módulo de documentos de Unico, y algunos valores difieren de la tabla anterior:
consent_grantedsiempre esfalse: tu empresa recoge el consentimiento y Unico no lo registra.share_idysigned_urlestán vacíos.face_matchsiempre estrueofalse, nuncanull.verifiedsiempre esnull.doc.versiones0.doc.codesuele traer el tipo de diccionario completo (ej.:unico.moja.dictionary.br.cnh.v2.Cnh), pero puede traer un código corto.doc.dataesnullcuando no se pudieron leer los datos de OCR.
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 no es válido. |
| Código | Mensaje | Descripción |
|---|---|---|
| — | Jwt header is an invalid JSON | Cuando el access token utilizado contiene caracteres incorrectos. |
| — | Jwt is expired | Cuando el access token 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. |
Se alcanzó el límite de tasa. 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 enfriamiento (backoff): Detenga o reduzca inmediatamente las solicitudes posteriores de su sistema. No reintente continuamente las solicitudes fallidas en un bucle cerrado.
- Cola y limitación (Queueing & throttling): Almacene en búfer o ponga en cola 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 evitar un efecto de manada donde todas las solicitudes en cola reintentan en el mismo milisegundo exacto.
Enviar solicitudes continuamente a un endpoint con límite de tasa sin aplicar backoff puede prolongar el período de restricción e impactar gravemente el rendimiento operativo de su sistema. Limitar adecuadamente las solicitudes de su lado garantiza una integración más fluida y resiliente.
Para conocer los límites predeterminados, aumentar solicitudes y obtener detalles adicionales, consulte Límites de tasa.
| Código | Mensaje | Descripción |
|---|---|---|
99999 | Internal failure! Try again later | Cuando ocurre un error interno. |
Polling vs. webhook
Puedes hacer polling de este endpoint para verificar el progreso, pero el patrón recomendado es suscribirte a un webhook y usar este endpoint solo como fallback. Ver Webhooks and Events.
Qué sigue
- Para la selfie capturada, ver Get Selfie.
- Para el paquete de evidencias de auditoría, ver Get Evidence Set.