Referencia de la API

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

URL base

https://apiv1.captcha.la

Una sola URL base

Todos los endpoints de esta página están en apiv1.captcha.la. Los hosts de reserva (bypass.*, fallbackapiv1.*) son destinos de failover a los que los SDK acuden por su cuenta durante una caída: apuntar tu integración a ellos devuelve service_online.

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.

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

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.

Endpoints de respaldo sin conexión

CaptchaLa mantiene un servicio de reserva en hosts separados para que la verificación siga funcionando cuando la API principal no está disponible:

Host	Lo llama	Función
`bypass.captchala.com` · `bypass.captcha-cdn.net`	SDK web / nativo (lado del usuario final)	Ejecuta la verificación sin conexión y emite un pass token `offline_` mientras la API principal está caída
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	SDK de servidor	Valida tokens `offline_` (`POST /api/validate`)

Son destinos de failover, no una API alternativa. Los SDK cambian a ellos por sí solos, únicamente después de que la API principal haya fallado de verdad, y vuelven en cuanto se recupera. Nada en tu configuración debe apuntar ahí.

`service_online` (HTTP 503)

json

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Lo recibes mientras la API principal está activa: el servicio de reserva solo atiende durante una caída. La petición llegó a bypass.* en lugar de a https://apiv1.captcha.la; corrige la URL, reintentar no sirve.

Causas habituales:

Causa	Solución
La opción `apiServer` del SDK apunta a un host bypass	Ponla en `https://apiv1.captcha.la` o quítala y deja que el SDK elija
`bypassServers` sobrescrito a mano	Quita la sobrescritura salvo que te hayamos dado hosts concretos
Un cliente HTTP propio copió una URL bypass (p. ej. de las devtools durante un incidente)	Llama a `https://apiv1.captcha.la` y deja el failover al SDK; el servicio de reserva no acepta tráfico normal de retos
Balanceador / proxy / DNS reescribiendo el host de la API	Devuelve el upstream a `apiv1.captcha.la`

TIP

La validación en servidor tampoco necesita el host de respaldo: POST /v1/validate en apiv1.captcha.la basta, y los SDK de servidor PHP / Go verifican los tokens offline_ contra la API de respaldo automáticamente.

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.
`service_online`	La petición llegó al servicio de respaldo sin conexión mientras la API principal está activa. Usa `https://apiv1.captcha.la` — consulta Endpoints de respaldo sin conexión.

Referencia de la API ​

URL base ​

Autenticación ​

API de validación del lado del servidor ​

Validación de token en el servidor ​

Token de desafío emitido por el servidor ​

Emitir el server token ​

Parámetros del cuerpo (form-urlencoded) ​

Inicializar el desafío ​

Endpoints de respaldo sin conexión ​

service_online (HTTP 503) ​

Códigos de error ​

Referencia de la API

URL base

Autenticación

API de validación del lado del servidor

Validación de token en el servidor

Token de desafío emitido por el servidor

Emitir el server token

Parámetros del cuerpo (form-urlencoded)

Inicializar el desafío

Endpoints de respaldo sin conexión

`service_online` (HTTP 503)

Códigos de error