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

A funcionalidade Verificação de e-mail emite avisos sempre que um sinal de risco é acionado no fluxo de OTP ou no próprio endereço: uma violação de dados conhecida, um fornecedor descartável, uma caixa de correio que não pode receber mensagens, um limite de tentativas de OTP ou uma correspondência com a sua lista de bloqueio ou outra verificação aprovada. Esta página lista cada código, o que o desencadeia e como configurar a resposta do fluxo.

Visão geral

Os avisos são identificados com a funcionalidade EMAIL. Surgem no relatório em email_verifications[].warnings[] 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 registo por sessão, de modo a surgir na Business Console na secção Email. Alguns avisos são acionadores de recusa automática estrita — definem sempre o estado da funcionalidade como Declined e contêm log_type: "error". Os restantes correspondem a uma ação configurável (DECLINE, REVIEW ou a predefinida NO_ACTION) definida por nó do fluxo ou por chamada de API, pelo que o mesmo código de risco pode recusar um fluxo enquanto apenas sinaliza outro. A ação configurada também define a gravidade: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Condições de recusa automática

Os seguintes avisos recusam sempre o passo de Verificação de e-mail, independentemente da configuração:

EMAIL_CODE_ATTEMPTS_EXCEEDED — o utilizador esgotou o limite de OTP: 2 introduções incorretas de código (email_max_check_attempts) ou 2 envios de OTP — o envio inicial mais um reenvio (email_max_retries) — por predefinição.
EMAIL_IN_BLOCKLIST — o endereço está numa lista de bloqueio gerida através da Lists API, ou correspondeu a uma verificação de e-mail previamente aprovada que foi colocada na lista de bloqueio.
UNDELIVERABLE_EMAIL_DETECTED — o endereço não pode receber mensagens: sintaxe inválida, um domínio inexistente, registos DNS (MX) em falta ou impossibilidade de entrega do e-mail com o OTP. O passo é concluído imediatamente como Declined — nenhuma verificação de código chega a ser executada. Exceção: quando o próprio utilizador introduziu o endereço (não foi pré-preenchido na criação da sessão), um envio não entregável devolve um erro apresentado em linha para que possa tentar novamente com um endereço diferente em vez de ser recusado.

Riscos configuráveis

Cada um dos seguintes riscos corresponde a uma definição (por nó do fluxo ou por chamada no endpoint de verificação autónomo) que pode configurar como DECLINE, REVIEW ou NO_ACTION:

Definição	Código de risco	Comportamento predefinido
`breached_email_action`	`BREACHED_EMAIL_DETECTED`	`NO_ACTION` — apresenta os detalhes da violação com o nível `information` sem alterar o estado.
`disposable_email_action`	`DISPOSABLE_EMAIL_DETECTED`	`NO_ACTION` — sinaliza o fornecedor descartável com o nível `information` sem alterar o estado.
`duplicated_email_action`	`DUPLICATED_EMAIL`	`NO_ACTION` — regista o duplicado com o nível `information`. Ignorado quando o endereço está na lista de permissões.

A deteção de duplicados apenas considera verificações de e-mail previamente aprovadas na mesma aplicação, agrupadas por vendor_data — as verificações que partilham o mesmo vendor_data são tratadas como um único utilizador final e excluídas. Se deixar vendor_data vazio, cada sessão é tratada como um utilizador distinto. Se o endereço estiver na sua lista de permissões de e-mail, a ação de duplicado é ignorada e é emitido EMAIL_IN_ALLOWLIST em alternativa.

Limites de tentativas de verificação

A funcionalidade Verificação de e-mail aplica um limite estrito nas tentativas de OTP para prevenir abusos:

Tentativas de introdução de código — email_max_check_attempts, predefinição 2: o segundo código incorreto (ou expirado) conclui o passo.
Tentativas de envio — email_max_retries, predefinição 2 envios no total (o envio inicial mais um reenvio): um pedido de reenvio adicional conclui o passo.

Ultrapassar qualquer um dos limites aciona EMAIL_CODE_ATTEMPTS_EXCEEDED e recusa automaticamente. Pode ajustar ambos os limites por nó do fluxo.

Avisos gerados

