---
title: Prevenção de Fraude — Referência de Veredito
---

# Referência de Veredito

Todo veredito da Prevenção de Fraude — seja entregue ao seu callback `onVerdict` no
[Web SDK](./web-sdk) ou obtido da [Data API](./data-api) — é o mesmo objeto
`BotVerdict`. Esta página documenta cada campo e como agir sobre ele.

```json
{
  "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](./web-sdk#escalation)); 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.

### `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 |

## `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. |

::: tip 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](./web-sdk) — receba vereditos na sua página
- [Data API](./data-api) — obtenha vereditos e estatísticas no lado do servidor