Data API da Prevenção de Fraude

A Data API é a contraparte do lado do servidor do 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).

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:

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

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

Exportação

Exporte linhas de veredito por visita para um intervalo de tempo, para conciliação 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 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.

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.

Referência do token de clique (para provedores de tráfego)

Um provedor de tráfego assina um token de clique no próprio servidor e o adiciona à URL de destino, para que o veredito da visita resultante seja atribuído de volta ao provedor. A assinatura é offline — sem chamada de API.

Obtenha suas credenciais de assinatura

No painel, abra seu app → Fraud Prevention → Emitir chave de assinatura. Você recebe:

• bot_kid — o id da sua chave pública (vai no token como pkid).
• bot_hmac_secret — seu segredo de assinatura, exibido uma única vez. Mantenha-o no lado do servidor.

Formato do token

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

body é o base64url do payload JSON; a assinatura é calculada sobre essa string body.

Campos do payload

campo	obrigatório	descrição
pkid	sim	seu bot_kid; o backend o usa para localizar seu segredo e verificar a assinatura
cid	sim	id único para este clique; a chave de reconciliação. Gere um valor novo e único por clique
aud	não	o app_key do anunciante de destino. Quando definido, o token só é aceito na página daquele anunciante. Omita para permitir que qualquer página de anunciante o aceite
click_ts	não	segundos unix de quando o clique ocorreu
exp	não	segundos unix de expiração; tokens expirados são rejeitados

Adicione-o ao link

Acrescente o token como o parâmetro de consulta _ctk na URL de destino do anunciante:

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

O SDK do anunciante lê _ctk automaticamente (configurável via tokenParam). Um cid só pode ser reivindicado uma vez (protegido contra replay). Consulte o Modelo de segurança.

Exemplo (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 passos

• Referência de Veredito — os campos retornados por estes endpoints
• Web SDK — colete vereditos na sua página