Saltar para o conteúdo

Bot Protection

Mantém os bots longe dos seus formulários, inícios de sessão e sites alojados.

Abrir Bot Protection
Verificado com o painel em 18 de novembro de 2026

O Bot Protection tem dois lados em código. Na sua página, um pequeno script desenha a verificação e coloca um token no seu formulário quando um visitante passa. No seu servidor, um pedido confirma esse token com a chave secreta da configuração. Nenhum dos dois precisa de uma chave de API da conta: a chave do site (pública) e a chave secreta (privada) da própria configuração são o que os delimita.

As configurações em si, os seus planos e os seus números gerem-se no dashboard.

Na sua página

Copie o código de incorporação da configuração; já contém a chave do site da configuração. Esta é a sua forma para cada modo de apresentação da verificação.

<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" async data-sitekey="YOUR_SITE_KEY"></script>
<div class="xuda-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" async data-sitekey="YOUR_SITE_KEY"></script>
<div class="xuda-captcha" data-sitekey="YOUR_SITE_KEY" data-mode="invisible"></div>
<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" data-sitekey="YOUR_SITE_KEY" data-mode="fullpage"></script>
  • Caixa de seleção e Invisível: coloque o div dentro do formulário que quer proteger. Numa passagem, o script preenche um campo oculto chamado xuda-captcha-response nesse formulário, para que o token seja enviado com ele.
  • Invisível não mostra nada. Um formulário enviado sem um token recente fica retido, a verificação corre e o formulário é enviado de novo.
  • Página inteira é só o script, no head da página. A página fica coberta até o visitante passar, e esse separador não é questionado de novo até a sua passagem expirar.
  • Uma configuração cujo aspeto é Claro ou Escuro acrescenta data-theme="light" ou data-theme="dark".

A verificação só corre nos domínios permitidos da configuração.

Callbacks

Indique uma função global no div (ou no script, para Página inteira) para ser informado do que aconteceu:

window.xudaCaptcha.execute(element) devolve uma promessa de um token novo, para um formulário que envia a partir do seu próprio código.

No seu servidor

Envie o token e a chave secreta da configuração para captcha_siteverify. Aceite o formulário apenas quando a resposta disser success. Mantenha a chave secreta na configuração do seu próprio servidor, nunca numa página.

curl -s https://xuda.ai/cpi/captcha_siteverify \
  -H 'content-type: application/json' \
  -d '{"secret":"YOUR_SECRET_KEY","response":"TOKEN_FROM_THE_FORM"}'
const res = await fetch('https://xuda.ai/cpi/captcha_siteverify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ secret: 'YOUR_SECRET_KEY', response: token }),
});
const { data } = await res.json();
if (!data.success) throw new Error('The check did not pass');
import requests

res = requests.post(
    'https://xuda.ai/cpi/captcha_siteverify',
    json={'secret': 'YOUR_SECRET_KEY', 'response': token},
)
passed = res.json()['data']['success']

Uma passagem responde:

json
{
  "code": 1,
  "data": {
    "success": true,
    "score": 0.9,
    "level_reached": 0,
    "hostname": "example.com",
    "challenge_ts": 1762950000000,
    "error-codes": []
  }
}
Um token vale uma vez, durante dois minutos

Um token é aceite uma única vez e dura dois minutos. Confirme-o quando o formulário chegar, não mais tarde, e nunca confirme o mesmo token duas vezes.

Quando não passa

success é false e error-codes diz porquê:

A resposta tem a mesma forma das que o reCAPTCHA e o Turnstile dão, por isso o código de servidor escrito para esses normalmente só precisa de mudar o endereço e o segredo.

Limites do plano

Uma verificação é contada quando o primeiro passo de um visitante chega a uma decisão. O limite mensal do plano lê as verificações nos seus próprios sites e formulários; nada do que é alojado com a Xuda é contado. Acima de um limite, o passo de IA é ignorado até ao mês seguinte e todas as verificações continuam a correr, por isso nenhum formulário falha. Consulte Planos e faturação.

Que tal está este guia?

Última atualização em 16 de novembro de 2026