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

O recurso Verificação de e-mail emite avisos sempre que um sinal de risco é acionado no fluxo de OTP ou no próprio endereço: um vazamento de dados conhecido, um provedor descartável, uma caixa de correio indisponível, um limite de tentativas de OTP atingido ou uma correspondência com sua lista de bloqueio ou com outra verificação aprovada. Esta página lista cada código, o que o aciona e como configurar a resposta do workflow.

Visão geral

Os avisos são marcados com o recurso EMAIL. Eles aparecem 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 log da sessão, de modo que aparece no Business Console na seção de e-mail. Alguns avisos são gatilhos de recusa automática obrigatória: eles sempre definem o status do recurso como Declined e têm log_type: "error". Os demais correspondem a uma ação configurável (DECLINE, REVIEW ou o padrão NO_ACTION) definida por nó do fluxo ou por chamada de API, então o mesmo código de risco pode fazer com que um fluxo seja recusado e apenas sinalizar outro. A ação configurada também define a severidade: DECLINE → error, REVIEW → warning, NO_ACTION → information.

Condições de recusa automática

Os avisos a seguir sempre recusam a etapa de Verificação de e-mail, independentemente da configuração:

EMAIL_CODE_ATTEMPTS_EXCEEDED: o usuário esgotou o limite de tentativas de OTP, que por padrão é de 2 códigos incorretos inseridos (email_max_check_attempts) ou 2 envios de OTP, ou seja, o envio inicial mais um reenvio (email_max_retries).
EMAIL_IN_BLOCKLIST: o endereço está em uma lista de bloqueio gerenciada pela Lists API ou corresponde a uma verificação de e-mail aprovada anteriormente que foi incluída na lista de bloqueio.
UNDELIVERABLE_EMAIL_DETECTED: o endereço não pode receber mensagens por ter sintaxe inválida, domínio inexistente ou registros DNS (MX) ausentes, ou o e-mail com o OTP não pôde ser entregue. A etapa é finalizada como Declined imediatamente, sem que nenhuma verificação de código seja executada. Exceção: quando o próprio usuário digitou o endereço (ele não foi preenchido previamente na criação da sessão), um envio que não pode ser entregue retorna um erro na própria tela para que ele possa tentar novamente com outro endereço, em vez de ser recusado.

Riscos configuráveis

Cada um dos riscos a seguir corresponde a uma configuração (por nó do fluxo ou por chamada no endpoint de verificação independente) que você pode definir como DECLINE, REVIEW ou NO_ACTION:

Configuração	Código de risco	Comportamento padrão
`breached_email_action`	`BREACHED_EMAIL_DETECTED`	`NO_ACTION`: exibe os detalhes do vazamento no nível `information` sem alterar o status.
`disposable_email_action`	`DISPOSABLE_EMAIL_DETECTED`	`NO_ACTION`: sinaliza o provedor de e-mail temporário no nível `information` sem alterar o status.
`duplicated_email_action`	`DUPLICATED_EMAIL`	`NO_ACTION`: registra a duplicidade no nível `information`. A ação de duplicidade é ignorada quando o endereço está na lista de permissões.

A detecção de duplicidade considera apenas verificações de e-mail aprovadas anteriormente na mesma aplicação, agrupadas por vendor_data: verificações que compartilham o mesmo vendor_data são tratadas como um único usuário final e excluídas. Se você deixar vendor_data vazio, cada sessão será tratada como um usuário distinto. Se o endereço estiver na sua lista de permissões de e-mail, a ação de duplicidade é ignorada e EMAIL_IN_ALLOWLIST é emitido em seu lugar.

Limites de tentativas de verificação

O recurso de verificação de e-mail aplica um limite rígido às tentativas de OTP para evitar abusos:

Tentativas de inserção do código: email_max_check_attempts, padrão 2. O segundo código incorreto (ou expirado) finaliza a etapa.
Tentativas de envio: email_max_retries, padrão de 2 envios no total (o envio inicial mais um reenvio). Uma nova requisição de reenvio finaliza a etapa.

Exceder qualquer um dos limites gera EMAIL_CODE_ATTEMPTS_EXCEEDED e recusa automaticamente a verificação. Você pode ajustar os dois limites por nó do fluxo.

Avisos gerados

Tag	Severidade	Descrição
`EMAIL_CODE_ATTEMPTS_EXCEEDED`	`error`	O usuário excedeu o limite de inserção ou de envio de código. Recusa automaticamente.
`EMAIL_IN_BLOCKLIST`	`error`	O endereço está em uma lista de bloqueio criada pela Lists API ou corresponde a uma verificação aprovada incluída na lista de bloqueio. Recusa automaticamente. `additional_data` contém `blocklisted_session_id`, `blocklisted_session_number` e `api_service` (todos `null` quando a correspondência vem apenas da lista).
`EMAIL_IN_ALLOWLIST`	`information`	O endereço corresponde a uma lista de permissão criada pela Lists API, por isso a ação de e-mail duplicado não foi aplicada.
`BREACHED_EMAIL_DETECTED`	Conforme `breached_email_action` (`information` por padrão)	O endereço foi encontrado em um ou mais vazamentos de dados conhecidos. O array `breaches[]` do relatório contém o serviço vazado, a data e as categorias de dados.
`DISPOSABLE_EMAIL_DETECTED`	Conforme `disposable_email_action` (`information` por padrão)	O domínio é um provedor conhecido de e-mails descartáveis/temporários, muitas vezes usado para evitar a rastreabilidade.
`UNDELIVERABLE_EMAIL_DETECTED`	`error`	O endereço não pode receber e-mails (sintaxe inválida, domínio inexistente, registros MX ausentes ou falha na entrega). Recusa automaticamente.
`DUPLICATED_EMAIL`	Conforme `duplicated_email_action` (`information` por padrão)	O endereço corresponde a uma verificação de e-mail aprovada anteriormente que pertence a outro usuário final (agrupado por `vendor_data`). `additional_data` contém `duplicated_session_id`, `duplicated_session_number` e `api_service`.

No máximo um entre EMAIL_IN_BLOCKLIST, DUPLICATED_EMAIL e EMAIL_IN_ALLOWLIST é gerado por tentativa: a lista de bloqueio tem precedência sobre o duplicado, que tem precedência sobre a lista de permissão.

Correspondências entre sessões

Quando um endereço de e-mail é detectado em verificações de e-mail aprovadas anteriormente ou na sua lista de bloqueio, essas correspondê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 um source com valor session (outra verificação aprovada) ou list_entry (uma entrada da lista de bloqueio). Se o endereço de e-mail atual estiver na sua lista de permissão de endereços de e-mail, a Didit mantém a evidência da correspondência, mas gera 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 ver o esquema completo das correspondências.

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

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 e-mail: comportamento do recurso 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: Lists: gerencie a lista de bloqueio de e-mails usada por EMAIL_IN_BLOCKLIST.

Autenticação

Verificação

Monitoramento

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

Relacionados

​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

​Relacionados

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

Relacionados