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 (中文)
• Go — go get github.com/Captcha-La/captchala-go · README

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.

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

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

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

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.

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

{
  "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.