סקירת API

כל נקודת קצה REST של RolChat פועלת לפי חוזה אחד: אותה כתובת URL בסיסית, אותה מעטפת תגובה, אותו עימוד, אותו מבנה שגיאה. לומדים אותו פעם אחת, וכל משפחת נקודות קצה בתיעוד נקודות הקצה נקראת באותה צורה.

כתובת URL בסיסית וגרסאות

https://api.rolchat.com/api/v1/

הגרסה נמצאת בנתיב. הוספת שדות אופציונליים, נקודות קצה חדשות או פרמטרי שאילתה חדשים עם ברירות מחדל אינה שינוי שובר ואינה מעלה את הגרסה. שינויים שוברים יוצאים כ-v2, ונקודות קצה של v1 שהוצאו משימוש ממשיכות לעבוד לפחות שישה חודשים אחרי ההכרזה (ראו הוצאה משימוש).

אימות

שיטה	כותרת	משמשת ל
JWT bearer	Authorization: Bearer <access_token>	סשנים אינטראקטיביים (אפליקציית הווב, אפליקציות הנייד)
מפתח API	Authorization: Bearer rcp_<secret>	קריאות בין מכונות, מפתחות API של תוספים
חתימת HMAC	X-RolChat-Signature: sha256=…	Webhooks נכנסים מהמערכות שלכם, ראו Webhooks
ללא	-	נקודות קצה ציבוריות של הווידג’ט (/widget/…, /forms/…), בהיקף אתר ומקור

לאינטגרציות השתמשו במפתח API (אסימון גישה אישי). מפתחות נוצרים בהגדרות ← תוספים ← מפתחות RolChat API, מוצגים פעם אחת ונשמרים רק כגיבוב. מפתח לעולם אינו יכול לעשות יותר מהחבר שיצר אותו: ההיקפים שלו נבדקים מול ההרשאות הנוכחיות של אותו חבר בכל קריאה. ראו אימות לגבי משכי החיים של JWT, הכותרת X-Account-Id וסשנים בכמה חברות.

מעטפת התגובה

משאב יחיד:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

רשימה:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

תגובות בלי גוף (204 No Content אחרי מחיקה) עדיין נושאות את הכותרת X-Request-Id.

שגיאה:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code קריא למכונה ב-snake_case והוא הערך שלפיו מסתעפים; message הוא באנגלית ומיועד ליומנים. field ו-details מופיעים כשהם מועילים ולעולם אינם מכילים מידע אישי. ה-API לעולם אינו עונה 200 עם מערך errors: אם יש שגיאות, הסטטוס הוא 400 ומעלה. רשימת הקודים המלאה נמצאת בעמוד שגיאות.

עימוד

נקודות קצה של רשימות שעלולות לגדול משתמשות בעימוד באמצעות סמן. בקשו את העמוד הראשון בלי סמן, ואז העבירו חזרה את ה-next_cursor שקיבלתם, מילה במילה:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

• ברירת המחדל של limit היא 50 והתקרה 200; ערכים גדולים יותר נדחים עם 400 validation_failed.
• הסמנים אטומים ופגים אחרי 24 שעות (400 validation_failed עם code: cursor_expired).
• התוצאות עקביות מול תמונת המצב שנלקחה בעמוד הראשון: רשומות שנמחקו בין עמודים נעלמות, ורשומות חדשות מופיעות רק כשמתחילים מחדש בלי סמן.
• נשלחת גם כותרת Link עם rel="next" ו-rel="prev" ללקוחות שמעדיפים אותה.

אידמפוטנטיות

שלחו כותרת Idempotency-Key (‏UUID או ULID, עד 255 תווים) עם כל POST, PATCH או DELETE:

• הבקשה הראשונה עם מפתח רצה, והסטטוס והגוף שלה נשמרים ל-24 שעות.
• חזרה עם אותו מפתח ואותו גוף מחזירה את התגובה השמורה בלי להריץ שוב תופעות לוואי.
• חזרה עם אותו מפתח אבל גוף שונה נדחית עם 409 idempotency_key_conflict.

השתמשו בה לכל קריאה שיוצרת משהו עם תופעות לוואי: שליחת הודעה, אימייל או SMS, ביצוע שיחה, כל דבר שכרוך בחיוב. בקשות GET תמיד אידמפוטנטיות ומתעלמות מהכותרת.

מגבלות קצב

המגבלות נספרות לדקה ומשויכות לחשבון, למפתח API או למשתמש (לכתובת IP בנתיבים שאינם דורשים כניסה). התקרות כברירת מחדל:

