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

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

{
  "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 — comportamento da funcionalidade, preços, canais suportados.
Relatório de Verificação de telefone — formato completo da resposta, incluindo lifecycle[] e matches[].
Modelos de dados — verificação de telefone — esquema canónico campo a campo.
API de Gestão — Listas — faça a gestão da lista de bloqueio de números de telefone utilizada por PHONE_NUMBER_IN_BLOCKLIST.

Autenticação

Verificação

Monitorização

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

Conteúdo relacionado

​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

​Conteúdo relacionado

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

Conteúdo relacionado