> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Códigos de riesgo en advertencias KYC
> Cadenas de códigos de riesgo en warnings para KYC por sesión, ID Verification, Face Match y Liveness. Consulta el esquema del request, códigos de respuesta.
## Resumen
Las APIs **ID Verification**, **Face Match** y **Liveness** devuelven un campo `warnings` cuando el servicio de verificación señala incidencias no bloqueantes o banderas de riesgo. El **KYC por sesión** (`POST /api/kyc/validations`, `GET /api/kyc/validations/:id`) persiste un array `warnings` en la validación **uniendo** códigos del documento, liveness, face match y AML, y puede añadir códigos **internos de Gu1** (p. ej. listas o sandbox). Los clientes pueden usarlos para:
* **Visualización**: Mapear cada código a un mensaje (i18n propio o las descripciones siguientes; en el dashboard de gu1 las etiquetas siguen el orden de claves bajo `warningRisks` y `rejectionReasonCodes` en los archivos de idioma del producto).
* **Lógica**: Actuar por código o enviar códigos permitidos en `omitWarnings` al [crear una validación](/es/use-cases/kyc/create-validation).
En APIs puntuales los códigos son **por servicio**; en validación por sesión se usa la **unión** de servicios más códigos internos. Abajo figuran los valores documentados.
Si el servicio devuelve un código no listado aquí, igual puede aparecer en `warnings`. Tratá los códigos desconocidos como advertencias genéricas y mostrá el código o un mensaje de respaldo.
## KYC por sesión
En **`GET /api/kyc/validations/:id`** (y listados), el array **`warnings`** de la validación contiene **cadenas de código de riesgo** obtenidas de:
* Paso de verificación de documento
* Paso de liveness
* Paso de face match
* Objetos de AML en la decisión de sesión
* Análisis de dispositivo e IP en la decisión de sesión (`ip_analyses[]` / `ip_analysis`)
Pueden añadirse códigos por reglas de Gu1 (p. ej. listas de bloqueo de la organización). El campo opcional **`omitWarnings`** en [`POST /api/kyc/validations`](/es/use-cases/kyc/create-validation) usa las mismas cadenas que documentan las tablas siguientes.
## ID Verification
Se devuelve en **POST /api/kyc/id-verification** y **GET /api/kyc/id-verification/verifications/:id** en el array `warnings`. Los mismos códigos pueden aparecer en validaciones por sesión en el paso de documento.
| Código | Descripción |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ID_DOCUMENT_IN_BLOCKLIST` | El documento coincide con una entrada de su lista de documentos bloqueados (fraudulentos, robados o problemáticos). |
| `BARCODE_NOT_DETECTED` | No se pudo encontrar o leer el código de barras del documento (calidad de imagen o tipo no soportado). |
| `BARCODE_VALIDATION_FAILED` | El código de barras no pudo validarse con el resto de los datos del documento. |
| `QR_NOT_DETECTED` | No se pudo encontrar o leer el código QR del documento. |
| `QR_VALIDATION_FAILED` | El código QR no pudo validarse con el resto de los datos del documento. |
| `MRZ_NOT_DETECTED` | No se encontró o leyó la zona de lectura mecánica (MRZ) del documento. |
| `MINIMUM_AGE_NOT_MET` | La edad del usuario está por debajo del mínimo requerido. |
| `DATA_INCONSISTENT` | Los datos OCR y del chip NFC no coinciden; posible alteración o inconsistencia. |
| `COULD_NOT_RECOGNIZE_DOCUMENT` | No se pudo confirmar la autenticidad o validez del documento. |
| `PORTRAIT_IMAGE_NOT_DETECTED` | No se pudo identificar o procesar la foto del documento. |
| `IMAGE_TOO_BLURRY` | La imagen del documento está demasiado borrosa; volvé a capturarla con mejor enfoque. |
| `IMAGE_TOO_DARK` | La imagen del documento está demasiado oscura; mejorá la iluminación al capturar. |
| `IMAGE_TOO_BRIGHT` | La imagen del documento está demasiado brillante o sobreexpuesta; evitá luz directa al capturar. |
| `DOCUMENT_NUMBER_NOT_DETECTED` | No se pudo localizar o leer el número de documento. |
| `DATE_OF_BIRTH_NOT_DETECTED` | No se pudo identificar la fecha de nacimiento en el documento. |
| `EXPIRATION_DATE_NOT_DETECTED` | No se pudo identificar la fecha de vencimiento en el documento. |
| `NAME_NOT_DETECTED` | No se pudo identificar el nombre y/o apellido en el documento. |
| `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | Hay diferencias entre el MRZ y los datos extraídos por OCR; posible alteración del documento. |
| `MRZ_VALIDATION_FAILED` | El MRZ no cumple el formato esperado o contiene datos inválidos. |
| `INVALID_DATE` | Una o más fechas del documento no son válidas o no coinciden con el formato esperado. |
| `DOCUMENT_EXPIRED` | La fecha de vencimiento del documento ya pasó. |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | El tipo de documento no está aceptado en este proceso de verificación. |
| `DOCUMENT_SIDES_MISMATCH` | Las caras del documento no coinciden con el formato esperado. |
| `COULD_NOT_DETECT_DOCUMENT_TYPE` | No se pudo determinar el tipo de documento enviado. |
| `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | El nombre en este documento no coincide con el de otros documentos ya verificados para este usuario. |
| `POSSIBLE_DUPLICATED_USER` | El sistema identificó un posible usuario duplicado con documentos aprobados en otra sesión; se requiere investigación. |
| `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY` | El rostro capturado no coincide suficientemente con la foto del documento. |
| `FULL_NAME_MISMATCH_WITH_PROVIDED` | El nombre completo proporcionado no coincide con el extraído del documento. |
| `DOB_MISMATCH_WITH_PROVIDED` | La fecha de nacimiento proporcionada no coincide con la del documento. |
| `GENDER_MISMATCH_WITH_PROVIDED` | El género proporcionado no coincide con el del documento. |
| `COUNTRY_MISMATCH_WITH_PROVIDED` | El país proporcionado no coincide con el del documento. |
| `NATIONALITY_MISMATCH_WITH_PROVIDED` | La nacionalidad proporcionada no coincide con la del documento. |
| `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | El número de identificación proporcionado no coincide con el del documento. |
| `SCREEN_CAPTURE_DETECTED` | El documento parece ser una captura de pantalla o foto de un documento en pantalla, no el físico. |
| `PRINTED_COPY_DETECTED` | El documento parece ser una copia impresa, no el original oficial. |
| `PORTRAIT_MANIPULATION_DETECTED` | Se detectó posible manipulación del área de la foto del documento. |
| `UNPARSED_ADDRESS` | La dirección del documento no pudo interpretarse o geolocalizarse. |
| `DOCUMENT_NUMBER_FORMAT_MISMATCH` | El número de documento no coincide con el formato esperado para este tipo. |
| `PERSONAL_NUMBER_FORMAT_MISMATCH` | El número personal no coincide con el formato esperado para este tipo de documento. |
| `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS` | Los datos extraídos de varios documentos de esta sesión no coinciden (nombre o fecha de nacimiento). |
| `GUENO_KYC_ORG_BLOCKLIST_HIT` | Camino de rechazo automático: un valor de esta validación coincidió con una lista de bloqueo KYC de la organización (señal agregada). |
| `GUENO_KYC_ORG_BLOCKLIST_IP` | Lista de bloqueo KYC de la organización: la IP de la sesión coincidió con una lista de enforcement. |
| `GUENO_KYC_ORG_BLOCKLIST_DOCUMENT` | Lista de bloqueo KYC de la organización: el número de documento coincidió con una lista de enforcement. |
| `GUENO_KYC_ORG_BLOCKLIST_PERSONAL` | Lista de bloqueo KYC de la organización: el número personal / trámite coincidió con una lista de enforcement. |
| `GUENO_KYC_ORG_MINIMUM_AGE_NOT_MET` | Política de edad mínima de la organización (ajustes KYC): la fecha de nacimiento extraída implica **menos años cumplidos** que el umbral configurado; la validación pasa a **rechazada** aunque el OCR haya validado la identidad. Si no hay fecha de nacimiento interpretable, no se aplica. |
## Face Match
Se devuelve en **POST /api/kyc/face-match** y **GET /api/kyc/face-match/verifications/:id** en el array `warnings`.
| Código | Descripción |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `LOW_FACE_MATCH_SIMILARITY` | Los rasgos faciales de la imagen no coinciden lo suficiente con la imagen de referencia. |
| `NO_REFERENCE_IMAGE` | Falta una imagen de referencia para la comparación facial. |
## Liveness (KYC por sesión)
Se devuelve en las respuestas de validación KYC por sesión (p. ej. validación actual, listado) cuando se realizan chequeos de vivacidad. El array `warnings` del payload puede contener estos códigos.
| Código | Descripción |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `FACE_IN_BLOCKLIST` | El rostro coincide con una entrada de su lista de rostros bloqueados. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | El sistema identificó un posible rostro en la lista de bloqueados. |
| `LOW_LIVENESS_SCORE` | El chequeo de vivacidad obtuvo una puntuación baja. |
| `NO_FACE_DETECTED` | No se identificó un rostro durante el chequeo de vivacidad. |
| `LIVENESS_FACE_ATTACK` | Se detectó un posible intento de evadir el chequeo de vivacidad. |
| `DUPLICATED_FACE` | Se identificó un rostro duplicado de otra sesión aprobada. |
| `POSSIBLE_DUPLICATED_FACE` | Este rostro podría coincidir con otro usuario ya aprobado en el sistema. |
| `MULTIPLE_FACES_DETECTED` | Se detectaron varios rostros en la imagen. Se usa el más grande para la verificación. (Solo Liveness pasivo) |
| `LOW_FACE_QUALITY` | La calidad de la imagen facial está por debajo del umbral aceptable. (Solo Liveness pasivo) |
| `LOW_FACE_LUMINANCE` | La imagen facial es demasiado oscura. (Solo Liveness pasivo) |
| `HIGH_FACE_LUMINANCE` | La imagen facial está demasiado brillante o sobreexpuesta. (Solo Liveness pasivo) |
## AML (KYC por sesión)
Cuando el AML corre dentro de la sesión, los códigos de riesgo de las **`warnings`** del screening se fusionan en el array `warnings` de la validación.
| Código | Descripción |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `POSSIBLE_MATCH_FOUND` | El screening AML encontró posibles coincidencias con listas o bases de alto riesgo; puede requerir revisión. |
| `COULD_NOT_PERFORM_AML_SCREENING` | No se pudo completar el screening AML con los datos disponibles (p. ej. faltan campos requeridos). |
## Análisis de dispositivo e IP (KYC por sesión)
Cuando el análisis de dispositivo e IP corre dentro de la sesión, los códigos de riesgo de **`ip_analyses[].warnings[]`** (o legacy `ip_analysis.warnings`) se fusionan en el array `warnings` de la validación.
| Código | Descripción |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PRIVATE_NETWORK_DETECTED` | La sesión se abrió mediante VPN, proxy o red Tor. |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | El país del documento de identidad no coincide con el país derivado de la dirección IP. |
| `EXPECTED_IP_ADDRESS_MISMATCH` | La IP en vivo difiere de la IP esperada indicada al crear la sesión. |
| `IP_ADDRESS_IN_BLOCKLIST` | La dirección IP de la sesión coincide con una entrada en la blocklist de IP del proveedor (fuerza rechazo en el proveedor). |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST` | La huella del dispositivo coincide con una entrada en la blocklist de dispositivos del proveedor (fuerza rechazo en el proveedor). |
| `DUPLICATED_IP_ADDRESS` | La misma dirección IP se usó en otra sesión con un identificador de usuario distinto (`vendor_data`). |
| `DUPLICATED_DEVICE_FINGERPRINT` | La misma huella persistente del dispositivo se reutilizó en sesiones con identificadores de usuario distintos. |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | Recuperación de dispositivo con alta confianza: la sesión coincide con un dispositivo visto antes tras cambiar el ID persistente (p. ej. incógnito, borrado de almacenamiento o reinstalación). |
## Internos (Gu1)
Códigos que Gu1 puede añadir (entidad vs OCR, política de nombre, sandbox, etc.) y aparecer en `warnings` de la validación por sesión cuando corresponda.
| Código | Descripción |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GUENO_DOCUMENT_NUMBER_MISMATCH` | El número de documento de la verificación no coincide con el de la entidad al momento del chequeo. |
| `GUENO_PERSONAL_NUMBER_MISMATCH` | Los chequeos de documento/personal contra la entidad no alinean como se exige. |
| `GUENO_KYC_NAME_SIMILARITY_BELOW_MIN` | La similitud del nombre de la entidad con el derivado del documento está por debajo del mínimo de la organización. |
| `GUENO_CROSS_ENTITY_DUPLICATED` | Gu1 confirmó que las referencias de rostro/sesión duplicada pertenecen a **otra entidad** de la misma organización (`metadata.kycCrossEntityDuplicates.matches`). Si el OCR mapeó **`approved`**, Gu1 deja el estado en **`in_review`** para revisión manual. **No omitible:** no puede ir en `omitWarnings` ni auto-aprobarse por omit. Matches contra otra entidad con el **mismo tax ID** (normalizado) que la entidad evaluada **no** cuentan como cross-entity. |
| `SANDBOX_KYC_REJECTED_DEFAULT` | Resultado de prueba en sandbox: validación rechazada cuando el tax ID coincidió con la lista de prueba. |
**Duplicados cross-entity:** Códigos del proveedor como `DUPLICATED_FACE` o `POSSIBLE_DUPLICATED_USER` se conservan solo si Gu1 resuelve match en **otra** entidad; si no, pueden suprimirse (`metadata.kycCrossEntityDuplicates.suppressedWarnings`). `GUENO_CROSS_ENTITY_DUPLICATED` nunca es omitible.
## Cruce con registro (Argentina / RENAPER)
Con doble chequeo RENAPER activado, si un problema de registro se expone como **código en `warnings`**, pueden usarse las mismas cadenas. En los idiomas del producto suelen mapearse bajo **`rejectionReasonCodes`** (y resoluciones de respaldo donde aplique).
| Código | Descripción |
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
| `RENAPER_DNI_MISSING` | No se pudo ejecutar el cruce: no hay número de documento (DNI) desde la verificación. |
| `RENAPER_GENDER_MISSING` | No se pudo ejecutar el cruce: hace falta género (M/F) para el registro. |
| `RENAPER_VERIFICATION_UNAVAILABLE` | No se pudo completar el registro; reintentar más tarde. |
| `RENAPER_DNI_NOT_MATCH` | El número de documento no coincide con el registro oficial. |
| `RENAPER_TRAMITE_DATA_MISSING` | No se pudo comparar el número de trámite: faltan datos requeridos. |
| `RENAPER_TRAMITE_ID_NOT_MATCH` | El número de trámite no coincide con el registro (p. ej. ejemplar de DNI desactualizado). |
| `RENAPER_NAME_NOT_MATCH` | El nombre del OCR no alcanza el umbral de similitud (80%) con el registro RENAPER. |
| `RENAPER_EJEMPLAR_NOT_MATCH` | El ejemplar del DNI no coincide con el registro RENAPER. |
| `RENAPER_DOB_NOT_MATCH` | La fecha de nacimiento del OCR no coincide con `fecha_nacimiento` de RENAPER. |
| `RENAPER_EXPIRY_NOT_MATCH` | La fecha de vencimiento del OCR no coincide con `vencimiento` de RENAPER. |
| `RENAPER_BIOMETRIC_NOT_MATCH` | La selfie no coincide con la foto del DNI en el registro biométrico. |
| `RENAPER_BIOMETRIC_UNAVAILABLE` | No se pudo completar el chequeo biométrico (red, credenciales o servicio). |
| `RENAPER_CREDENTIALS_REQUIRED` | Faltan credenciales RENAPER configuradas para la organización. |
| `RENAPER_NOT_VALID_CREDENTIALS` | Las credenciales RENAPER no son válidas. |
## Ejemplo de respuesta (ID Verification)
```json theme={null}
{
"status": "approved",
"verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"requestId": "req_abc",
"extractedData": { "fullName": "Jane Doe", "documentNumber": "12345678" },
"warnings": ["POSSIBLE_DUPLICATED_USER"]
}
```
## Ejemplo de respuesta (Face Match)
```json theme={null}
{
"match": true,
"score": 85,
"status": "approved",
"verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"warnings": []
}
```
Verificar frente/reverso del documento y extraer datos
Comparar retrato del documento y selfie