Panoramica dell'API
Documentazione completa dell'API di Cliqer, che copre gli endpoint REST e la comunicazione in tempo reale via WebSocket.
URL di base
https://cliqer.io/apiTutti gli endpoint dell'API sono relativi all'URL di base del server Cliqer a cui ti connetti.
$BASE_URL con l'URL della tua istanza Cliqer (ad es. https://cliqer.io). Negli esempi WebSocket, sostituisci $WS_URL con wss://cliqer.io. Gli esempi TypeScript usano percorsi relativi e funzionano senza modifiche.Autenticazione
Cliqer esegue l'autenticazione tramite un cookie di sessione httpOnly (session_token), generato da POST /api/auth/login. I browser lo inviano automaticamente; gli strumenti da server a server lo conservano in un cookie jar. I team Studio 8K ed Enterprise possono anche generare chiavi API per le richieste REST da server a server, inviate come Authorization: Bearer cliqer_<key> (la gestione delle chiavi richiede il piano Studio 8K o Enterprise). Il WebSocket non accetta chiavi API: per connetterti usa un token di sessione.
# 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>
Alcuni endpoint non richiedono una sessione, ad esempio POST /api/licenses/validate, che è pubblico.
Sezioni dell'API
Ciclo di vita delle richieste
Risposte di errore
Tutti gli endpoint restituiscono risposte di errore standard:
| Stato | Descrizione |
|---|---|
400 | Bad Request - Parametri mancanti o non validi |
401 | Unauthorized - Nessun cookie di sessione valido |
403 | Forbidden - Autorizzazioni insufficienti oppure origine non consentita |
404 | Not Found - Risorsa non trovata |
409 | Conflict - Ad es. raggiunto il limite di postazioni per l'attivazione della licenza |
429 | Too Many Requests - Limite di frequenza superato (vedi Retry-After) |
500 | Internal Server Error |
Formato della risposta di errore:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
Limitazione della frequenza
La maggior parte degli endpoint applica un limite di frequenza per IP del client, con una finestra fissa di 60 secondi su tre livelli. Quando una richiesta supera il limite, il server risponde 429 Too Many Requests con un'intestazione Retry-After: 60. Non è previsto alcun blocco progressivo/esponenziale e non viene restituita alcuna intestazione X-RateLimit-Remaining.
| Intestazione | Descrizione |
|---|---|
Retry-After | Secondi mancanti al ripristino della finestra (60, inviata solo con un 429) |
Livelli di limitazione della frequenza
| Livello | Richieste / 60 s | Si applica a |
|---|---|---|
| Rigoroso | 5 | POST /api/licenses/validate e gli endpoint di accesso (POST /api/auth/login, registrazione, reimpostazione della password, passaggi di passkey e 2FA) |
| Standard | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| Moderato | 60 | Endpoint di lettura ad alto volume |
Due endpoint applicano un secondo limite Rigoroso basato sulla credenziale anziché sull'IP, così un singolo obiettivo non può essere bersagliato da molti indirizzi diversi: POST /api/licenses/validate usa come chiave la license_key e POST /api/auth/login l'indirizzo email.
429 per il resto della finestra di 60 secondi. I limiti di frequenza vengono imposti dal server stesso, prima che l'endpoint esegua la propria elaborazione.