---
title: Referencia de la API
---

# Referencia de la API

CaptchaLa proporciona una API RESTful para todas las integraciones del lado servidor.

## URL base

```
https://apiv1.captcha.la
```

## Autenticación

Todas las solicitudes a la API requieren cabeceras de autenticación:

```
X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

::: warning
`X-App-Secret` es solo del lado del servidor. Nunca lo expongas a navegadores, aplicaciones móviles o repositorios públicos.
:::

## API de validación del lado del servidor

> 💡 **Usa un SDK de servidor para evitar el código repetitivo.** Envuelve el endpoint, gestiona los reintentos y expone errores tipados:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

Después de que el usuario supere el CAPTCHA en el frontend, tu servidor debe validar el token devuelto por el SDK. A continuación se muestran los endpoints de validación del lado del servidor.

### Validación de token en el servidor

Valida el pass_token del SDK del frontend (con prefijo pt_). Requiere las cabeceras X-App-Key y X-App-Secret.

```bash
POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }
```

`client_ip` es **opcional pero recomendado**: la IP del usuario final tomada de tu solicitud entrante, usada para comprobaciones de riesgo adicionales. Puedes omitirlo sin problema.

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}
```

El objeto `captcha_args` es **solo informativo** (para tus registros / análisis de riesgo):

| Campo | Descripción |
| --- | --- |
| `platform` | Plataforma desde la que se resolvió el desafío. |
| `user_ip` | IP registrada en el momento de la resolución. |
| `referer` | URL de referencia de la página del desafío. |
| `pkg` | Identificador de paquete de la app (móvil), si aplica. |
| `solved_at` | Marca de tiempo Unix de la resolución. |
| `risk_score` | Puntuación de riesgo de la sesión de resolución. |

::: tip
Verifica que `data.valid === true` **y** que `data.action` coincide con el escenario esperado
(rechaza si se presenta un token de un flujo `pay` en `/login`). Los tokens son de un solo uso.
:::

## Token de desafío emitido por el servidor {#server-token}

Emite un server_token de corta duración desde tu backend. El navegador pasa este token al inicializar un desafío, demostrando que la solicitud se originó en tu servidor de confianza.

### Emitir el server token

Llama a este endpoint solo desde tu propio servidor. Requiere X-App-Key + X-App-Secret. La respuesta contiene un server_token (prefijo sct_) que el frontend reenvía al inicializar el desafío.

```bash
POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4
```

```json
{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}
```

#### Parámetros del cuerpo (form-urlencoded)

| Campo | Descripción |
| --- | --- |
| `action` | Escenario de negocio, por ejemplo login, register, pay. Debe coincidir con la acción usada al inicializar el desafío. |
| `ttl` | Duración del token en segundos. Por defecto 300, máximo 900. |
| `max_uses` | Número máximo de usos del token. Por defecto 10. |
| `bind_ip` | Vincula el token a una IP de cliente. Se rechaza la inicialización desde otra IP. |
| `bind_device_id` | Vincula el token a un ID de dispositivo específico. |
| `bind_fingerprint` | Vincula el token a una huella digital de navegador concreta. |

### Inicializar el desafío

Llamado por el SDK para iniciar un desafío CAPTCHA. Acepta un server_token opcional emitido por /v1/server/challenge/issue.

| Campo | Descripción |
| --- | --- |
| `app_key` | Tu App Key público. |
| `action` | Escenario de negocio. Debe coincidir con la acción usada al emitir el server_token. |
| `server_token` | Opcional; obligatorio cuando la aplicación tiene server_token_required = true. |

::: info
Si server_token_required está activado para esta aplicación en el panel, la inicialización del desafío rechazará las solicitudes que no incluyan un server_token válido.
:::

## Códigos de error

| Código | Descripción |
| --- | --- |
| `invalid_app_key` | App Key no válida |
| `invalid_app_secret` | App Secret no válido |
| `challenge_expired` | Desafío caducado |
| `challenge_not_found` | Desafío no encontrado |
| `invalid_answer` | Respuesta no válida |
| `token_expired` | Token caducado |
| `token_already_used` | Token ya utilizado |
| `token_not_found` | Token no encontrado |
| `quota_exceeded` | Cuota superada |
| `rate_limited` | Límite de tasa alcanzado |
| `rate_limit_exceeded` | Demasiadas solicitudes de emisión para esta aplicación. Espera y reintenta. |