Saltar al contenido

Bot Protection

Mantiene a los bots fuera de tus formularios, inicios de sesión y sitios alojados.

Abrir Bot Protection
Comprobado con el panel el 18 de noviembre de 2026

Bot Protection tiene dos lados en código. En tu página, un pequeño script dibuja la comprobación y pone un token en tu formulario cuando un visitante la supera. En tu servidor, una solicitud confirma ese token con la clave secreta de la configuración. Ninguno necesita una clave de API de la cuenta: lo que los delimita es la clave del sitio (pública) y la clave secreta (privada) de cada configuración.

Las configuraciones en sí, sus planes y sus cifras se gestionan en el dashboard.

En tu página

Copia el código de inserción de la configuración; ya contiene la clave del sitio de la configuración. Esta es su forma para cada manera de mostrar la comprobación.

<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>
  • Casilla e Invisible: pon el div dentro del formulario que quieres proteger. Al superarla, el script rellena un campo oculto llamado xuda-captcha-response en ese formulario, de modo que el token se envía con él.
  • Invisible no muestra nada. Un formulario enviado sin un token reciente se retiene, se ejecuta la comprobación y el formulario se envía de nuevo.
  • Página completa es solo el script, en el head de la página. La página queda cubierta hasta que el visitante la supera, y a esa pestaña no se le vuelve a pedir hasta que caduca su superación.
  • Una configuración cuyo aspecto es Claro u Oscuro añade data-theme="light" o data-theme="dark".

La comprobación solo se ejecuta en los dominios permitidos de la configuración.

Callbacks

Indica una función global en el div (o en el script, para Página completa) para que te avise de lo ocurrido:

window.xudaCaptcha.execute(element) devuelve una promesa de un token reciente, para un formulario que envías desde tu propio código.

En tu servidor

Envía el token y la clave secreta de la configuración a captcha_siteverify. Acepta el formulario solo cuando la respuesta diga success. Guarda la clave secreta en la configuración propia de tu servidor, nunca en una 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']

Una superación responde:

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

Un token se acepta una sola vez y dura dos minutos. Confírmalo cuando llegue el formulario, no más tarde, y nunca confirmes el mismo token dos veces.

Cuando no se supera

success es false y error-codes dice por qué:

La respuesta tiene la misma forma que las que dan reCAPTCHA y Turnstile, así que el código de servidor escrito para ellos normalmente solo necesita cambiar su dirección y su secreto.

Límites del plan

Una comprobación se cuenta cuando el primer paso de un visitante llega a una decisión. El límite mensual del plan lee las comprobaciones de tus propios sitios y formularios; nada de lo alojado con Xuda se cuenta. Superado un límite, el paso de IA se omite hasta el mes siguiente y todas las comprobaciones siguen funcionando, así que ningún formulario se rompe. Consulta Planes y facturación.

¿Qué te parece esta guía?

Última actualización: 16 de noviembre de 2026