---
title: Prevenção de Fraude — Data API
---

# Data API da Prevenção de Fraude

A Data API é a contraparte do lado do servidor do [Web SDK](./web-sdk). Use-a para obter
vereditos, agregar estatísticas e exportar dados para **relatórios e conciliação** —
obtendo os números com os quais seus próprios sistemas concordam.

## URL base

```
https://apiv1.captcha.la
```

## Autenticação

Todas as requisições da Data API são autenticadas com as credenciais da sua aplicação da
Prevenção de Fraude, enviadas como cabeçalhos:

```
X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

::: warning
`X-App-Secret` é **somente do lado do servidor**. Nunca o exponha a navegadores, apps
móveis ou repositórios públicos. O SDK de página só usa a `appKey` pública.
:::

## Endpoints

### Obter um veredito

Recupera o veredito de uma única visita (por exemplo, para conciliar uma visita
específica).

```bash
GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

O `data` da resposta é um objeto [`BotVerdict`](./verdict-reference):

```json
{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}
```

### Estatísticas agregadas

Obtenha contagens em baldes ao longo de um intervalo de tempo — totais, participação de
bots e o detalhamento por `action`/`level` — para painéis e relatórios de qualidade.

```bash
GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

```json
{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}
```

### Exportação

Exporte linhas de veredito por visita para um intervalo de tempo, para conciliação
offline.

```bash
GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

Cada linha carrega o identificador da visita, o timestamp e os campos do veredito
(`is_bot`, `score`, `level`, `action`), para que você possa cruzá-la de volta com seus
próprios logs.

::: tip Conciliação por clique
Para cenários de tráfego pago, uma única visita pode ser vinculada a um clique entregue
específico, para que duas partes possam liquidar com base nela. Isso usa um token de
clique e é abordado no guia de [Fraude em anúncios](./scenarios/ad-fraud).
:::

## Próximos passos

- [Referência de Veredito](./verdict-reference) — os campos retornados por estes endpoints
- [Web SDK](./web-sdk) — colete vereditos na sua página