Inicio rápido

Esta guía te ayudará a integrar el CAPTCHA de CaptchaLa en 5 minutos.

Míralo funcionar en 30 segundos

demo-v1.captcha.la — HTML + PHP puro, licencia MIT, ver el código fuente en cada página.

• popup.html — modo popup
• float.html — widget flotante
• bind.html — enlazar a un botón
• inline.html — integración en línea
• server-token.html — token emitido por el servidor (anti-replay)

1. Crear cuenta

Regístrate gratis en el panel de control.

Regístrate ahora →

2. Crear aplicación

Crea una aplicación en el panel para obtener tu App Key.

3. Instalar el SDK

Elige el método de instalación que prefieras.

<!-- CDN loader (recomendado): CDN con fallback automático, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# o vía npm
npm install captchala

4. Inicializar el CAPTCHA

Inicializa el componente CAPTCHA en tu página.

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. Verificación en el servidor

Valida el token en tu servidor.

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Comprueba siempre que data.valid === true y que data.action coincida con el escenario que esperas. Los pass tokens son de un solo uso; el mismo pt_xxx no puede validarse dos veces.

Modo de token emitido por el servidor (recomendado en producción)

Para acciones sensibles (inicio de sesión, registro, pago) recomendamos el flujo de token emitido por el servidor: tu backend solicita primero un server_token de corta duración, que el navegador utiliza después para inicializar el CAPTCHA. Esto evita el abuso si tu app_key se filtra.

Cuándo usarlo

• Recomendado: registro, inicio de sesión, restablecimiento de contraseña, pago, canje de puntos y cualquier endpoint que un atacante pueda automatizar.
• Opcional: formularios públicos informales, cuadros de búsqueda e interacciones de bajo valor donde la conveniencia es prioritaria.

1. El backend emite el server_token

Llama a /v1/server/challenge/issue desde tu propio servidor, usando las cabeceras X-App-Key y X-App-Secret. Nunca expongas estas cabeceras al navegador.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. El frontend renderiza CaptchaLa con el server_token

Pasa el token a tu componente CaptchaLa. El SDK lo reenvía al inicializar el desafío.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

Notas de seguridad

• Nunca incluyas el app_secret en código del frontend, aplicaciones móviles o repositorios públicos. Debe permanecer en el servidor.
• Activa «Requerir token de desafío emitido por el servidor» en el panel para rechazar cualquier desafío que se intente sin un server_token.
• Mantén el ttl corto (300s por defecto, 900s máximo) y prefiere max_uses=1 para reducir el impacto de una filtración de token.

Siguientes pasos

• SDK Web
• Referencia de la API