API de datos de Prevención de fraude

La API de datos es la contraparte del lado del servidor del 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).

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:

{
  "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.

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

{
  "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.

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.

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.

Próximos pasos

• Referencia del veredicto — los campos devueltos por estos endpoints
• Web SDK — recopila veredictos en tu página