Saltar al contenido principal
Obtener ProcesoGET

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.

Markdown
advertencia

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

Endpoint​

EntornoURL
ProducciónGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Solicitud​

Headers
HeaderValor
AuthorizationBearer <access_token>
Parámetros de ruta
ParámetroTipoObligatorioDescripción
processIdstring (UUID)síIdentificador del proceso devuelto por Crear Proceso.

Ejemplo​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"

Respuestas​

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 del proceso
CampoSignificado
idUUID del proceso; la clave utilizada para consultar y rastrear el flow.
flowTipo de recorrido ejecutado (ej.: id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriURI de callback a la que se redirige la aplicación cliente al final del flow.
userRedirectUrlURL completa de la página del CbU que el usuario abre para realizar el recorrido (contiene el id y flags de comportamiento).
stateEstado del ciclo de vida del proceso (ej.: PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED).
resultVeredicto final de la evaluación. Valores PROCESS_RESULT_* (ej.: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Solo es concluyente cuando state = PROCESS_STATE_FINISHED.
createdAtMarca de tiempo de creación del proceso (UTC).
finishedAtMarca de tiempo de finalización del proceso (UTC).
personSubobjeto con los datos de la persona verificada.
purposePropósito del proceso (ej.: personAuthentication, registro de persona).
servicesLista de servicios adicionales adjuntos al proceso; vacía cuando no hay ninguno.
authenticationInfo.​authenticationIdID del evento de autenticación de identidad generado por el flow.
capacitiesCapacidades/productos utilizados. Valores PROCESS_CAPACITY_* (ej.: IDCLOUDONE).
expiresAtMarca de tiempo de expiración del proceso/enlace (UTC).
tokenToken de sesión/acceso asociado al proceso (puede estar vacío).
companyDataSubobjeto con los datos de la empresa/tenant propietaria del proceso.
simulatedBooleano; indica si se trata de un proceso de simulación/sandbox (true) o uno real (false).
Campos de person
CampoSignificado
duiTypeTipo del documento único de identificación. Valores DUI_TYPE_* (ej.: BR_CPF).
duiValueValor del documento (ej.: el número de CPF).
friendlyNameNombre amigable/apodo de la persona (texto libre, no validado).
emailCorreo electrónico de la persona; puede estar vacío.
phoneNúmero de teléfono en formato E.164 (código de país + código de área + número).
notificationsLista de canales de notificación. Cada elemento contiene notificationChannel con valores NOTIFICATION_CHANNEL_* (ej.: WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3Código de país ISO alfa-3 del número de teléfono (ej.: BRA); puede estar vacío.
Campos de companyData
CampoSignificado
branchIdIdentificador de la sucursal del tenant; vacío cuando no se segmenta por sucursal.
countryCodePaís de la empresa en ISO alfa-3 (ej.: BRA).
Tipos de documento y campos de OCR

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.

Esquemas específicos

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ísdoc.codeTipo de diccionarioDocumento
BRRGunico.​moja.​dictionary.​br.​rg.​v2.​RgRG
BRCNHunico.​moja.​dictionary.​br.​cnh.​v2.​CnhCNH (licencia de conducir)
BRCINunico.​moja.​dictionary.​br.​cin.​v1.​CinCIN
BRPASSAPORTEunico.​moja.​dictionary.​br.​passaporte.​v1.​PassaportePasaporte
MXINEunico.​moja.​dictionary.​mx.​ine.​v1.​IneCredencial de elector INE
MXLPCunico.​moja.​dictionary.​mx.​lpc.​v1.​LpcLicencia para conducir
MXPASAPORTEunico.​moja.​dictionary.​mx.​pasaporte.​v1.​PasaportePasaporte
—UNKNOWNunico.​moja.​dictionary.​other.​unknown.​v1.​UnknownNo 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 diferentes

El 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.

BrazilLos clientes en Brasil pueden recibir el payload completo del proceso

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"
}
}
}
]
}
]
}
}
Campos de nivel superior
CampoTipoDescripción
process.idstring (UUID)Identificador del proceso.
process.flowstringIdentificador del flow enviado en la creación.
process.callbackUristringURL de callback configurada para los eventos del proceso.
process.​userRedirectUrlstringURL para redirigir al usuario después de completar el recorrido.
process.stateenumEstado actual del proceso. Ver valores más abajo.
process.resultenumResultado de la verificación. Presente solo cuando state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)Marca de tiempo ISO 8601 de creación del proceso.
process.finishedAtstring (datetime)Marca de tiempo ISO 8601 de finalización del proceso. Presente solo cuando state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)Marca de tiempo ISO 8601 de expiración del proceso.
process.purposestringPropósito del proceso según lo configurado en el flow.
process.​clientReferencestringReferencia opcional del lado del cliente para indexación en el portal.
process.useCasestringIdentificador del escenario asociado al flow.
process.capacitiesarray of stringsLista de capacidades activadas en este proceso.
process.tokenstringJWT firmado para la integración del SDK.
process.personobjectIdentificación proporcionada en la creación.
process.​person.​notificationsarrayCanales de notificación configurados para el recorrido (ej.: email).
process.​authenticationInfoobjectResultados por capacidad. Ver más abajo.
process.companyDataobjectContexto de empresa y sucursal.
process.​companyData.​branchIdstringIdentificador de la sucursal.
process.​companyData.​countryCodestringCódigo de país ISO 3166-1 alfa-3 (ej.: BRA).
process.​bioTokenDataobjectInformación del proceso de referencia — presente solo en flows de 1:1 Validation y Smart Revalidation.
process.servicesarrayEnvelopes firmados, documentos capturados y otros resultados de servicio. Ver más abajo.
Valores de process.state
ValorSignificado
PROCESS_STATE_CREATEDProceso creado; el usuario aún no completó el recorrido.
PROCESS_STATE_AWAITING_FOR_DOCUMENTProceso 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_FINISHEDRecorrido completado. Verifica result y authenticationInfo.
PROCESS_STATE_FAILEDError de procesamiento.
Valores de process.result
ValorSignificado
PROCESS_RESULT_OKTodas las capacidades devolvieron resultados positivos.
PROCESS_RESULT_INVALID_IDENTITYAl menos una capacidad devolvió un negativo definitivo (ej.: liveness fallida, identidad no coincidente).
PROCESS_RESULT_ERRORError durante el procesamiento del resultado.
PROCESS_RESULT_EXPIREDEl proceso expiró antes de completar el recorrido.
PROCESS_RESULT_UNSPECIFIEDEl proceso aún no ha finalizado.
Resultados por capacidad en authenticationInfo