Tag	Severidade	Descrição
`EMAIL_CODE_ATTEMPTS_EXCEEDED`	`error`	O utilizador excedeu o limite de introdução de código ou de envio. Recusa automática.
`EMAIL_IN_BLOCKLIST`	`error`	O endereço está presente numa lista de bloqueio criada através da Lists API, ou correspondeu a uma verificação aprovada que consta da lista de bloqueio. Recusa automática. `additional_data` contém `blocklisted_session_id`, `blocklisted_session_number` e `api_service` (todos `null` no caso de uma correspondência exclusiva de lista).
`EMAIL_IN_ALLOWLIST`	`information`	O endereço coincidiu com uma lista de permissões criada através da Lists API, pelo que a ação de e-mail duplicado foi ignorada.
`BREACHED_EMAIL_DETECTED`	Conforme `breached_email_action` (`information` por predefinição)	O endereço foi encontrado numa ou mais violações de dados conhecidas. O array `breaches[]` no relatório contém o serviço afetado pela violação de dados, a data e as categorias de dados.
`DISPOSABLE_EMAIL_DETECTED`	Conforme `disposable_email_action` (`information` por predefinição)	O domínio é um fornecedor de e-mails descartáveis / temporários conhecido, frequentemente utilizado para evitar a rastreabilidade.
`UNDELIVERABLE_EMAIL_DETECTED`	`error`	O endereço não consegue receber mensagens (sintaxe inválida, domínio inexistente, registos MX em falta ou falha na entrega). Recusa automática.
`DUPLICATED_EMAIL`	Conforme `duplicated_email_action` (`information` por predefinição)	O endereço coincide com uma verificação de e-mail previamente aprovada pertencente a um utilizador final diferente (agrupado por `vendor_data`). `additional_data` contém `duplicated_session_id`, `duplicated_session_number` e `api_service`.

No máximo, um de EMAIL_IN_BLOCKLIST, DUPLICATED_EMAIL e EMAIL_IN_ALLOWLIST é acionado por tentativa — a lista de bloqueio tem precedência sobre a correspondência duplicada, que tem precedência sobre a lista de permissões.

Correspondências entre sessões

Quando um endereço é detetado em verificações de e-mail previamente aprovadas ou na sua lista de bloqueio, essas ocorrências também aparecem em email_verifications[].matches[] (limitado a 5 entradas). Cada correspondência contém session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service e uma source de session (outra verificação aprovada) ou list_entry (uma entrada da lista de bloqueio). Se o endereço atual estiver na sua lista de permissões de e-mail, a Didit mantém a evidência da correspondência, mas emite EMAIL_IN_ALLOWLIST em vez de aplicar a ação de e-mail duplicado. Consulte o relatório de Verificação de e-mail para obter o esquema completo de correspondência.

Exemplo

{
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "EMAIL_IN_BLOCKLIST",
      "additional_data": {
        "blocklisted_session_id": null,
        "blocklisted_session_number": null,
        "api_service": null
      },
      "log_type": "error",
      "short_description": "Email in blocklist",
      "long_description": "The system detected that the email is in the blocklist, which is not allowed.",
      "node_id": "feature_email_1"
    },
    {
      "feature": "EMAIL",
      "risk": "DISPOSABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Disposable email detected",
      "long_description": "The system detected that the email is disposable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ]
}

Tipos de aviso

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

Relacionado

Visão geral da Verificação de e-mail — comportamento da funcionalidade e preços.
Relatório de Verificação de e-mail — formato completo da resposta, incluindo lifecycle[] e matches[].
Modelos de dados — verificação de e-mail — esquema canónico campo a campo.
Management API — Listas — faça a gestão da lista de bloqueio de e-mail utilizada por EMAIL_IN_BLOCKLIST.

Autenticação

Verificação

Monitorização

Plataforma

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

Visão geral

Condições de recusa automática

Riscos configuráveis

Limites de tentativas de verificação

Avisos gerados

Correspondências entre sessões

Exemplo

Tipos de aviso

Relacionado

​Visão geral

​Condições de recusa automática

​Riscos configuráveis

​Limites de tentativas de verificação

​Avisos gerados

​Correspondências entre sessões

​Exemplo

​Tipos de aviso

​Relacionado

Visão geral

Condições de recusa automática

Riscos configuráveis

Limites de tentativas de verificação

Avisos gerados

Correspondências entre sessões

Exemplo

Tipos de aviso

Relacionado