Códigos de riesgo en advertencias KYC

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.

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 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.
`SANDBOX_KYC_REJECTED_DEFAULT`	Resultado de prueba en sandbox: validación rechazada cuando el tax ID coincidió con la lista de prueba.

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

{
  "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)

{
  "match": true,
  "score": 85,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "warnings": []
}

ID Verification

Verificar frente/reverso del documento y extraer datos

Face Match

Comparar retrato del documento y selfie

​Resumen

​KYC por sesión

​ID Verification

​Face Match

​Liveness (KYC por sesión)

​AML (KYC por sesión)

​Análisis de dispositivo e IP (KYC por sesión)

​Internos (Gu1)

​Cruce con registro (Argentina / RENAPER)

​Ejemplo de respuesta (ID Verification)

​Ejemplo de respuesta (Face Match)

ID Verification

Face Match

Resumen

KYC por sesión

ID Verification

Face Match

Liveness (KYC por sesión)

AML (KYC por sesión)

Análisis de dispositivo e IP (KYC por sesión)

Internos (Gu1)

Cruce con registro (Argentina / RENAPER)

Ejemplo de respuesta (ID Verification)

Ejemplo de respuesta (Face Match)