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

> Guia dos códigos de risco da Verificação de telefone da Didit: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, listas de bloqueio e limites de OTP.

A funcionalidade de Verificação de telefone emite **avisos** sempre que um sinal de risco é acionado no fluxo de OTP ou no próprio número: um número sabidamente problemático, uma linha VoIP ou descartável, um limite de tentativas de OTP atingido ou uma correspondência com a sessão de outro utilizador. Esta página lista todos os códigos, o que os aciona e como configurar a resposta do fluxo.

## Visão geral

Os avisos são identificados com a funcionalidade `PHONE`. Surgem sob `phone_verifications[].warnings[]` em `GET /v3/session/{sessionId}/decision/` e seguem a estrutura padrão do [objeto de aviso](https://docs.didit.me/pt/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 registo por sessão, de modo a surgir na Business Console na secção Telefone.

Alguns avisos são acionadores de **recusa automática estrita** — definem sempre o estado da funcionalidade como `Declined`. Outros correspondem a uma **ação configurável** (`DECLINE`, `REVIEW` ou `NO_ACTION`, dependendo da definição) definida nas definições do seu fluxo, pelo que o mesmo código de risco pode recusar um fluxo e apenas sinalizar outro.

## Condições de recusa automática

Os seguintes avisos recusam sempre o passo de Verificação de telefone, independentemente da configuração, e apresentam sempre `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` — o utilizador esgotou o limite de tentativas de OTP: por predefinição, 2 submissões de códigos incorretos (`phone_max_check_attempts`) ou mais de 2 envios de OTP (`phone_max_retries`), ambos configuráveis por nó de fluxo. A API de telefone autónoma permite 3 tentativas de código.
* `PHONE_NUMBER_IN_BLOCKLIST` — o número está na sua lista de bloqueio gerida através da [Lists API](https://docs.didit.me/pt/management-api/lists/overview.md), ou corresponde a uma sessão na lista de bloqueio.

`HIGH_RISK_PHONE_NUMBER` — a camada antifraude do fornecedor de entrega que recusa enviar o OTP (envio `Blocked`) — recusa por predefinição, mas **já não é incondicional**: consulte [`high_risk_phone_action`](#envios-bloqueados) abaixo.

## Riscos configuráveis

Cada um dos seguintes riscos mapeia para uma definição de fluxo que pode configurar para `DECLINE`, `REVIEW` ou `NO_ACTION` (a predefinição — o aviso é registado sem afetar o estado). A ação configurada também define o `log_type` do aviso: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Definição | Código de risco | É acionado quando |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | A pesquisa da operadora identifica o tipo de linha como `voip`, `isp` ou `vpn`. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | A pesquisa assinala o número como pertencente a um fornecedor de números temporários/descartáveis. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | O número corresponde a outra sessão de qualquer estado pertencente a um utilizador final diferente. Ignorado se o número estiver na lista de permissões. |

A deteção de duplicados é executada na sua aplicação em verificações de telefone de KYC, KYB e de API autónoma, e agrupa as sessões por `vendor_data` — as sessões que partilham o mesmo `vendor_data` são tratadas como um único utilizador final e são excluídas dos resultados de correspondência. Deixe o `vendor_data` vazio e cada sessão será tratada como um utilizador distinto.

### Envios bloqueados

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

| Definição | Código de risco | É acionado quando |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | A camada antifraude do fornecedor de entrega recusou enviar o OTP (envio `Blocked`). Aceita apenas `DECLINE` ou `REVIEW`, e tem como predefinição `DECLINE`. |

A definição é aplicada **apenas quando cada bloqueio de alto risco no passo apresentar `additional_data.risk_factors` exatamente igual a `["device_attribute"]`** — o sinal do fornecedor de que "este dispositivo parece suspeito", que é o que dispara em linhas móveis normais. Qualquer outro fator de risco, qualquer combinação que inclua `device_attribute` juntamente com outros fatores, ou um bloqueio sem quaisquer fatores de risco recusa independentemente da definição. O motivo do bloqueio (`repeated_attempts`, `suspicious` ou `spam`) é um campo separado, devolvido em `additional_data.blocked_reason`.

Independentemente da definição, um número presente numa lista de permissões de telefone criada através da [Lists API](https://docs.didit.me/pt/management-api/lists/overview.md) nunca é recusado automaticamente por um envio bloqueado: o passo passa para **Em análise**, o aviso apresenta `log_type: "warning"` e `additional_data.phone_number_in_allowlist` é `true`.

## Limites de tentativas de verificação

A funcionalidade Verificação de telefone aplica um limite rígido às tentativas de OTP para prevenir abusos:

* **Tentativas de introdução do código** — Por predefinição, **2** envios incorretos (`phone_max_check_attempts`) antes de o passo finalizar como `Declined` com `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. A API de telefone autónoma permite **3** tentativas de código por verificação.
* **Tentativas de envio** — Por predefinição, **2** envios no total (`phone_max_retries`): o envio inicial mais um reenvio. Um pedido de envio adicional finaliza o passo e gera `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **Validade do OTP** — Um OTP pendente é válido durante **5 minutos a partir do primeiro envio**; as novas tentativas não prolongam a janela.

Ambos os limites são configuráveis por nó do fluxo. Independentemente destes limites, a camada antifraude do fornecedor de entrega pode bloquear totalmente um envio (motivo `repeated_attempts`, `suspicious` ou `spam`) — isso gera `HIGH_RISK_PHONE_NUMBER`, e não o aviso de tentativas.

## Avisos gerados

| Etiqueta | `log_type` | Descrição |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (sempre) | O utilizador excedeu o limite de introdução de código OTP ou de envio. Recusa automática. |
| `HIGH_RISK_PHONE_NUMBER` | Segue `high_risk_phone_action`, ou `warning` quando estiver na lista de permissões | O fornecedor de entrega bloqueou o envio do OTP. Recusa por predefinição; defina `high_risk_phone_action` para `REVIEW` para encaminhar um bloqueio apenas por sinais de dispositivo para Em análise (consulte [Envios bloqueados](#envios-bloqueados)). Um número numa lista de permissões de telefone também passa para Em análise. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (sempre) | O número está numa lista de bloqueio criada através da [API de Listas](https://docs.didit.me/pt/management-api/lists/overview.md) ou corresponde a uma sessão incluída numa lista de bloqueio. Recusa automática. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (tudo `null` para um resultado exclusivamente da lista de bloqueio). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | O número correspondeu a outras sessões, mas está numa lista de permissões criada através da [API de Listas](https://docs.didit.me/pt/management-api/lists/overview.md), pelo que as ações relativas a números de telefone duplicados são ignoradas. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Segue `disposable_number_action` | O número pertence a um fornecedor temporário / descartável, frequentemente utilizado para contornar a rastreabilidade. |
| `VOIP_NUMBER_DETECTED` | Segue `voip_number_action` | O número corresponde a uma linha de `voip`, `isp` ou `vpn` em vez de uma linha móvel ou fixa padrão. |
| `DUPLICATED_PHONE_NUMBER` | Segue `duplicated_phone_number_action` | O número corresponde a outra sessão — com qualquer estado — pertencente a um utilizador 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 é detetado noutras sessões ou na sua lista de bloqueio, essas correspondências também surgem em `phone_verifications[].matches[]` (com um limite de 5 entradas). Cada correspondência inclui `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` e uma `source` de `session` (outra sessão com o mesmo número, em qualquer estado) ou `list_entry` (uma correspondência sintética da lista de bloqueio adicionada no início do array). Se o número atual estiver na sua lista de permissões 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 relativa a números de telefone duplicados. Consulte o [relatório de Verificação de telefone](https://docs.didit.me/pt/core-technology/phone-verification/report-phone-verification.md#correspondências-entre-sessões) para obter o esquema completo de correspondências.

## Exemplo

Um envio bloqueado (`HIGH_RISK_PHONE_NUMBER`) num 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

A cada risco é atribuída uma gravidade com base na configuração da sua aplicação. As gravidades dividem-se em três categorias:

## Conteúdo relacionado

* [Visão geral da Verificação de telefone](https://docs.didit.me/pt/core-technology/phone-verification/overview.md) — comportamento da funcionalidade, preços, canais suportados.
* [Relatório de Verificação de telefone](https://docs.didit.me/pt/core-technology/phone-verification/report-phone-verification.md) — formato completo da resposta, incluindo `lifecycle[]` e `matches[]`.
* [Modelos de dados — verificação de telefone](https://docs.didit.me/pt/reference/data-models.md#verificação-de-telefone) — esquema canónico campo a campo.
* [API de Gestão — Listas](https://docs.didit.me/pt/management-api/lists/overview.md) — faça a gestão da lista de bloqueio de números de telefone utilizada por `PHONE_NUMBER_IN_BLOCKLIST`.


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