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.

MarkdownChatGPTClaude
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. Valores PROCESS_STATE_* (ej.: CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, 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

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: IDCARD, DRIVERLICENSE, PASSPORT o VOTERID. Los pasaportes de EE. UU. mantienen su variante en lugar de colapsar a PASSPORT, por lo que también se devuelven valores como POLYCARBONATEPASSPORT, PASSPORTCARD y PAPERPASSPORT. Por ejemplo, unico.moja.dictionary.ar.generic.v1.IdCard y unico.moja.dictionary.us.generic.v1.PolycarbonatePassport se reportan como IDCARD y POLYCARBONATEPASSPORT.

process.services[].documents[].doc.code reporta el tipo de documento como un código corto en mayúsculas. unico.moja.dictionary.br.cnh.v2.Cnh se convierte en CNH. El código no contiene ni el país ni la versión del esquema; la versión se devuelve por separado en doc.version.

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 — doc.data está vacío
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": "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
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-2.
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.
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.
Inconsistencia de nomenclatura del estado

AWAITING_FOR_DOCUMENT no sigue la convención de prefijo PROCESS_STATE_* usada por los demás estados. Se trata de una inconsistencia de nomenclatura conocida en la API actual.

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).
Campos de process.services
Convenciones de nomenclatura mixtas en services

El arreglo services usa camelCase para los campos a nivel de envelope (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 un error de documentación.

CampoTipoDescripción
envelopeIdstring (UUID)Identificador del envelope firmado.
documentIdsarray of stringsIDs de los documentos capturados en este servicio.
consent_grantedbooleanIndica si el usuario otorgó el consentimiento de compartición de datos.
documentsarrayDocumentos capturados con datos de OCR y resultados de validación.
documents[].doc_idstringIdentificador del documento.
documents[].​typifiedbooleanIndica si el tipo de documento se identificó correctamente.
documents[].​cpf_matchbooleanIndica si el CPF del documento coincide con el CPF proporcionado (solo Brasil).
documents[].​face_matchbooleanIndica si la selfie coincide con la foto del documento.
documents[].​validate_docbooleanIndica si el documento superó la validación de autenticidad.
documents[].​reused_docbooleanIndica si este documento se reutilizó de un proceso anterior.
documents[].​signed_urlstringURL pre-firmada para descargar el PDF del documento (válida durante 5 minutos — vuelve a solicitarla para renovarla).
documents[].​doc.​versionintegerVersión del esquema de OCR.
documents[].​doc.​codestringCódigo corto del tipo de documento (ej.: CNH). 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 dentro de doc.data (ej.: nomeCivil, dataNascimento) se devuelven en portugués — son los valores reales producidos por el motor 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​

Última actualización el