Referência de Veredito

Todo veredito da Prevenção de Fraude — seja entregue ao seu callback onVerdict no Web SDK ou obtido da Data API — é o mesmo objeto BotVerdict. Esta página documenta cada campo e como agir sobre ele.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Campos

Campo	Tipo	Descrição
is_bot	boolean	O veredito principal. true = a visita é julgada como tráfego automatizado ou inválido; false = parece ser uma pessoa real. Este é o único campo sobre o qual a maioria das integrações decide.
score	number (0–100)	Quão suspeita é a visita. Quanto maior, mais suspeita. Use-o para definir seus próprios limiares — por exemplo, excluir visitas acima de um corte que você escolher. O valor exato é produzido pelo nosso modelo de risco e não deve ser submetido a engenharia reversa.
level	enum	Faixa aproximada de score: low, medium, high, critical. Conveniente quando você quer baldes (buckets) em vez de um número bruto.
action	enum	Nosso tratamento recomendado para a visita: record_only, challenge, flag ou deny. Veja abaixo. Trate valores desconhecidos como flag, para que sua integração continue funcionando se novos valores forem adicionados.
reasons	string[]	Até três categorias de motivo amplas que explicam um veredito arriscado. Vazio para visitas limpas.
consistency	object	Uma conclusão de consistência entre sinais. Leia consistency.ok (boolean): true = os sinais da visita se alinham conforme esperado; false = algo não bateu e a visita merece escrutínio extra. O detalhamento interno por trás dessa conclusão não é exposto.
degraded	boolean	true quando o veredito não pôde ser totalmente calculado (serviço inacessível, erro etc.) e um fallback conservador foi retornado. Trate vereditos degradados como "desconhecido", não como "limpo".
verdict_id	string	Id único deste veredito. Use-o para consultar o veredito depois com a Data API.
verdict_token	string	Prova assinada deste veredito, para o seu servidor verificar. Veja Verificação no servidor. Ausente em vereditos de fallback.
verdict_token_exp	number	Horário Unix (segundos) em que o verdict_token expira.

action — o que fazer

action é a nossa recomendação; você continua no controle da decisão final.

action	Significado	O que fazer
record_only	A visita parece normal.	Prossiga como de costume. Apenas registre o veredito para relatórios e conciliação.
flag	A visita é suspeita, mas não conclusivamente ruim.	Continue servindo a página, mas marque a visita como de baixa qualidade — exclua-a das suas métricas, segmente-a para fora dos fluxos seguintes e pondere-a nas suas próprias decisões (por exemplo, atribuição de conversão ou quanto você confia na visita).
challenge	A visita atingiu o seu limite de desafio (alto risco por padrão).	Peça uma verificação extra antes de tratar o visitante como humano. Quando a ação de tratamento do seu app está definida como challenge, o Web SDK executa isso por você (veja Escalonamento); caso contrário, aplique seu próprio gate.
deny	A visita correspondeu a uma regra de bloqueio — por exemplo, uma entrada de lista de bloqueio ou uma política que você configurou para bloquear.	Não sirva o conteúdo protegido. Nenhum desafio é oferecido. Versões mais antigas do SDK repassam esse valor sem alteração, então trate-o em onVerdict.

Ação de tratamento configurável

O que action reporta para uma visita de alto risco é uma configuração por app, definida no painel, nos detalhes da sua aplicação. O veredito é autoritativo no servidor: action só se torna challenge ou flag quando a visita atinge a faixa de alto risco e seu app está configurado com a ação correspondente. Abaixo dessa faixa, o veredito permanece record_only.

Configuração	action retornado em alto risco	Significado
record_only (padrão)	record_only	Apenas registrar. O veredito é registrado para relatórios e conciliação; nada é pedido ao visitante.
challenge	challenge	Aciona um CAPTCHA de reverificação. O Web SDK exibe um desafio (o estilo é controlado pelo challengeConfig do SDK).
flag	flag	Marca a visita. O veredito carrega flag; sua integração decide como agir sobre ele (bloquear / segmentar / tratar).

Como a decisão é tomada no lado do servidor, seu código permanece simples: leia verdict.action em onVerdict e aja sobre ele — prossiga, bloqueie ou deixe o SDK apresentar um desafio. Você não precisa derivar o risco por conta própria.

Limite e tipo de verificação

