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

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 (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, 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 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 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). 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 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, 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 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:

{
  "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: comportamiento de la función, precios y canales compatibles.
Informe de Verificación de teléfono: estructura completa de la respuesta, incluidos lifecycle[] y matches[].
Modelos de datos: verificación de teléfono: esquema canónico campo por campo.
Management API: listas: gestiona la lista de bloqueo de teléfonos que usa PHONE_NUMBER_IN_BLOCKLIST.

Autenticación

Verificación

Monitorización

Plataforma

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

Descripción general

Condiciones de rechazo automático

Riesgos configurables

Envíos bloqueados

Límites de intentos de verificación

Advertencias generadas

Coincidencias entre sesiones

Ejemplo

Tipos de advertencia

Relacionado

​Descripción general

​Condiciones de rechazo automático

​Riesgos configurables

​Envíos bloqueados

​Límites de intentos de verificación

​Advertencias generadas

​Coincidencias entre sesiones

​Ejemplo

​Tipos de advertencia

​Relacionado

Descripción general

Condiciones de rechazo automático

Riesgos configurables

Envíos bloqueados

Límites de intentos de verificación

Advertencias generadas

Coincidencias entre sesiones

Ejemplo

Tipos de advertencia

Relacionado