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://verify.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). Passe exatamente um identificador: verdict_id (do veredito que a página recebeu) ou cid (o id do clique, para tráfego com token de clique).

bash

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

found indica se um veredito foi encontrado. Quando é true, data contém os campos do veredito descritos na Referência do veredito:

json

{
  "found": true,
  "data": {
    "cid": null,
    "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "reasons": ["automation", "network"],
    "consistency": { "ok": false },
    "degraded": false,
    "created_at": "2026-06-25 00:00:00"
  }
}

Quando nada corresponde, a resposta é {"found": false}. Uma requisição sem verdict_id nem cid é rejeitada com HTTP 400.

TIP

Os vereditos são armazenados alguns segundos depois de serem produzidos, então uma consulta feita logo após a visita pode retornar found: false. Para verificar uma visita em tempo real, use Verificar um token de veredito.

Verificar um token de veredito

Verifique um verdict_token que sua página recebeu do Web SDK. Use isto para proteger conteúdo no seu servidor (veja Verificação no servidor). A verificação é respondida imediatamente e não depende de dados armazenados.

bash

POST /v1/bot/verdict/verify
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "token": "vt1.eyJ2Ijoi...", "ip": "203.0.113.7", "consume": false }

Parâmetro	Obrigatório	Descrição
`token`	sim	O `verdict_token` do veredito.
`ip`	não	O endereço IP do visitante como seu servidor o vê. Quando informado, o token deve vir da mesma rede da visita. Recomendado.
`consume`	não	`true` = o token só pode ser usado uma vez; uma segunda verificação retorna `already_used`. Padrão `false`: o token pode ser verificado novamente até expirar.

json

{
  "valid": true,
  "error": null,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "expired": false,
  "expires_at": 1767225600,
  "ip_match": true,
  "verdict": {
    "is_bot": false,
    "level": "low",
    "action": "record_only",
    "score": 12,
    "degraded": false,
    "reasons": [],
    "issued_at": 1767225000
  }
}

Campo	Descrição
`valid`	`true` quando o token é autêntico, pertence ao seu app, não expirou, corresponde a `ip` (se informado) e, com `consume`, ainda não foi usado. `valid` só diz que o token é genuíno. Não diz que o visitante é humano, então verifique também `verdict`.
`error`	`null`, ou o motivo de o token não ser válido: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (a verificação de uso único não pôde ser concluída; tente novamente).
`expired` / `expires_at`	Estado de expiração e horário de expiração (segundos Unix).
`ip_match`	`true` / `false` quando `ip` foi informado; caso contrário, `null`.
`verdict`	O veredito assinado: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null` quando o token não pôde ser lido.

Uma proteção típica entrega o conteúdo quando valid é true e verdict.is_bot é false. Decida você mesmo como tratar verdict.degraded e requisições sem nenhum token. Se você liberar em caso de falha (fail open), visitantes reais continuam passando durante uma indisponibilidade. Se bloquear em caso de falha (fail closed), nada passa sem um token válido.

Por padrão, os tokens expiram após 10 minutos. Execute o SDK novamente (por exemplo, no próximo carregamento de página) para obter um novo.

Estatísticas agregadas

Obtenha contagens ao longo de um intervalo de tempo (totais, bots e o detalhamento por level e por dia) 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

{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "cleaned": true,
  "total": 124500,
  "bots": 18230,
  "by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 },
  "by_day": [
    { "date": "2026-06-01", "total": 4100, "bots": 590 }
  ]
}

from / to têm como padrão os últimos 7 dias.

Exportação

Exporte linhas de veredito por visita para um intervalo de tempo, para conciliação offline. As linhas são retornadas das mais recentes para as mais antigas, em páginas.

bash

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

Parâmetro	Descrição
`from` / `to`	Intervalo de datas (`YYYY-MM-DD`). Opcional.
`limit`	Linhas por página, 1–5000 (padrão 1000).
`cursor`	Passe o `next_cursor` da página anterior para obter a próxima página.

json

{
  "rows": [
    {
      "id": 1042, "cid": null, "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
      "is_bot": false, "score": 12, "level": "low", "action": "record_only",
      "reasons": [], "consistency": { "ok": true }, "degraded": false,
      "created_at": "2026-06-25 00:00:00", "rescored": false
    }
  ],
  "next_cursor": 1042
}

Cada linha carrega os identificadores da visita, o timestamp e os campos do veredito, para que você possa cruzá-la de volta com seus próprios logs. next_cursor é null na última página.

Números depurados

Estatísticas e exportações são reportadas em base depurada por padrão: tráfego que é identificado posteriormente como inválido é reavaliado continuamente e removido dos números. Isso acontece de forma assíncrona, então os números de janelas muito recentes ainda podem se ajustar ligeiramente. Passe ?raw=1 para ver os números não depurados; em export, cada linha também carrega a flag rescored.

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). Cada cid é protegido contra replay: o mesmo visitante recarregando a página não tem problema, mas um token reutilizado em outro lugar é sinalizado. 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)}`

