סקירת API
תיעוד מלא של Cliqer API, הכולל נקודות קצה של REST ותקשורת בזמן אמת דרך WebSocket.
כתובת בסיס
https://cliqer.io/apiכל נקודות הקצה של ה-API יחסיות לכתובת הבסיס של שרת Cliqer שאליו מתבצע החיבור.
$BASE_URL בכתובת המופע של Cliqer (לדוגמה https://cliqer.io). בדוגמאות WebSocket יש להחליף את $WS_URL בכתובת wss://cliqer.io. דוגמאות TypeScript משתמשות בנתיבים יחסיים ופועלות ללא שינוי.אימות
Cliqer מבצע אימות באמצעות עוגיית סשן מסוג httpOnly (session_token), שמונפקת על ידי POST /api/auth/login. דפדפנים שולחים אותה אוטומטית; כלים שפועלים משרת לשרת שומרים אותה במאגר עוגיות (cookie jar). צוותים בתוכניות Studio 8K ו-Enterprise יכולים גם להנפיק מפתחות API לבקשות REST משרת לשרת, שנשלחים בתור Authorization: Bearer cliqer_<key> (ניהול מפתחות מחייב תוכנית Studio 8K או Enterprise). ה-WebSocket אינו מקבל מפתחות API: יש להתחבר אליו עם אסימון סשן.
# 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>
כמה נקודות קצה אינן דורשות סשן, למשל POST /api/licenses/validate, שהיא ציבורית.
חלקי ה-API
מחזור החיים של בקשה
תגובות שגיאה
כל נקודות הקצה מחזירות תגובות שגיאה סטנדרטיות:
| סטטוס | תיאור |
|---|---|
400 | Bad Request: פרמטרים חסרים או לא תקינים |
401 | Unauthorized: אין עוגיית סשן תקפה |
403 | Forbidden: אין מספיק הרשאות, או שהמקור (origin) אינו מורשה |
404 | Not Found: המשאב לא נמצא |
409 | Conflict: למשל, הגעה למגבלת המושבים בהפעלת רישיון |
429 | Too Many Requests: חריגה ממגבלת קצב הבקשות (ראו Retry-After) |
500 | Internal Server Error |
פורמט תגובת שגיאה:
{
"statusCode": 400,
"statusMessage": "Description of the error"
}
הגבלת קצב
רוב נקודות הקצה מוגבלות בקצב לפי כתובת ה-IP של הלקוח, באמצעות חלון קבוע של 60 שניות בשלוש רמות. כאשר בקשה חורגת מהמגבלה, השרת מגיב ב-429 Too Many Requests עם הכותרת Retry-After: 60. אין חסימה מדורגת/מעריכית, ולא מוחזרת כותרת X-RateLimit-Remaining.
| כותרת | תיאור |
|---|---|
Retry-After | מספר השניות עד לאיפוס החלון (60, נשלחת רק בתגובת 429) |
רמות הגבלת קצב
| רמה | בקשות / 60 שניות | חלה על |
|---|---|---|
| מחמירה | 5 | POST /api/licenses/validate ונקודות הקצה של ההתחברות (POST /api/auth/login, הרשמה, איפוס סיסמה, שלבי מפתח גישה ו-2FA) |
| רגילה | 30 | GET /api/licenses/status, POST /api/licenses/deactivate, GET /api/auth/me, POST /api/auth/logout |
| מקלה | 60 | נקודות קצה לקריאה בנפח גבוה |
שתי נקודות קצה מחילות מגבלה מחמירה נוספת לפי פרטי ההזדהות ולא לפי כתובת ה-IP, כך שאי אפשר להפציץ יעד אחד מכתובות רבות: POST /api/licenses/validate מוגבלת לפי license_key, ו-POST /api/auth/login מוגבלת לפי כתובת האימייל.
429 עד סוף חלון 60 השניות. מגבלות הקצב נאכפות על ידי השרת עצמו, לפני שנקודת הקצה מבצעת את עבודתה.