Przegląd API
Pełna dokumentacja API Cliqer obejmująca endpointy REST i komunikację w czasie rzeczywistym przez WebSocket.
Bazowy URL
https://cliqer.io/apiWszystkie endpointy API są względne wobec bazowego URL serwera Cliqer, z którym się łączysz.
$BASE_URL adresem URL swojej instancji Cliqer (np. https://cliqer.io). W przykładach WebSocket zastąp $WS_URL wartością wss://cliqer.io. Przykłady w TypeScript używają ścieżek względnych i działają bez żadnych zmian.Uwierzytelnianie
Cliqer uwierzytelnia za pomocą ciasteczka sesji httpOnly (session_token), tworzonego przez POST /api/auth/login. Przeglądarki wysyłają je automatycznie, a narzędzia serwer-serwer przechowują je w cookie jar. Zespoły w planach Studio 8K i Enterprise mogą też generować klucze API do żądań REST serwer-serwer, wysyłane jako Authorization: Bearer cliqer_<key> (zarządzanie kluczami wymaga planu Studio 8K lub Enterprise). WebSocket nie przyjmuje kluczy API: łącz się z nim za pomocą tokenu sesji.
# 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>
Kilka endpointów nie wymaga sesji, np. POST /api/licenses/validate, który jest publiczny.
Sekcje API
Cykl życia żądania
Odpowiedzi z błędami
Wszystkie endpointy zwracają standardowe odpowiedzi z błędami:
| Status | Opis |
|---|---|
400 | Bad Request: brak parametrów lub nieprawidłowe parametry |
401 | Unauthorized: brak ważnego ciasteczka sesji |
403 | Forbidden: niewystarczające uprawnienia lub niedozwolone źródło (origin) |
404 | Not Found: nie znaleziono zasobu |
409 | Conflict: np. osiągnięto limit stanowisk przy aktywacji licencji |
429 | Too Many Requests: przekroczono limit żądań (zobacz Retry-After) |
500 | Internal Server Error |
Format odpowiedzi z błędem:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
Limity żądań
Większość endpointów ma limit żądań na adres IP klienta, liczony w stałym oknie 60 sekund na trzech poziomach. Gdy żądanie przekroczy limit, serwer odpowiada 429 Too Many Requests z nagłówkiem Retry-After: 60. Nie ma progresywnego/wykładniczego blokowania, a nagłówek X-RateLimit-Remaining nie jest zwracany.
| Nagłówek | Opis |
|---|---|
Retry-After | Liczba sekund do zresetowania okna (60, wysyłany tylko przy 429) |
Poziomy limitów żądań
| Poziom | Żądania / 60 s | Zastosowanie |
|---|---|---|
| Ścisły | 5 | POST /api/licenses/validate i endpointy logowania (POST /api/auth/login, rejestracja, reset hasła, kroki klucza dostępu i 2FA) |
| Standardowy | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| Łagodny | 60 | Endpointy odczytu o dużym natężeniu ruchu |
Dwa endpointy stosują drugi limit Ścisły, powiązany z danymi uwierzytelniającymi zamiast z adresem IP, więc jednego celu nie da się zasypywać żądaniami z wielu adresów: POST /api/licenses/validate liczy limit według license_key, a POST /api/auth/login według adresu e-mail.
429 do końca 60-sekundowego okna. Limity żądań są egzekwowane przez sam serwer, zanim endpoint wykona swoją pracę.