Postback (servidor a servidor)

Em vez de consultar periodicamente a Data API, você pode receber os vereditos enviados ao seu próprio endpoint assim que acontecem — útil para trackers de afiliados e back-ends de anunciantes que querem registrar ou conciliar cada visita em tempo real.

Ative-o

No painel, abra seu app → Fraud Prevention → defina a Postback URL (bot_postback_url). Uma vez definida, cada veredito é enviado via POST para essa URL logo após ser produzido. A entrega é assíncrona e isolada — um endpoint lento ou com falha nunca afeta o veredito já retornado ao SDK da página.

Quando é disparado

A cada verificação que produz um veredito para o app. A entrega é de melhor esforço, com algumas novas tentativas automáticas; trate-a como pelo menos uma vez (at-least-once) e elimine duplicatas por verdict_id.

Requisição

POST <your bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>

Corpo (JSON):

json

{
  "cid": "CID_OF_THE_VISIT",
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "is_bot": 1,
  "score": 87,
  "level": "high",
  "action": "flag",
  "advertiser_app_id": 12,
  "provider_app_id": 34,
  "created_at": "2026-06-25 00:00:00"
}

campo	descrição
`cid`	chave de reconciliação da visita (pode ser `null` se não havia token de clique)
`verdict_id`	id do veredito; o mesmo valor que a página recebeu
`is_bot`	`1` / `0`
`score`	pontuação de risco
`level`	`low` / `medium` / `high` / `critical`
`action`	ação definida pelo servidor (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	id do app para o qual a verificação foi executada
`provider_app_id`	id do provedor de tráfego quando atribuído via token de clique; caso contrário, `null`
`created_at`	horário do veredito (UTC)

Verifique a assinatura

O cabeçalho X-Bot-Signature permite confirmar que a requisição realmente veio de nós. Ele tem o formato t=<unix_ts>,v=<hex>, onde:

hex = HMAC_SHA256( "<unix_ts>." + raw_request_body , bot_hmac_secret )

bot_hmac_secret é o mesmo segredo de assinatura que você emite em Fraud Prevention → Emitir chave de assinatura. Para verificar, recalcule o HMAC sobre o corpo bruto recebido (não re-serialize o JSON) e compare em tempo constante. Opcionalmente, rejeite requisições cujo t esteja muito distante do seu relógio, para limitar replay.

// Express example
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // "t=" prefix
const v  = vPart.slice(2)              // "v=" prefix
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody is the unparsed request body
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

Próximos passos

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

Data API da Prevenção de Fraude ​

URL base ​

Autenticação ​

Endpoints ​

Obter um veredito ​

Verificar um token de veredito ​

Estatísticas agregadas ​

Exportação ​

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

Obtenha suas credenciais de assinatura ​

Formato do token ​

Campos do payload ​

Adicione-o ao link ​

Exemplo (pseudocódigo) ​

Postback (servidor a servidor) ​

Ative-o ​

Quando é disparado ​

Requisição ​

Verifique a assinatura ​

Próximos passos ​

Data API da Prevenção de Fraude

URL base

Autenticação

Endpoints

Obter um veredito

Verificar um token de veredito

Estatísticas agregadas

Exportação

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

Obtenha suas credenciais de assinatura

Formato do token

Campos do payload

Adicione-o ao link

Exemplo (pseudocódigo)

Postback (servidor a servidor)

Ative-o

Quando é disparado

Requisição

Verifique a assinatura

Próximos passos