Επισκόπηση API
Πλήρης τεκμηρίωση για το Cliqer API, που καλύπτει τα REST endpoints και την επικοινωνία πραγματικού χρόνου μέσω WebSocket.
Βασικό URL
https://cliqer.io/apiΌλα τα endpoints του API είναι σχετικά με το βασικό URL του διακομιστή Cliqer στον οποίο συνδέεστε.
$BASE_URL με το URL της δικής σας εγκατάστασης Cliqer (π.χ. https://cliqer.io). Στα παραδείγματα WebSocket, αντικαταστήστε το $WS_URL με wss://cliqer.io. Τα παραδείγματα TypeScript χρησιμοποιούν σχετικές διαδρομές και λειτουργούν χωρίς τροποποίηση.Έλεγχος ταυτότητας
Το Cliqer ελέγχει την ταυτότητα μέσω ενός httpOnly cookie συνεδρίας (session_token), το οποίο δημιουργείται από το POST /api/auth/login. Τα προγράμματα περιήγησης το στέλνουν αυτόματα, ενώ τα εργαλεία διακομιστή προς διακομιστή το διατηρούν σε ένα cookie jar. Οι ομάδες Studio 8K και Enterprise μπορούν επίσης να δημιουργούν κλειδιά API για αιτήματα REST διακομιστή προς διακομιστή, τα οποία αποστέλλονται ως Authorization: Bearer cliqer_<key> (η διαχείριση κλειδιών απαιτεί το πακέτο Studio 8K ή Enterprise). Το WebSocket δεν δέχεται κλειδιά API: συνδέστε το με ένα token συνεδρίας.
# 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>
Ορισμένα endpoints δεν απαιτούν συνεδρία, όπως το POST /api/licenses/validate, το οποίο είναι δημόσιο.
Ενότητες API
Κύκλος ζωής αιτήματος
Αποκρίσεις σφάλματος
Όλα τα endpoints επιστρέφουν τυπικές αποκρίσεις σφάλματος:
| Κατάσταση | Περιγραφή |
|---|---|
400 | Bad Request: λείπουν παράμετροι ή δεν είναι έγκυρες |
401 | Unauthorized: δεν υπάρχει έγκυρο cookie συνεδρίας |
403 | Forbidden: ανεπαρκή δικαιώματα ή μη επιτρεπόμενη προέλευση |
404 | Not Found: ο πόρος δεν βρέθηκε |
409 | Conflict: π.χ. συμπληρώθηκε το όριο θέσεων ενεργοποίησης της άδειας |
429 | Too Many Requests: υπέρβαση του ορίου ρυθμού αιτημάτων (δείτε Retry-After) |
500 | Internal Server Error |
Μορφή απόκρισης σφάλματος:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
Περιορισμός ρυθμού αιτημάτων
Τα περισσότερα endpoints έχουν όριο ρυθμού αιτημάτων ανά IP πελάτη, με σταθερό παράθυρο 60 δευτερολέπτων σε τρία επίπεδα. Όταν ένα αίτημα υπερβαίνει το όριο, ο διακομιστής απαντά με 429 Too Many Requests και την κεφαλίδα Retry-After: 60. Δεν υπάρχει προοδευτικός/εκθετικός αποκλεισμός και δεν επιστρέφεται κεφαλίδα X-RateLimit-Remaining.
| Κεφαλίδα | Περιγραφή |
|---|---|
Retry-After | Δευτερόλεπτα έως την επαναφορά του παραθύρου (60, αποστέλλεται μόνο με 429) |
Επίπεδα ορίου ρυθμού
| Επίπεδο | Αιτήματα / 60s | Εφαρμόζεται σε |
|---|---|---|
| Αυστηρό | 5 | POST /api/licenses/validate και τα endpoints σύνδεσης (POST /api/auth/login, εγγραφή, επαναφορά κωδικού πρόσβασης, βήματα κλειδιού πρόσβασης και 2FA) |
| Τυπικό | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| Χαλαρό | 60 | Endpoints ανάγνωσης υψηλού όγκου |
Δύο endpoints εφαρμόζουν ένα δεύτερο Αυστηρό όριο με βάση το διαπιστευτήριο αντί για την IP, ώστε ένας στόχος να μην μπορεί να βομβαρδιστεί με αιτήματα από πολλές διευθύνσεις: το POST /api/licenses/validate χρησιμοποιεί ως κλειδί το license_key και το POST /api/auth/login τη διεύθυνση email.
429 για το υπόλοιπο του παραθύρου 60 δευτερολέπτων. Τα όρια ρυθμού αιτημάτων επιβάλλονται από τον ίδιο τον διακομιστή, πριν το endpoint εκτελέσει την εργασία του.