Todos los campos se devuelven siempre, sin importar el flow. Los campos de capacidades no usadas en el flow devuelven *_UNSPECIFIED.

Valores de enum abreviados

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.

CampoCapacidadValores posibles
authenticationId—Identificador único de este intento de autenticación.
livenessResultLivenessLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultIdentity VerificationAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultFraud Risk ClassificationTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1 ValidationBIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultSmart RevalidationSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultAge VerificationID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.​scoreEnabledRisk ScoreSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.​scoreRisk ScoreNúmero de -100 a +100. Presente cuando authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE y Risk Score está habilitado.
serproResult.scoreSimilitud Serpro0–100 (similitud); -1 (no hay rostro registrado para este CPF); -2 (error de integración).
deviceMetadataMetadatos del DispositivoObjeto con status (found, not_found, unavailable) y los datos del dispositivo. Ausente cuando la capacidad no está habilitada en el flujo.
Campos de process.services
Un elemento por módulo

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).

CampoTipoDescripción
consent_grantedbooleanElemento de captura de documentos. Indica si el usuario otorgó el consentimiento para compartir los documentos con tu empresa.
documentsarrayElemento de captura de documentos. Documentos capturados con datos de OCR y resultados de validación.
documents[].doc_idstringIdentificador del documento.
documents[].​share_idstringIdentificador del permiso de compartición que el usuario otorgó a tu empresa para este proceso.
documents[].​typifiedbooleanIndica si se identificó el tipo de documento.
documents[].​cpf_matchbooleanSolo 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_docbooleanSolo 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_matchboolean or nullIndica si la selfie coincide con la foto del documento. null significa que la verificación no se ejecutó — no es un resultado negativo.
documents[].​verifiedboolean or nulltrue 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_docbooleanIndica si este documento se reutilizó de un proceso anterior.
documents[].​signed_urlstringURL 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.​versionintegerVersión del diccionario del tipo de documento (ej.: 2 para unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringTipo 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.​dataobjectCampos 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_idstring (UUID)Elemento de firma electrónica. Identificador del sobre firmado.
document_idsarray of stringsElemento de firma electrónica. IDs de los documentos del sobre.
Procesos creados solo por API

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_granted siempre es false: tu empresa recoge el consentimiento y Unico no lo registra.
  • share_id y signed_url están vacíos.
  • face_match siempre es true o false, nunca null.
  • verified siempre es null.
  • doc.version es 0.
  • doc.code suele traer el tipo de diccionario completo (ej.: unico.moja.dictionary.br.cnh.v2.Cnh), pero puede traer un código corto.
  • doc.data es null cuando no se pudieron leer los datos de OCR.

Códigos de Error​

CódigoMensajeDescripción
3process id is invalidCuando el ID del proceso no es válido.

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​