# Umbrales de biometría (V3)

Fuente: /identity-verification-v3/biometric-thresholds/

 Solo disponible en V3

Durante la verificación comparamos el rostro de la credencial con la selfie del usuario y revisamos que
la persona esté realmente frente a la cámara (prueba de vida). Cada comprobación da un porcentaje, y la
sesión la aprueba solo si ese porcentaje alcanza un **umbral**: el porcentaje mínimo de aceptación.

Al [crear la sesión](/identity-verification-v3/create-verification-session/) puedes fijar tus propios
umbrales para que la verificación sea más estricta o más flexible según tu caso de uso. Si no envías
ninguno, se aplican los valores por defecto.

> **Nota**
>
> Los umbrales son **opcionales y no tienen costo adicional**. Se fijan por sesión, así que puedes usar
> valores distintos en cada una (por ejemplo, más estrictos para operaciones de mayor monto).

## Umbrales disponibles

| Parámetro | Qué compara | Rango permitido | Por defecto | Aprueba cuando |
| - | - | - | - | - |
| `face_match_threshold` | El rostro de la credencial contra la selfie. | `70` a `100` | `90` | La similitud es **mayor o igual** al umbral. |
| `liveness_threshold` | La confianza de la prueba de vida. | `50` a menos de `100` | `80` | La confianza es **mayor** al umbral. |
| `qr_face_match_threshold` | La fotografía del QR del reverso contra el rostro de la credencial. Solo aplica si la sesión se creó con `qr_validation: true`. | `70` a `100` | `80` | La similitud es **mayor o igual** al umbral. |

Todos son porcentajes y aceptan decimales, por ejemplo `87.5`.

> **La prueba de vida no acepta 100**
>
> La prueba de vida aprueba solo cuando la confianza es **mayor** que el umbral. Con `100` ninguna
> persona podría pasarla, por eso el valor debe ser menor a `100` (por ejemplo, `99.9`).

## Cómo configurarlos

Envía los umbrales en el cuerpo de la solicitud al crear la sesión. Puedes mandar uno, dos o los tres:
los que omitas toman su valor por defecto.

**JSON**

```json
{
    "validations": ["INE", "CURP"],
    "face_match_threshold": 92,
    "liveness_threshold": 85
}
```

**Con validación de QR**

```json
{
    "validations": ["INE", "CURP"],
    "qr_validation": true,
    "face_match_threshold": 92,
    "liveness_threshold": 85,
    "qr_face_match_threshold": 85
}
```

**cURL**

```bash
curl -X POST https://api.verificamex.com/identity/v3/identity/sessions \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": ["INE", "CURP"],
    "face_match_threshold": 92,
    "liveness_threshold": 85
  }'
```

> **Consejo**
>
> `qr_face_match_threshold` solo tiene efecto si también envías `qr_validation: true`. Ver
> [Validación de QR](/identity-verification-v3/qr-validation/).

## Cómo saber qué umbrales se aplicaron

La respuesta de creación confirma los umbrales de la sesión en la raíz del objeto, incluidos los que
tomaron su valor por defecto:

```json
{
    "uuid": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
    "status": "OPEN",
    "verification_url": "https://kyc.verificamex.com/verify/870c7eee-3604-4995-aa98-bc8fa6aa1112?t=...",
    "liveness_threshold": 85,
    "face_match_threshold": 92,
    "qr_face_match_threshold": 80,
    "result": null
}
```

El [detalle de la sesión](/identity-verification-v3/show-verification-session/) y el
[webhook](/identity-verification-v3/webhooks/) los incluyen en el objeto `thresholds`, junto a
`coincidence` (la similitud facial que obtuvo el usuario). Así puedes ver contra qué valor se calificó
cada sesión:

```json
{
    "data": {
        "id": "870c7eee-3604-4995-aa98-bc8fa6aa1112",
        "status": "FINISHED",
        "result": 100,
        "coincidence": 95.1,
        "thresholds": {
            "liveness": 85,
            "face_match": 92,
            "qr_face_match": 80
        }
    }
}
```

| Campo | Tipo | Descripción |
| - | - | - |
| `thresholds.face_match` | `Number` | Umbral de comparación facial con el que se calificó la sesión. Siempre trae un valor. |
| `thresholds.liveness` | `Number` o `null` | Umbral de la prueba de vida: el que enviaste o el valor por defecto (`80`). |
| `thresholds.qr_face_match` | `Number` o `null` | Umbral de la fotografía del QR: el que enviaste o el valor por defecto (`80`). |

