פורטלים, API ו-MCP

פורטלים, API ו-MCP: מדריך צעד אחרי צעד במערכת Eolipa.

למי: יועצי הטמעה ומנהלי פרויקטים בחברות הטמעהזמן קריאה: כ-3 דקותהדוגמאות מחברת ההדגמה, על נתוני דוגמה

→ מדריך המטמיע: תוכן העניינים

9.1 פורטל לקוחות

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

  1. "מחולל פורטלים" ← "פורטל חדש".
  2. בוחרים את הצד: "לקוחות".
  3. "יצירת הפורטל".

מה נבדק במסד:

  • לפורטל יש תפקיד מסד משלו, ומדיניות RLS (eolipa_pt_*) לכל טבלה שהוא חושף: לקוחות, הזמנות, הצעות, חשבוניות ושורות.
  • לתפקיד הפורטל אין הרשאת כתיבה לאף טבלה. גם באג בממשק הפורטל לא יאפשר לו לשנות נתונים.
  • כל לקוח רואה רק את הרשומות שלו, כי הסינון נעשה במסד ולא בממשק.

מה מגדירים אחרי היצירה:

חלקמה קובעים
"דפי הפורטל"אילו דפים, ובאיזה סדר. הדף הראשון הוא עמוד הבית של הפורטל. גוררים לסידור
"מה מוצג"אילו שדות בכל דף. 🔒 = שדה שלא נחשף בפורטל. כשמוסיפים שדה כספי, מופיעה אזהרה: "זה שדה כספי - הצד יראה אותו בפורטל. השינוי נרשם ביומן"
מסננים"ברירת מחדל: מוצגים רק מסמכים שהופקו". אפשר גם "להסתיר רשומות בסטטוס"
"מה הצד יכול לעשות"פעולות שמותרות לצד החיצוני
"מראה וכניסה""טקסט פתיחה", מיתוג, ואופן הכניסה ("כניסה עם")
"אפליקציה"התקנה כאפליקציה בטלפון, עם QR

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

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

רישוי: פורטלים כלולים לפי החבילה. אם הרישיון לא כולל פורטלים, המחולל אומר זאת.

9.2 מחולל ה-API

"מחולל API" בונה ממשק לשותף: מה מותר לו לקרוא ולכתוב, ובאילו תנאים.

  1. "מחולל API" ← כותבים במשפט מה השותף צריך, למשל "גישה לקריאה של לקוחות וחשבוניות לרואה החשבון", ← "בנה תוכנית". או מגדירים ידנית ב"הגדרת הממשק".
  2. בודקים את ההרשאות: אילו מסכים, אילו שדות, קריאה או כתיבה. "הוכחת הרשאה מינימלית" מראה שהממשק לא מקבל יותר ממה שביקשתם.
  3. אבטחה (רשות):
    • "דרוש חתימה על כל בקשה (זיהוי כפול)": HMAC-SHA256 על זמן, nonce, נתיב וגיבוב הגוף;
    • כתובות IP מותרות (IPv4 או CIDR);
    • "בתוקף עד": אחרי התאריך כל מפתח של הממשק נדחה.
  4. יוצרים מפתח. "אישורי הגישה החדשים - מוצגים פעם אחת". במסד נשמר רק גיבוב.
  5. "דוגמאות curl ו-JSON" נותן לשותף דוגמה מוכנה.

איך זה נאכף: לכל ממשק יש תפקיד במסד. ההרשאות נאכפות במסד ולא בשכבת ה-API. ההגדרה עצמה נשמרת כמטא-דאטה בשכבת הלקוח, בלי המפתחות.

Webhooks (הודעה ליעד חיצוני כשרשומה נוצרת או משתנה): ב"יעדים חיצוניים" במחולל האוטומציות (פרק 5.6).

9.3 סוכנים חיצוניים (MCP)

"חיבור סוכנים חיצוניים (MCP)" מחבר סוכן AI חיצוני (לקוח MCP שולחני, עורך קוד, עוזר AI בענן ועוד) ל-Eolipa, עם הרשאות של משתמש מסוים.

  1. "אסימון חדש לסוכן חיצוני" ← בוחרים כלים (או משפחות כלים), תוקף (מ-15 דקות עד 3 חודשים), וכתובות IP מותרות (רשות).
  2. "קריאה בלבד" נאכף בשרת.
  3. כתיבה מסוכן חיצוני הופכת לבקשת אישור בתיבת המשימות. בקרה "אישור אנושי לכתיבה מסוכן חיצוני" פועלת על כל הכלים.
  4. אסימון עם כתיבה דורש "אישור כפול": אדם אחר, מנהל שאינו הבעלים, מאשר אותו.
  5. את האסימון מעתיקים רק ברגע ההנפקה. כל קריאה נרשמת ביומן.

הוראות החיבור לכל כלי: מדריך ה-MCP.

9.4 חיבורים ומקורות נתונים חיצוניים

  • "חיבורים חיצוניים": גישה של תוכנה חיצונית לנתונים: אסימון לכל תוכנה, הרשאה לכל מסך (קריאה, יצירה, עדכון), החרגת שדות, הגנות (HMAC, IP, mTLS, תוקף וקצב), אימות נוסף כשפותחים כתיבה, ויומן לכל קריאה.
  • "מקורות נתונים חיצוניים": משיכת נתונים ממקור ציבורי מתבנית (למשל בנק ישראל או הלמ"ס). מנהל המערכת רואה כרטיס אישור עם מה שיוצא החוצה ו-5 שורות ראשונות מניסיון, ויש גם העלאת קובץ ידנית. באותו אזור רושמים גם שרתי MCP חיצוניים שהסוכן של Eolipa יכול להשתמש בהם, וכל כלי מאושר בנפרד.
  • חיבור למערכת הקודמת להסבה ולשאיבות חוזרות: פרק 10.
  • "אבטחה וחיבורים": המקום המרכזי למדיניות האבטחה: אימות דו-שלבי, חיבורים ואסימונים.

9.5 טיפים להטמעה

  • שותף אחד = ממשק אחד. כך אפשר לבטל גישה לשותף בלי לפגוע באחרים, והיומן אומר מי קרא מה.
  • מתחילים בקריאה בלבד. כתיבה מוסיפים רק כשיש צורך ברור, ועם חתימה על כל בקשה.
  • הפורטל לא מחליף את ה-API. פורטל הוא לאנשים (לקוח, ספק, עובד). API הוא למערכות.

הכי טוב ללמוד על המערכת עצמה.

התרגילים במדריכים מתאימים לסביבת ההדגמה, על נתוני דוגמה.

נתוני דוגמה · 7 ימים · ללא עלות · הרשמה ללא כרטיס אשראי