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",
  "consistency": { "ok": true },
  "degraded": false
}

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 ou flag. Veja abaixo.
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".

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 é de alto risco.	Peça uma verificação extra antes de tratar o visitante como humano. Com escalate: true do Web SDK, isso é tratado por você (veja Escalonamento); caso contrário, aplique seu próprio gate.

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.

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