ממשק ה‑API

כל מסך במערכת מוגש מאותו API שסקריפט יכול לקרוא לו. הגרסה נמצאת בנתיב עצמו — /api/v1/… — מתחת לכתובת שההתקנה שלכם יושבת עליה.

מסמך המסלולים יושב בתוך המוצר

הרשימה המלאה של המסלולים, השדות והערכים היא הגדרות ← תיעוד ה‑API, ולא העמוד הזה. שלוש סיבות, וכולן מעשיות:

• המסמך נוצר מההתקנה עצמה, ולכן הוא תמיד תואם לגרסה שמותקנת אצלכם ולא לגרסה שאתר כלשהו מתאר.
• הוא כולל את הכתובת שאליה קריאת ניסיון תישלח בפועל — הכתובת הזאת תלויה בפריסה, ואתר חיצוני אינו יכול לדעת אותה.
• ברשת מנותקת אין אתר תיעוד חיצוני להפנות אליו.

המסך גם נותן כפתור הורדת openapi.json, כדי למסור את המסמך למי שכותב את האינטגרציה או להזין אותו לגנרטור קוד. הגישה אליו דורשת את ההרשאה docs.api, שאינה ניתנת כברירת מחדל: מפת המסלולים המלאה של ההתקנה שלכם היא מידע ארגוני, וארגון שרוצה למסור אותה לאנשי האינטגרציה מעניק את ההרשאה במפורש.

שתי דרכי הזדהות

הזדהות	איך היא נשלחת	מי משתמש בה
אסימון התחברות	Authorization: Bearer	הדפדפן. מונפק בכניסה למערכת, ותוקפו נקבע בהגדרות
אסימון גישה	X-API-Key, או אותה כותרת Bearer	סקריפטים ומערכות אוטומטיות

כל מסלול מקבל אחת מהשתיים — לא את שתיהן יחד.

אסימוני גישה

נוצרים בהגדרות ← אסימוני גישה, בשני סוגים:

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

ההיקפים הם מפתחות מקטלוג ההרשאות — אותו אוצר מילים, אותו עורך, בלי רשימה שנייה שצריך לתחזק.

מה כדאי לדעת לפני שמנפיקים

• הסוד מוצג פעם אחת בלבד, ביצירה ובריענון. אין ״הצג שוב״. אסימון שאבד — מרעננים, לא משחזרים.
• קידומת קבועה מסגירה את סוג האסימון (cc_pat_ לאישי, cc_svc_ לשירות), כך שאפשר לסרוק מאגר קוד או תיקיית סקריפטים ולמצוא אסימון שנשכח בפנים.
• ריענון מנפיק אסימון חדש עם אותו שם, אותו סוג ואותם היקפים, ומשאיר את הישן בתוקף לתקופת חסד שאתם קובעים — כי אי אפשר להחליף סוד בשתי מערכות באותו רגע. תקופת חסד אפס מנתקת את הישן מיד, וזה המצב של ״נחשף, לנתק עכשיו״.
• ריענון שמור לבעל האסימון בלבד. מי שמנהל אסימונים של אחרים יכול לבטל, לא לרענן — ביטול אומר בדיוק מה שהוא עושה, ואילו ריענון היה מעביר בשקט את האסימון לבעלות אחרת ומשאיר את האינטגרציה של המקורי מתה.
• תפוגה נבחרת ביצירה, ו״ללא תפוגה״ היא בחירה מפורשת ולא ברירת מחדל שנופלת עליה בהיסח הדעת.
• מכסה למשתמש, שמנהל מערכת יכול לשנות. אסימון בלי סיבה הוא אסימון שאיש לא יבטל.
• ניהול האסימונים עצמו סגור בפני אסימון. יצירה, שינוי היקפים וביטול נעשים רק מתוך התחברות רגילה — אחרת אסימון צר היה יכול לשכפל את עצמו רחב יותר.

בדיקה שאסימון עובד

GET /tokens/me הוא המסלול היחיד בניהול האסימונים שאסימון גישה עצמו רשאי לקרוא. הוא מחזיר מי הקורא ומה מותר לו, בלי לגעת בנתונים עסקיים — הקריאה שכדאי לשים ראשונה בסקריפט חדש.

תשובות ושגיאות

התשובות הן JSON. שגיאה מוחזרת בשדה detail:

קוד	משמעות
401	אין הזדהות תקפה — אסימון חסר, שגוי, פג או מבוטל
403	ההזדהות תקפה, אבל אין לה את ההרשאה לפעולה הזאת

ההפרדה הזאת נשמרת בכוונה: קוד אחד לשתי המשמעויות היה שולח כל תקלת הרשאה לבדיקה מחדש של האסימון.

[VERIFY] — מדיניות התאימות בין גרסאות ה‑API — מה נחשב שינוי שובר ומה לא — נקבעת מול צוות המוצר לפני שהיא מתפרסמת כאן.