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

# Avisos e códigos de risco da verificação de telefone

> Avisos da Verificação de Telefone da Didit: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, DISPOSABLE_NUMBER_DETECTED, lista de bloqueio e OTP.

O recurso Verificação de telefone emite **avisos** sempre que um sinal de risco é disparado no fluxo de OTP ou no próprio número: um número conhecido por ser fraudulento, uma linha VoIP ou descartável, um limite de tentativas de OTP ou uma correspondência com a sessão de outro usuário. Esta página lista cada código, o que o dispara e como configurar a resposta do workflow.

## Visão geral

Os avisos são marcados com o recurso `PHONE`. Eles aparecem em `phone_verifications[].warnings[]` em `GET /v3/session/{sessionId}/decision/` e seguem o formato padrão do [objeto de aviso](https://docs.didit.me/pt-br/reference/data-models.md#objeto-de-aviso) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Cada aviso também é encaminhado para o log da sessão, de modo que aparece no Business Console na seção Telefone.

Alguns avisos são gatilhos de **recusa automática obrigatória**: eles sempre definem o status do recurso como `Declined`. Outros correspondem a uma **ação configurável** (`DECLINE`, `REVIEW` ou `NO_ACTION`, dependendo da configuração) definida nas configurações do seu fluxo, de modo que o mesmo código de risco pode levar à recusa em um fluxo e apenas sinalizar em outro.

## Condições de recusa automática

Os avisos a seguir sempre recusam a etapa de Verificação de telefone, independentemente da configuração, e sempre trazem `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`: o usuário esgotou um limite de tentativas de OTP: por padrão, 2 tentativas com código incorreto (`phone_max_check_attempts`) ou mais de 2 envios de OTP (`phone_max_retries`), ambos ajustáveis por nó do fluxo. A API de telefone independente permite 3 tentativas de código.
* `PHONE_NUMBER_IN_BLOCKLIST`: o número está na sua lista de bloqueio gerenciada pela [API de listas](https://docs.didit.me/pt-br/management-api/lists/overview.md) ou corresponde a uma sessão incluída na lista de bloqueio.

`HIGH_RISK_PHONE_NUMBER` (a camada antifraude do provedor de entrega se recusando a enviar o OTP, envio `Blocked`) recusa por padrão, mas **deixou de ser incondicional**: veja [`high_risk_phone_action`](#envios-bloqueados) abaixo.

## Riscos configuráveis

Cada um dos riscos a seguir corresponde a uma configuração do fluxo que você pode definir como `DECLINE`, `REVIEW` ou `NO_ACTION` (o padrão: o aviso é registrado sem afetar o status). A ação configurada também define o `log_type` do aviso: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Configuração | Código de risco | É disparado quando |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | A operadora indica um tipo de linha `voip`, `isp` ou `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | A consulta sinaliza o número como de um provedor temporário / descartável. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | O número corresponde a outra sessão, de qualquer status, pertencente a um usuário final diferente. Ignorado quando o número está na lista de permissões. |

A detecção de duplicidade é executada dentro da sua aplicação, abrangendo verificações de telefone de KYC, KYB e independentes via API, e agrupa as sessões por `vendor_data`: sessões que compartilham o mesmo `vendor_data` são tratadas como um único usuário final e excluídas dos resultados de correspondência. Se você deixar `vendor_data` vazio, cada sessão será tratada como um usuário distinto.

### Envios bloqueados

`HIGH_RISK_PHONE_NUMBER` segue o mesmo padrão, com um conjunto de opções mais restrito, porque um envio que o provedor recusou não pode ser aprovado:

| Configuração | Código de risco | É disparado quando |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | A camada antifraude do provedor de entrega se recusou a enviar o OTP (envio `Blocked`). Aceita apenas `DECLINE` ou `REVIEW`, e o padrão é `DECLINE`. |

A configuração é aplicada **somente quando todos os bloqueios de alto risco na etapa trazem `additional_data.risk_factors` exatamente igual a `["device_attribute"]`**: o sinal do provedor de que "este dispositivo parece suspeito", que é o que dispara em linhas móveis comuns. Qualquer outro fator de risco, qualquer combinação que apenas inclua `device_attribute` ou um bloqueio sem nenhum fator de risco resulta em recusa, independentemente da configuração. O motivo do bloqueio (`repeated_attempts`, `suspicious` ou `spam`) é um campo separado, retornado em `additional_data.blocked_reason`.

Independentemente da configuração, um número que esteja em uma lista de permissões de telefone criada pela [API de listas](https://docs.didit.me/pt-br/management-api/lists/overview.md) nunca é recusado automaticamente por um envio bloqueado: a etapa vai para **In Review**, o aviso traz `log_type: "warning"` e `additional_data.phone_number_in_allowlist` é `true`.

## Limites de tentativas de verificação

O recurso de Verificação de telefone aplica um limite rígido de tentativas de OTP para evitar abusos:

* **Tentativas de inserção do código**: por padrão, **2** envios incorretos (`phone_max_check_attempts`) antes que a etapa seja finalizada como `Declined` com `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. A API de telefone independente permite **3** tentativas de código por verificação.
* **Tentativas de envio**: por padrão, **2** envios no total (`phone_max_retries`), ou seja, o envio inicial mais um reenvio. Uma nova requisição de envio finaliza a etapa e gera `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Validade do OTP**: um OTP pendente é válido por **5 minutos a partir do primeiro envio**; reenvios não estendem esse prazo.

Os dois limites podem ser ajustados em cada nó do fluxo de verificação (workflow). Independentemente desses limites, a camada antifraude do provedor de entrega pode bloquear um envio diretamente (motivo `repeated_attempts`, `suspicious` ou `spam`). Isso gera `HIGH_RISK_PHONE_NUMBER`, e não o aviso de tentativas.

## Avisos gerados

| Tag | `log_type` | Descrição |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (sempre) | O usuário excedeu o limite de inserção do código OTP ou de envios. Recusa automaticamente. |
| `HIGH_RISK_PHONE_NUMBER` | Segue `high_risk_phone_action`, ou `warning` quando o número está na lista de permissões | O provedor de entrega bloqueou o envio do OTP. Recusa por padrão; defina `high_risk_phone_action` como `REVIEW` para encaminhar para Em revisão um bloqueio baseado apenas em sinais do dispositivo (consulte [Envios bloqueados](#envios-bloqueados)). Um número que está em uma lista de permissões de telefones também vai para Em revisão. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (sempre) | O número está em uma lista de bloqueio criada pela [API de listas](https://docs.didit.me/pt-br/management-api/lists/overview.md) ou corresponde a uma sessão na lista de bloqueio. Recusa automaticamente. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (todos `null` quando a correspondência vem apenas da lista). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | O número corresponde a outras sessões, mas está em uma lista de permissões criada pela [API de listas](https://docs.didit.me/pt-br/management-api/lists/overview.md), por isso as ações para telefones duplicados não são aplicadas. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Segue `disposable_number_action` | O número pertence a um provedor de números temporários ou descartáveis, usados com frequência para evitar a rastreabilidade. |
| `VOIP_NUMBER_DETECTED` | Segue `voip_number_action` | O número corresponde a uma linha `voip`, `isp` ou `vpn`, e não a uma linha móvel ou fixa convencional. |
| `DUPLICATED_PHONE_NUMBER` | Segue `duplicated_phone_number_action` | O número corresponde a outra sessão, com qualquer status, pertencente a um usuário final diferente (agrupado por `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Correspondências entre sessões

Quando um número é detectado em outras sessões ou na sua lista de bloqueio, essas correspondências também aparecem em `phone_verifications[].matches[]` (limitadas a 5 entradas). Cada correspondência contém `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` e um `source` com valor `session` (outra sessão com o mesmo número, com qualquer status) ou `list_entry` (uma correspondência sintética da lista de bloqueio, inserida no início do array). Se o número atual estiver na sua lista de permissões de números de telefone, a Didit mantém a evidência da correspondência, mas emite `PHONE_NUMBER_IN_ALLOWLIST` em vez de aplicar a ação para números de telefone duplicados. Consulte o [relatório de Verificação de telefone](https://docs.didit.me/pt-br/core-technology/phone-verification/report-phone-verification.md#correspondências-entre-sessões) para ver o esquema completo das correspondências.

## Exemplo

Um envio bloqueado (`HIGH_RISK_PHONE_NUMBER`) para um número VoIP, com `voip_number_action` configurado para `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 aviso

Cada risco recebe uma severidade com base na configuração da sua aplicação. As severidades se dividem em três categorias:

## Relacionados

* [Visão geral da Verificação de telefone](https://docs.didit.me/pt-br/core-technology/phone-verification/overview.md): comportamento do recurso, preços e canais compatíveis.
* [Relatório de Verificação de telefone](https://docs.didit.me/pt-br/core-technology/phone-verification/report-phone-verification.md): estrutura completa da resposta, incluindo `lifecycle[]` e `matches[]`.
* [Modelos de dados: verificação de telefone](https://docs.didit.me/pt-br/reference/data-models.md#verificação-de-telefone): esquema canônico campo a campo.
* [Management API: listas](https://docs.didit.me/pt-br/management-api/lists/overview.md): gerencie a lista de bloqueio de números de telefone usada por `PHONE_NUMBER_IN_BLOCKLIST`.


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