> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificación telefónica: advertencias y códigos de riesgo

> Didit: códigos de riesgo de verificación telefónica, como HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, lista de bloqueo y límites de OTP.

La función de Verificación de teléfono emite **advertencias** cada vez que se activa una señal de riesgo en el flujo de OTP o en el propio número: un número con historial fraudulento conocido, una línea VoIP o desechable, un límite de intentos de OTP alcanzado o una coincidencia con la sesión de otro usuario. Esta página recoge cada código, qué lo activa y cómo configurar la respuesta del flujo de verificación (workflow).

## Descripción general

Las advertencias están etiquetadas con la función `PHONE`. Aparecen en `phone_verifications[].warnings[]` dentro de `GET /v3/session/{sessionId}/decision/` y siguen la estructura estándar del [objeto de advertencia](https://docs.didit.me/es/reference/data-models.md#objeto-de-advertencia) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Cada advertencia también se registra en el log de la sesión, por lo que se muestra en la Business Console, en la sección de teléfono.

Algunas advertencias son disparadores de **rechazo automático obligatorio**: siempre establecen el estado de la función en `Declined`. Otras se asocian a una **acción configurable** (`DECLINE`, `REVIEW` o `NO_ACTION`, según la configuración) definida en la configuración de tu flujo, de modo que el mismo código de riesgo puede hacer que se rechace un flujo y solo marcar otro.

## Condiciones de rechazo automático

Las siguientes advertencias siempre rechazan el paso de Verificación de teléfono, independientemente de la configuración, y siempre llevan `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`: el usuario agotó un límite de intentos de OTP; por defecto, 2 intentos de código incorrecto (`phone_max_check_attempts`) o más de 2 envíos de OTP (`phone_max_retries`), ambos ajustables por nodo del flujo. La API de teléfono independiente permite 3 intentos de código.
* `PHONE_NUMBER_IN_BLOCKLIST`: el número está en tu lista de bloqueo gestionada mediante la [API de listas](https://docs.didit.me/es/management-api/lists/overview.md), o coincide con una sesión incluida en la lista de bloqueo.

`HIGH_RISK_PHONE_NUMBER` (cuando la capa antifraude del proveedor de entrega se niega a enviar el OTP, es decir, un envío `Blocked`) rechaza por defecto, pero **ya no es incondicional**: consulta [`high_risk_phone_action`](#envíos-bloqueados) más abajo.

## Riesgos configurables

Cada uno de los siguientes riesgos se asocia a una configuración del flujo que puedes establecer en `DECLINE`, `REVIEW` o `NO_ACTION` (el valor por defecto: la advertencia se registra sin afectar al estado). La acción configurada también determina el `log_type` de la advertencia: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Configuración | Código de riesgo | Se activa cuando |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | El operador identifica un tipo de línea `voip`, `isp` o `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | La consulta marca el número como perteneciente a un proveedor de números temporales o desechables. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | El número coincide con otra sesión, con cualquier estado, que pertenece a un usuario final distinto. Se omite cuando el número está en una lista de permitidos. |

La detección de duplicados se ejecuta dentro de tu aplicación en las verificaciones de teléfono de KYC, KYB e independientes mediante la API, y agrupa las sesiones por `vendor_data`: las sesiones que comparten el mismo `vendor_data` se tratan como un único usuario final y se excluyen de los resultados de coincidencia. Si dejas `vendor_data` vacío, cada sesión se trata como un usuario distinto.

### Envíos bloqueados

`HIGH_RISK_PHONE_NUMBER` sigue el mismo patrón con un conjunto de opciones más reducido, porque un envío que el proveedor rechazó no puede aprobarse:

| Configuración | Código de riesgo | Se activa cuando |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | La capa antifraude del proveedor de entrega se negó a enviar el OTP (envío `Blocked`). Solo acepta `DECLINE` o `REVIEW`, y su valor por defecto es `DECLINE`. |

La configuración se aplica **solo cuando todos los bloqueos de alto riesgo del paso llevan `additional_data.risk_factors` exactamente igual a `["device_attribute"]`**, es decir, la señal del proveedor de que "este dispositivo parece sospechoso", que es la que se activa en líneas móviles normales. Cualquier otro factor de riesgo, cualquier combinación que simplemente incluya `device_attribute` o un bloqueo sin ningún factor de riesgo provocan el rechazo, independientemente de la configuración. El motivo del bloqueo (`repeated_attempts`, `suspicious` o `spam`) es un campo independiente, que se devuelve en `additional_data.blocked_reason`.

Con independencia de la configuración, un número incluido en una lista de permitidos de números de teléfono creada mediante la [API de listas](https://docs.didit.me/es/management-api/lists/overview.md) nunca se rechaza automáticamente por un envío bloqueado: el paso pasa a **En revisión**, la advertencia lleva `log_type: "warning"` y `additional_data.phone_number_in_allowlist` es `true`.

## Límites de intentos de verificación

La función de Verificación de teléfono aplica un límite estricto de intentos de OTP para evitar abusos:

* **Intentos de introducción del código**: por defecto, **2** intentos fallidos de introducir el código (`phone_max_check_attempts`) antes de que el paso finalice como `Declined` con `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. La API independiente de teléfono permite **3** intentos de código por verificación.
* **Intentos de envío**: por defecto, **2** envíos en total (`phone_max_retries`): el envío inicial más un reenvío. Una solicitud de envío adicional finaliza el paso y genera `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Validez del OTP**: un OTP pendiente es válido durante **5 minutos desde el primer envío**; los reintentos no amplían ese plazo.

Ambos límites se pueden ajustar en cada nodo del flujo. Con independencia de estos límites, la capa antifraude del proveedor de entrega puede bloquear un envío directamente (motivo `repeated_attempts`, `suspicious` o `spam`), lo que genera `HIGH_RISK_PHONE_NUMBER`, no la advertencia de intentos.

## Advertencias generadas

| Etiqueta | `log_type` | Descripción |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (siempre) | El usuario superó el límite de introducción o de envío del código OTP. Se rechaza automáticamente. |
| `HIGH_RISK_PHONE_NUMBER` | Según `high_risk_phone_action`, o `warning` si está en la lista de permitidos | El proveedor de entrega bloqueó el envío del OTP. Se rechaza por defecto; configura `high_risk_phone_action` como `REVIEW` para dirigir a En revisión un bloqueo basado solo en señales del dispositivo (consulta [Envíos bloqueados](#envíos-bloqueados)). Un número que está en una lista de teléfonos permitidos también pasa a En revisión. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (siempre) | El número está en una lista de bloqueo creada mediante la [API de listas](https://docs.didit.me/es/management-api/lists/overview.md) o coincide con una sesión bloqueada. Se rechaza automáticamente. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (todos `null` si la coincidencia es solo con la lista). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | El número coincidió con otras sesiones, pero está en una lista de permitidos creada mediante la [API de listas](https://docs.didit.me/es/management-api/lists/overview.md), por lo que se omiten las acciones por teléfono duplicado. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Según `disposable_number_action` | El número pertenece a un proveedor de números temporales o desechables, usados a menudo para eludir la trazabilidad. |
| `VOIP_NUMBER_DETECTED` | Según `voip_number_action` | El número corresponde a una línea `voip`, `isp` o `vpn` en lugar de una línea móvil o fija estándar. |
| `DUPLICATED_PHONE_NUMBER` | Según `duplicated_phone_number_action` | El número coincide con otra sesión, en cualquier estado, perteneciente a un usuario final distinto (agrupado por `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Coincidencias entre sesiones

Cuando se detecta un número en otras sesiones o en tu lista de bloqueo, esas coincidencias también aparecen en `phone_verifications[].matches[]` (con un máximo de 5 entradas). Cada coincidencia incluye `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` y un `source` con valor `session` (otra sesión con el mismo número, en cualquier estado) o `list_entry` (una coincidencia sintética con la lista de bloqueo que se añade al principio del array). Si el número actual está en tu lista de números de teléfono permitidos, Didit conserva la evidencia de la coincidencia, pero emite `PHONE_NUMBER_IN_ALLOWLIST` en lugar de aplicar la acción por teléfono duplicado. Consulta el [informe de Verificación de teléfono](https://docs.didit.me/es/core-technology/phone-verification/report-phone-verification.md#coincidencias-entre-sesiones) para ver el esquema completo de coincidencias.

## Ejemplo

Un envío bloqueado (`HIGH_RISK_PHONE_NUMBER`) en un número VoIP, con `voip_number_action` configurado como `REVIEW`:

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## Tipos de advertencia

A cada riesgo se le asigna una gravedad según la configuración de tu aplicación. Las gravedades se dividen en tres categorías:

## Relacionado

* [Visión general de la Verificación de teléfono](https://docs.didit.me/es/core-technology/phone-verification/overview.md): comportamiento de la función, precios y canales compatibles.
* [Informe de Verificación de teléfono](https://docs.didit.me/es/core-technology/phone-verification/report-phone-verification.md): estructura completa de la respuesta, incluidos `lifecycle[]` y `matches[]`.
* [Modelos de datos: verificación de teléfono](https://docs.didit.me/es/reference/data-models.md#verificación-de-teléfono): esquema canónico campo por campo.
* [Management API: listas](https://docs.didit.me/es/management-api/lists/overview.md): gestiona la lista de bloqueo de teléfonos que usa `PHONE_NUMBER_IN_BLOCKLIST`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.