---
title: Inicio rápido
---

# Inicio rápido

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

::: tip Míralo funcionar en 30 segundos
[demo-v1.captcha.la](https://demo-v1.captcha.la) — HTML + PHP puro, licencia MIT, ver el código fuente en cada página.

- [popup.html](https://demo-v1.captcha.la/popup.html) — modo popup
- [float.html](https://demo-v1.captcha.la/float.html) — widget flotante
- [bind.html](https://demo-v1.captcha.la/bind.html) — enlazar a un botón
- [inline.html](https://demo-v1.captcha.la/inline.html) — integración en línea
- [server-token.html](https://demo-v1.captcha.la/server-token.html) — token emitido por el servidor (anti-replay)
:::


## 1. Crear cuenta

Regístrate gratis en el panel de control.

[Regístrate ahora →](https://dash.captcha.la/register)

## 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.

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

```bash
# o vía npm
npm install captchala
```

## 4. Inicializar el CAPTCHA

Inicializa el componente CAPTCHA en tu página.

```html
<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.

```bash
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>" }
```

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "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) {#server-token}

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.

```bash
# 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.

```js
// 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](/es/web-sdk)
- [Referencia de la API](/es/api-reference)