Descripción general de la API
Documentación completa de la API de Cliqer, que abarca los endpoints REST y la comunicación en tiempo real por WebSocket.
URL base
https://cliqer.io/apiTodos los endpoints de la API son relativos a la URL base del servidor de Cliqer al que te conectas.
$BASE_URL por la URL de tu instancia de Cliqer (p. ej., https://cliqer.io). En los ejemplos de WebSocket, sustituye $WS_URL por wss://cliqer.io. Los ejemplos de TypeScript usan rutas relativas y funcionan sin modificaciones.Autenticación
Cliqer se autentica con una cookie de sesión httpOnly (session_token), generada por POST /api/auth/login. Los navegadores la envían automáticamente; las herramientas de servidor a servidor la guardan en un almacén de cookies. Los equipos de Studio 8K y Enterprise también pueden generar claves de API para solicitudes REST de servidor a servidor, enviadas como Authorization: Bearer cliqer_<key> (la gestión de claves requiere el plan Studio 8K o Enterprise). El WebSocket no acepta claves de API: conéctalo con un token de sesión.
# The session cookie is set by /api/auth/login and sent on every subsequent request
Cookie: session_token=YOUR_SESSION_TOKEN
# Or authenticate a server-to-server REST request with a team API key
Authorization: Bearer cliqer_<key>
Algunos endpoints no necesitan sesión, como POST /api/licenses/validate, que es público.
Secciones de la API
Ciclo de vida de una solicitud
Respuestas de error
Todos los endpoints devuelven respuestas de error estándar:
| Estado | Descripción |
|---|---|
400 | Solicitud incorrecta: faltan parámetros o no son válidos |
401 | No autorizado: no hay ninguna cookie de sesión válida |
403 | Prohibido: permisos insuficientes u origen no permitido |
404 | No encontrado: no se ha encontrado el recurso |
409 | Conflicto: p. ej., se ha alcanzado el límite de puestos de activación de la licencia |
429 | Demasiadas solicitudes: se ha superado el límite de frecuencia (consulta Retry-After) |
500 | Error interno del servidor |
Formato de la respuesta de error:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
Limitación de frecuencia
La mayoría de los endpoints tienen un límite de frecuencia por IP de cliente, con una ventana fija de 60 segundos y tres niveles. Cuando una solicitud supera el límite, el servidor responde 429 Too Many Requests con una cabecera Retry-After: 60. No hay bloqueo progresivo/exponencial y no se devuelve ninguna cabecera X-RateLimit-Remaining.
| Cabecera | Descripción |
|---|---|
Retry-After | Segundos hasta que se reinicia la ventana (60, solo se envía con un 429) |
Niveles de límite de frecuencia
| Nivel | Solicitudes / 60 s | Se aplica a |
|---|---|---|
| Estricto | 5 | POST /api/licenses/validate y los endpoints de inicio de sesión (POST /api/auth/login, registro, restablecimiento de contraseña, pasos de llave de acceso y 2FA) |
| Estándar | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| Relajado | 60 | Endpoints de lectura de alto volumen |
Dos endpoints aplican un segundo límite Estricto basado en la credencial en lugar de en la IP, para que no se pueda atacar un mismo objetivo desde muchas direcciones: POST /api/licenses/validate se basa en la license_key y POST /api/auth/login, en la dirección de correo electrónico.
429 durante el resto de la ventana de 60 segundos. El propio servidor impone los límites de frecuencia antes de que el endpoint haga su trabajo.