> ## 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.

# Проверка телефона: предупреждения и коды риска

> Справочник Didit по кодам риска проверки телефона: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, списки блокировки и лимиты OTP.

Функция Проверка телефона генерирует **предупреждения** каждый раз, когда срабатывает сигнал риска в процессе OTP или в отношении самого номера: заведомо неблагонадёжный номер, VoIP или одноразовый номер, превышение лимита попыток ввода OTP или совпадение с сессией другого пользователя. На этой странице перечислены все коды, условия их срабатывания и способы настройки реакции сценария.

## Обзор

Предупреждения помечаются функцией `PHONE`. Они отображаются в массиве `phone_verifications[].warnings[]` в ответе `GET /v3/session/{sessionId}/decision/` и имеют стандартную структуру [объекта предупреждения](https://docs.didit.me/ru/reference/data-models.md#объект-предупреждения) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Каждое предупреждение также записывается в журнал сессии и отображается в Business Console в разделе Phone.

Некоторые предупреждения служат триггерами **безусловного автоматического отклонения** — они всегда переводят статус функции в `Declined`. Другие соотносятся с **настраиваемым действием** (`DECLINE`, `REVIEW` или `NO_ACTION`, в зависимости от настройки), заданным в настройках сценария, поэтому один и тот же код риска может приводить к отклонению в одном сценарии и лишь привлекать внимание в другом.

## Условия автоматического отклонения

Следующие предупреждения всегда отклоняют шаг Проверка телефона независимо от конфигурации и всегда содержат `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` — пользователь исчерпал лимит попыток OTP: по умолчанию 2 неверных ввода кода (`phone_max_check_attempts`) или более 2 отправок OTP (`phone_max_retries`), оба параметра настраиваются для каждого узла сценария. Автономный API проверки телефона допускает 3 попытки ввода кода.
* `PHONE_NUMBER_IN_BLOCKLIST` — номер находится в вашем списке блокировки, управляемом через [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md), или совпадает с сессией, внесённой в список блокировки.

`HIGH_RISK_PHONE_NUMBER` — отказ антифрод-системы провайдера доставки отправить OTP (отправка `Blocked`) — отклоняет по умолчанию, но **больше не является безусловным**: см. [`high_risk_phone_action`](#заблокированные-отправки) ниже.

## Настраиваемые риски

Каждый из следующих рисков сопоставлен с настройкой сценария, для которой можно настроить значение `DECLINE`, `REVIEW` или `NO_ACTION` (по умолчанию — предупреждение фиксируется без влияния на статус). Настроенное действие также определяет `log_type` предупреждения: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Настройка | Код риска | Срабатывает, когда |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | Тип линии определяется как `voip`, `isp` или `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | При проверке номер определяется как принадлежащий поставщику временных или одноразовых номеров. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | Номер совпадает с другой сессией в любом статусе, принадлежащей другому конечному пользователю. Проверка пропускается, если номер находится в списке разрешений. |

Обнаружение дубликатов работает в рамках вашего приложения по всем проверкам телефонов в KYC, KYB и автономном API и группирует сессии по `vendor_data`: сессии с одинаковым `vendor_data` считаются принадлежащими одному конечному пользователю и исключаются из результатов совпадений. Если оставить `vendor_data` пустым, каждая сессия будет считаться отдельным пользователем.

### Заблокированные отправки

`HIGH_RISK_PHONE_NUMBER` следует тому же принципу с более узким набором вариантов, поскольку отправка, отклонённая провайдером, не может быть одобрена:

| Настройка | Код риска | Срабатывает, когда |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | Антифрод-система провайдера доставки отказалась отправить OTP (отправка `Blocked`). Принимает только `DECLINE` или `REVIEW`, по умолчанию — `DECLINE`. |

Этот параметр применяется **только тогда, когда каждая блокировка высокого риска на шаге содержит в `additional_data.risk_factors` ровно `["device_attribute"]`** — сигнал провайдера о том, что «устройство выглядит подозрительным», который может срабатывать на обычных мобильных номерах. Любой другой фактор риска, любая комбинация, лишь включающая `device_attribute`, или блокировка вообще без факторов риска приводят к отклонению независимо от настройки. Причина блокировки (`repeated_attempts`, `suspicious` или `spam`) передаётся в отдельном поле `additional_data.blocked_reason`.

Независимо от настройки, номер из списка разрешённых номеров телефонов, созданного через [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md), никогда не отклоняется автоматически из-за заблокированной отправки: шаг переходит в статус **На проверке**, предупреждение получает `log_type: "warning"`, а `additional_data.phone_number_in_allowlist` принимает значение `true`.

## Лимиты попыток верификации

Функция «Проверка телефона» применяет жёсткое ограничение на количество попыток ввода OTP для предотвращения злоупотреблений:

* **Попытки ввода кода** — По умолчанию **2** неверные попытки ввода (`phone_max_check_attempts`), после чего шаг завершается со статусом `Declined` с ошибкой `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. Отдельный API проверки телефона разрешает **3** попытки ввода кода за верификацию.
* **Попытки отправки** — По умолчанию **2** отправки в сумме (`phone_max_retries`): начальная отправка плюс одна повторная отправка. Следующий запрос на отправку завершает шаг и вызывает `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Срок действия OTP** — OTP, ожидающий подтверждения, действителен в течение **5 минут с момента первой отправки**; повторные попытки не продлевают это окно.

Оба лимита настраиваются для каждого узла сценария. Независимо от этих лимитов, антифрод-система провайдера доставки может полностью заблокировать отправку (причина `repeated_attempts`, `suspicious` или `spam`) — это вызовет `HIGH_RISK_PHONE_NUMBER`, а не предупреждение о попытках.

## Генерируемые предупреждения

| Тег | `log_type` | Описание |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (всегда) | Пользователь превысил лимит ввода кода OTP или лимит отправок. Автоматически отклоняется. |
| `HIGH_RISK_PHONE_NUMBER` | Соответствует `high_risk_phone_action` или `warning`, если номер в белом списке | Провайдер доставки заблокировал отправку OTP. По умолчанию отклоняется; установите `high_risk_phone_action` в `REVIEW`, чтобы направлять блокировку исключительно по сигналам устройства в статус «на проверке» (см. [Заблокированные отправки](#заблокированные-отправки)). Номер из белого списка телефонов также переходит в статус «на проверке». `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (всегда) | Номер находится в списке блокировки, созданном через [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md), или совпадает с сессией, внесённой в список блокировки. Автоматически отклоняется. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (все `null` при совпадении только со списком). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | Номер совпал с другими сессиями, но находится в белом списке, созданном через [Lists API](https://docs.didit.me/ru/management-api/lists/overview.md), поэтому действия для дублирующихся номеров пропускаются. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Соответствует `disposable_number_action` | Номер принадлежит провайдеру временных или одноразовых номеров, часто используемому для уклонения от отслеживания. |
| `VOIP_NUMBER_DETECTED` | Соответствует `voip_number_action` | Номер относится к линии типа `voip`, `isp` или `vpn`, а не к стандартной мобильной или фиксированной линии. |
| `DUPLICATED_PHONE_NUMBER` | Соответствует `duplicated_phone_number_action` | Номер совпадает с другой сессией — в любом статусе — принадлежащей другому конечному пользователю (группировка по `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Совпадения между сессиями

Когда номер обнаруживается в других сессиях или в вашем списке блокировки, эти совпадения также отображаются в `phone_verifications[].matches[]` (не более 5 записей). Каждое совпадение содержит `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` и `source` со значением `session` (другая сессия с тем же номером, в любом статусе) или `list_entry` (синтетическое совпадение со списком блокировки, добавленное в начало массива). Если текущий номер находится в вашем белом списке телефонов, Didit сохраняет данные о совпадении, но выдаёт `PHONE_NUMBER_IN_ALLOWLIST` вместо применения действия для дублирующихся номеров. Полную схему совпадений см. в разделе [Отчёт о проверке телефона](https://docs.didit.me/ru/core-technology/phone-verification/report-phone-verification.md#совпадения-между-сессиями).

## Пример

Заблокированная отправка (`HIGH_RISK_PHONE_NUMBER`) для номера VoIP с параметром `voip_number_action`, настроенным на `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"
    }
  ]
}
```

## Типы предупреждений

Каждому риску присваивается уровень критичности на основе настроек вашего приложения. Уровни критичности делятся на три категории:

## Связанные материалы

* [Обзор Проверки телефона](https://docs.didit.me/ru/core-technology/phone-verification/overview.md) — поведение функции, цены, поддерживаемые каналы.
* [Отчёт о проверке телефона](https://docs.didit.me/ru/core-technology/phone-verification/report-phone-verification.md) — полная структура ответа, включая `lifecycle[]` и `matches[]`.
* [Модели данных — проверка телефона](https://docs.didit.me/ru/reference/data-models.md#проверка-телефона) — каноническая схема полей.
* [Management API — Списки](https://docs.didit.me/ru/management-api/lists/overview.md) — управление списком блокировки номеров, используемым `PHONE_NUMBER_IN_BLOCKLIST`.


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