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.

Referencia del token de clic (para proveedores de tráfico)

Un proveedor de tráfico firma un token de clic en su propio servidor y lo añade a la URL de destino, de modo que el veredicto de la visita resultante se atribuye de vuelta al proveedor. La firma es offline: no requiere ninguna llamada a la API.

Obtén tus credenciales de firma

En el panel, abre tu aplicación → Prevención de fraude → Emitir clave de firma. Recibes:

• bot_kid — el id de tu clave pública (se incluye en el token como pkid).
• bot_hmac_secret — tu secreto de firma, mostrado una sola vez. Guárdalo en el servidor.

Formato del token

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body es el base64url del payload JSON; la firma se calcula sobre esa cadena body.

Campos del payload

campo	obligatorio	descripción
pkid	sí	tu bot_kid; el backend lo usa para localizar tu secreto y verificar la firma
cid	sí	id único de este clic; la clave de conciliación. Genera un valor nuevo y único por clic
aud	no	el app_key del anunciante de destino. Cuando se establece, el token solo se acepta en la página de ese anunciante. Omítelo para permitir que cualquier página de anunciante lo acepte
click_ts	no	segundos unix del momento en que se produjo el clic
exp	no	segundos unix de caducidad; los tokens caducados se rechazan

Añádelo al enlace

Añade el token como el parámetro de consulta _ctk en la URL de destino del anunciante:

https://advertiser.example/lp?_ctk=ct.<...>.<...>

El SDK del anunciante lee _ctk automáticamente (configurable mediante tokenParam). Un cid solo puede reclamarse una vez (protegido contra repetición). Consulta el Modelo de seguridad.

Ejemplo (pseudocódigo)

const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`

Próximos pasos

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