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

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

{
  "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: comportamento do recurso, preços e canais compatíveis.
Relatório de Verificação de telefone: estrutura completa da resposta, incluindo lifecycle[] e matches[].
Modelos de dados: verificação de telefone: esquema canônico campo a campo.
Management API: listas: gerencie a lista de bloqueio de números de telefone usada por PHONE_NUMBER_IN_BLOCKLIST.

Autenticação

Verificação

Monitoramento

Plataforma

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

Visão geral

Condições de recusa automática

Riscos configuráveis

Envios bloqueados

Limites de tentativas de verificação

Avisos gerados

Correspondências entre sessões

Exemplo

Tipos de aviso

Relacionados

​Visão geral

​Condições de recusa automática

​Riscos configuráveis

​Envios bloqueados

​Limites de tentativas de verificação

​Avisos gerados

​Correspondências entre sessões

​Exemplo

​Tipos de aviso

​Relacionados

Visão geral

Condições de recusa automática

Riscos configuráveis

Envios bloqueados

Limites de tentativas de verificação

Avisos gerados

Correspondências entre sessões

Exemplo

Tipos de aviso

Relacionados