Obtener proceso

advertencia

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

En el contrato de API, la respuesta de POST /processes/v1 ya es el resultado final. Este endpoint existe para reconsultas — por ejemplo, cuando necesitas inspeccionar un proceso que persististe anteriormente o auditar una transacción anterior. En el contrato API, la respuesta de POST /processes/v1 ya es el resultado final. Este endpoint existe para re-consultas, por ejemplo, cuando necesita inspeccionar un proceso que persistió anteriormente, o auditar una transacción previa.

Endpoint

Entorno	URL
Producción	GET https://api.id.unico.app/processes/v1/{processId}
Sandbox	GET https://api.id.uat.unico.app/processes/v1/{processId}

Solicitud

Encabezados

Encabezado	Valor
Authorization	Bearer <access_token>
APIKEY	Clave API provisionada.

Parámetros de ruta

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

Ejemplo

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

Respuestas

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1
}

Los campos de respuesta dependen de tu APIKey

El ejemplo anterior muestra todos los campos de capacidad posibles. Tu respuesta real solo incluirá los campos correspondientes a las capacidades habilitadas en la configuración de tu APIKey — los campos de capacidades deshabilitadas se omiten por completo. Contacta a tu gestor de proyecto de Unico para habilitar o ajustar las capacidades.

Campo	Tipo	Descripción
id	string (UUID)	Identificador del proceso.
status	integer	1 (procesando), 2 (divergencia), 3 (finalizado con éxito), 4 (cancelado), 5 (error).
unicoId.result	string	yes, no, inconclusive - consulte Verificación de Identidad.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive — consulte Clasificación de Riesgo de Fraude.
idFace.result	string	FOUND, NOT_FOUND — consulte Identificador Facial.
idFace.personId	string	Identificador opaco estable para el rostro. Presente solo cuando idFace.result = FOUND.
identityFraudsters.result	string	Obsoleto. Use riskLevel en su lugar. Los clientes con integraciones en curso pueden seguir usándolo mientras coordinan la migración con el equipo responsable del proyecto.
government.serpro	integer	Puntuación de similitud Serpro (0-100, -1, -2). Disponible solo en Brasil. Consulte Retorno de Similitud Serpro.
liveness	integer	1 (aprobado), 2 (fallido) - consulte Detección de Vida.
score	integer	Puntuación de riesgo probabilística. Presente cuando unicoId.result = inconclusive y la orquestación de score de riesgo está activa. Valores positivos indican mayor probabilidad de ser el titular; valores negativos indican mayor riesgo. Disponible solo en Brasil.

400 Bad Request

El parámetro de ruta processId falta o está malformado. Consulte Códigos de error a continuación.

403 Forbidden

Token Bearer o APIKEY ausente, expirado o inválido.

404 Not Found

El processId no existe o no pertenece al tenant autenticado.

410 Gone

El proceso existe pero resultó en un error. Devuelve solo id y status: 5.

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.

500 Internal Server Error

Error inesperado del servidor.

Cuándo usar este endpoint

El contrato API devuelve resultados sincrónicamente, por lo que la mayoría de las integraciones no necesitan este endpoint. Úselo cuando:

• Solo persistió el processId y necesita recuperar el resultado completo más tarde (auditoría, soporte).
• Sospecha que la respuesta original se perdió en tránsito (error de red después de que la plataforma completó el trabajo).
• Está construyendo una herramienta de back-office que revisa procesos históricos.

Códigos de error

400 Bad Request

Código	Mensaje	Descripción
20023	O parâmetro processId não foi informado.	Falta el parámetro de ID del proceso.
20002	O parâmetro APIKey não foi informado.	Falta el parámetro APIKEY en el encabezado de la solicitud.
20001	O parâmetro authtoken não foi informado.	Falta el parámetro del token de integración en el encabezado de la solicitud.

404 Not Found

Código	Mensaje	Descripción
50001	O processo informado não foi encontrado.	El proceso no existe en la base de datos.

403 Forbidden

Código	Mensaje	Descripción
30017	User does not have permission to perform this action.	JWT malformado o usuario sin permiso para realizar esta operación.
10502	O token informado está expirado.	Cuando el token de acceso utilizado ha expirado.
10501	O token informado é inválido.	El token de autenticación es inválido.
10201	O AppKey informado é inválido.	El parámetro APIKEY no fue ingresado o no existe.

410 Gone

El proceso existe pero resultó en un error. Devuelve solo id y status: 5.

500 Internal Server Error

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