דלי	מגבלת ברירת מחדל	בדקה
בקשות ללא כניסה (לפי IP)	60	לכל IP
משתמש מחובר (לוח הבקרה)	1,000	לכל משתמש
מפתח API	1,000	לכל מפתח
נקודות קצה ציבוריות של הווידג’ט	60 לכל מבקר, ו-600 לכל כתובת רשת	בדקה
כניסה (/auth/login)	5	לכל IP
Webhooks נכנסים	300	בדקה
שרת MCP	600	בדקה
נקודות קצה של OAuth	600	בדקה

התקרות הן ברירות המחדל של הפלטפורמה, והמפעיל יכול לשנות אותן; התוכנית שלכם אינה מכפילה אותן, ומגבלות Enterprise מוסכמות בחוזה. נקודות קצה מוגבלות קצב מחזירות:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

כשחוצים מגבלה התגובה היא 429 עם code: rate_limited במערך errors וכותרת Retry-After בשניות. המתינו את הזמן הזה לפני הקריאה הבאה. עשר התחברויות שנכשלו נועלות את החשבון ל-30 דקות.

גדלים וזמנים קצובים

קטגוריה	גוף בקשה מרבי	זמן קצוב בשרת
ברירת מחדל	1 MB	30 שנ’
הודעה עם קבצים מצורפים	25 MB	30 שנ’
ייבוא CSV	50 MB	מחזיר 202 ורץ ברקע
תמונות בבסיס הידע	10 MB	30 שנ’
Bulk API	10 MB	30 שנ’
חיפוש	1 MB	10 שנ’
בקשות AI	1 MB	60 שנ’
נקודות קצה של הווידג’ט	100 KB	30 שנ’

גופים גדולים מדי מקבלים 413 payload_too_large. שירות שחרג מהזמן עונה 504 עם code: upstream_timeout ורמז retry_after כשניסיון חוזר יכול לעזור.

סוגי תוכן, תאריכים ומזהים

• בקשות ותגובות הן application/json; charset=utf-8. העלאות קבצים משתמשות ב-multipart/form-data; ייצוא CSV מחזיר text/csv. UTF-8 לא תקין נדחה עם 400 validation_failed.
• חותמות זמן הן ISO-8601 ב-UTC עם דיוק של אלפיות שנייה: 2026-04-20T14:23:45.123Z. כל היסט ISO-8601 מתקבל בקלט ומנורמל ל-UTC.
• מזהים הם ULID או UUID אטומים. אין מזהים מספריים, וכתובות אימייל או מספרי טלפון לעולם אינם מופיעים ב-URL.

בידוד דיירים והרשאות

כל בקשה מאומתת רצה בתוך חשבון אחד. משאב ששייך לחשבון אחר, או לאתר שהתפקיד של הקורא אינו מכסה, עונה 404 not_found ולא 403, כדי שקיומן של רשומות לעולם לא ידלוף. אסימון תקין בלי ההרשאה הנדרשת (למשל contacts.delete) עונה 403 forbidden. חלק מההרשאות נושאות סיומת היקף (conversations.read:own, :team, :all) שמצמצמת את מה שרשימה מחזירה.

PATCH מקבל רק שדות ניתנים לכתיבה. id, account_id, created_at, updated_at ושדות מצב כמו resolved_at הם לקריאה בלבד; שליחת אחד מהם מחזירה 400 validation_failed עם details.forbidden_fields. שינויי מצב עוברים דרך פעולות ייעודיות כמו POST /tickets/:id/resolve.

כל כתיבה נרשמת ביומן הביקורת של החשבון.

כותרות ניטור

כל תגובה נושאת:

X-Request-Id: req_01HK…

רשמו ביומן את X-Request-Id. זה הדבר הראשון שהתמיכה מבקשת.

CORS

המקור של לוח הבקרה בדפדפן הוא https://app.rolchat.com. נקודות קצה ציבוריות של הווידג’ט מאפשרות כל מקור, או רק את המקורות שאתם מאמתים לאתר. קריאות שרת-לשרת עם מפתח API אינן כפופות ל-CORS.

הוצאה משימוש

1. השינוי מוכרז ביומן השינויים, ונקודת הקצה המושפעת מתחילה לשלוח Deprecation: true וכותרת Sunset עם תאריך ההסרה.
2. נקודות קצה ציבוריות ממשיכות לעבוד לפחות שישה חודשים אחרי ההכרזה.
3. הסרה מתבצעת רק בגרסה ראשית חדשה. בתוך v1 השינויים הם תוספתיים בלבד.

תקינות

כל שירות חושף /healthz (חיות) ו-/readyz (מוכנות).