Quando a ação é challenge, mais duas configurações aparecem na mesma seção do painel:

• Limite de verificação — a partir de qual nível de risco a ação configurada é retornada. O padrão é risco alto ou maior. O modo estrito também a aplica a visitas de risco médio: mais scrapers e agentes de IA são barrados, mas mais visitantes reais veem uma verificação.
• Tipo de verificação — o tipo mínimo de CAPTCHA exibido na escalada: controle deslizante (padrão), girar, clique ou clique 3D. Tipos mais fortes são mais difíceis de resolver para ferramentas automatizadas e de IA.

escalate_result

Presente depois que uma escalada de captcha gerenciada é executada — ou seja, quando action era challenge e o SDK executou o captcha. null quando nenhuma escalada ocorreu. Também entregue a onEscalateDone(passed, detail).

campo	descrição
passed	se o visitante passou no captcha
token	o pass token do captcha — verifique-o no servidor para confirmar a aprovação (não confie apenas no passed do cliente)
challenge_id	o id do challenge do captcha
cid	o click id ao qual esta escalada está vinculada, se havia um click token presente

reasons — categorias de motivo

reasons diz, em termos gerais, por que uma visita pareceu arriscada. Contém no máximo três categorias, da mais forte para a mais fraca. Nunca contém sinais individuais nem detalhamentos do score.

Categoria	Significado
automation	Sinais de ferramentas automatizadas, como navegadores com script ou headless.
network	A rede parece arriscada ou inconsistente, como um proxy, data center ou rede de anonimização, ou um endereço bloqueado.
abnormal_requests	Padrões de requisição incomuns, como requisições demais, falhas repetidas ou um histórico de tráfego automatizado.
device	O dispositivo ou o seu ambiente não pôde ser considerado confiável, ou não pôde ser reconhecido.
behavior	A visita não se comportou como uma pessoa, por exemplo nenhuma interação ou um link reutilizado.
other	Qualquer outro motivo, incluindo suas próprias regras e vereditos de fallback.

Trate a lista como uma explicação para relatórios, não como um sinal para criar regras. Em vez disso, decida com base em is_bot, action ou score. Novas categorias podem ser adicionadas no futuro.

Verificação no servidor

Qualquer coisa que a página recebe pode ser alterada pelo visitante. Se você protege conteúdo (só pessoas reais podem ver uma página, uma resposta de API ou um download), não confie na flag is_bot no navegador. Envie o verdict_token ao seu próprio servidor e verifique-o lá:

1. Em onVerdict, envie verdict.verdict_token ao seu backend, por exemplo em um header ou cookie.
2. Seu backend chama POST /v1/bot/verdict/verify com o token e o endereço IP do visitante.
3. Sirva o conteúdo somente quando a resposta tiver valid: true e o veredito for aceitável para você (por exemplo, verdict.is_bot é false).

O token é vinculado ao seu app, a este veredito e à rede do visitante, e expira após pouco tempo (10 minutos por padrão). Por padrão, um token pode ser verificado várias vezes, então um único token pode cobrir as visualizações de página de uma visita. Passe consume: true quando um token precisar ser usado uma única vez, como no envio de um formulário.

Se o visitante depois passar em um desafio de escalonamento, o token ainda mostra o veredito original. Verifique também o pass token do captcha vindo de escalate_result com a API do captcha no servidor.

level vs score

level é apenas um agrupamento em faixas de score, fornecido por conveniência:

level	Use quando
low	Tratar como tráfego limpo.
medium	Limítrofe — ok registrar, considere excluir de funis de alto valor.
high	Fortemente suspeito — sinalize e exclua.
critical	Quase certamente inválido — sinalize/exclua e, idealmente, escalone.

Escolha o campo que se encaixa no seu pipeline

• Gate simples sim/não → decida sobre is_bot.
• Orientado por recomendação → decida sobre action.
• Limiares personalizados → decida sobre score (ou level para baldes).

Tratando vereditos degradados

Quando degraded é true, o veredito não foi totalmente calculado. O fallback é deliberadamente conservador (is_bot: false, action: record_only), de modo que usuários reais nunca são bloqueados. Para relatórios, trate-os como desconhecidos em vez de contá-los como tráfego confirmadamente limpo.

Próximos passos

• Web SDK — receba vereditos na sua página
• Data API — obtenha vereditos e estatísticas no lado do servidor