> **Bajo el umbral, coincidence llega en 0**
>
> Si la similitud facial no alcanza `face_match_threshold`, `coincidence` llega en `0`: el servicio de
> comparación facial no informa la similitud de los rostros que quedan por debajo del umbral. Un `0`
> junto al error `FACE-MATCH-KYC-001` significa "menor que el umbral", no "similitud de 0%". Lo mismo
> aplica a `qr_validation.face_match.confidence` con `qr_face_match_threshold`.

> **Nota**
>
> Las sesiones creadas antes de que existiera esta opción muestran `face_match: 90` y `null` en los
> otros dos: son los valores por defecto con que se calificaron.

## Cómo afectan el resultado de la sesión

Si una comprobación no alcanza su umbral, se agrega una entrada al arreglo `errors` y el `result` de la
sesión pasa a **`0`**, sin importar que Lista Nominal o RENAPO hayan pasado.

| Key | Se agrega cuando |
| - | - |
| FACE-MATCH-KYC-001 | La similitud entre la credencial y la selfie es menor que `face_match_threshold`. |
| LIVENESS-KYC-001 | La prueba de vida no se completó, o su confianza no superó `liveness_threshold`. |
| QR-KYC-003 | La fotografía del QR no alcanzó `qr_face_match_threshold`. Solo cuando el QR se leyó con éxito: ver [Cómo afecta el resultado](/identity-verification-v3/qr-validation/#cómo-afecta-el-resultado-de-la-sesión). |

La entrada de `FACE-MATCH-KYC-001` indica en `Output` el umbral con que se comparó. La similitud llega
en `0` porque, como se explica arriba, no se informa cuando queda por debajo del umbral:

```json
{
    "Key": "FACE-MATCH-KYC-001",
    "Name": "Comprobación facial",
    "Category": "KycBiometryValidation",
    "Result": false,
    "Output": "face_match_confidence=0; umbral=92",
    "Message": "La comprobación facial de kyc.verificamex.com no alcanzó el umbral requerido"
}
```

Por ejemplo, con `face_match_threshold: 92`:

1. **Similitud de `95.1`**: aprueba la comparación facial y `coincidence` es `95.1`.
2. **Similitud de `92`**: aprueba, porque es igual al umbral, y `coincidence` es `92`.
3. **Similitud menor que `92`**: `coincidence` llega en `0`, se agrega `FACE-MATCH-KYC-001` a `errors`
   y el `result` pasa a `0`.

## Cómo elegir tus umbrales

- **Subir un umbral** hace la verificación más estricta: baja el riesgo de suplantación, pero rechaza
  a más personas legítimas, por ejemplo cuando la foto de la credencial es antigua, hay poca luz o la
  cámara es de baja calidad.
- **Bajar un umbral** reduce los rechazos, pero aumenta el riesgo de aprobar a alguien que no es el
  titular de la credencial.

Te recomendamos empezar con los valores por defecto, revisar cuántas sesiones se rechazan con
`FACE-MATCH-KYC-001` o `LIVENESS-KYC-001` y qué `coincidence` obtienen las aprobadas, y ajustar en
pasos pequeños.

> **Bajar el umbral de rostro aumenta el riesgo**
>
> El valor por defecto de `face_match_threshold` es `90`. Si lo bajas, se aprobarán sesiones que con el
> valor por defecto se rechazan. Hazlo solo si tu proceso tiene otros controles para confirmar la
> identidad del usuario.

## Errores de validación

Si un umbral está fuera de su rango o no es un número, la sesión **no se crea** y recibes un `422` que
indica el campo con el problema:

```json
{
    "message": "face_match_threshold debe ser de al menos 70.",
    "errors": {
        "face_match_threshold": [
            "face_match_threshold debe ser de al menos 70."
        ]
    }
}
```

| Valor enviado | Mensaje |
| - | - |
| `face_match_threshold` o `qr_face_match_threshold` menor que `70` | `… debe ser de al menos 70.` |
| `face_match_threshold` o `qr_face_match_threshold` mayor que `100` | `… no puede ser mayor que 100.` |
| `liveness_threshold` menor que `50` | `liveness_threshold debe ser de al menos 50.` |
| `liveness_threshold` de `100` o más | `liveness_threshold debe ser menor que 100.` |
| Un valor que no es número | `… debe ser un número.` |

> **Diferencia con la V2**
>
> Los umbrales no son configurables en las sesiones creadas con la V2.

**Por sesión**

Cada sesión puede llevar sus propios umbrales.

**Sin costo adicional**

Configurarlos no consume tokens extra.

**Rostro: 90 por defecto**

Si no envías nada, se mantiene el criterio de siempre.

**Visibles en la respuesta**

El detalle y el webhook indican contra qué valor se calificó.