---
title: Prevención de fraude — API de datos
---

# API de datos de Prevención de fraude

La API de datos es la contraparte del lado del servidor del [Web SDK](./web-sdk).
Úsala para extraer veredictos, agregar estadísticas y exportar datos para **informes
y conciliación** — obteniendo las cifras sobre las que tus propios sistemas se ponen
de acuerdo.

## URL base

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

## Autenticación

Todas las solicitudes a la API de datos se autentican con las credenciales de tu
aplicación de Prevención de fraude, enviadas como cabeceras:

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

::: warning
`X-App-Secret` es **solo del lado del servidor**. Nunca lo expongas a navegadores,
aplicaciones móviles ni repositorios públicos. El SDK de página solo usa el `appKey`
público.
:::

## Endpoints

### Obtener un veredicto

Recupera el veredicto de una sola visita (p. ej. para conciliar una 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
```

El `data` de la respuesta es un objeto [`BotVerdict`](./verdict-reference):

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

### Estadísticas agregadas

Extrae recuentos agrupados en un rango temporal — totales, proporción de bots y el
desglose por `action`/`level` — para paneles e informes de calidad.

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

### Exportación

Exporta filas de veredicto por visita para un rango temporal, para conciliación
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 fila lleva el identificador de la visita, la marca de tiempo y los campos del
veredicto (`is_bot`, `score`, `level`, `action`), para que puedas vincularla de
vuelta con tus propios registros.

::: tip Conciliación por clic
Para escenarios de tráfico de pago, una sola visita se puede vincular de vuelta a un
clic entregado concreto para que dos partes liquiden sobre él. Eso usa un token de
clic y se cubre en la guía de [Fraude publicitario](./scenarios/ad-fraud).
:::

## Próximos pasos

- [Referencia del veredicto](./verdict-reference) — los campos devueltos por estos
  endpoints
- [Web SDK](./web-sdk) — recopila veredictos en tu página