קטלוג הפירוטים ב-API ובעוזר ה-AI
איך משתמשים בקטלוג הפירוטים מחוץ למסך: קריאת הקטלוג ב-API הציבורי, יצירת מרכיב מחיר לפי פריט (פירוט מהתבנית, סכום ומע״מ מברירות המחדל), קבוצות תשלומים, עדכון ושינוי פריט, והשימוש בקטלוג בצ׳אט ה-AI ובחיבור MCP.
הקטלוג פועל גם כשמרכיבי מחיר נוצרים מחוץ למסך: ממערכת חיצונית דרך ה-API, או מעוזר ה-AI. כך גם מרכיבים כאלה מקבלים את הנוסח של המשרד ומשויכים למוצר.
ב-API הציבורי
קריאת הקטלוג
GET /price-catalog מחזיר את הפריטים הפעילים. לכל פריט: מזהה, שם, תבנית הפירוט, סכום ברירת המחדל, הגדרת המע״מ, העלות הנלווית, סוגי השומה שהוא ברירת המחדל עבורם, והאם הוא פריט ברירת המחדל. בנוסף מוחזר requireCatalogItem, שמציין אם הארגון מחייב פריט בכל מרכיב. עם includeArchived=true מוחזרים גם פריטים בארכיון.
יצירת מרכיב מחיר לפי פריט
ביצירת מרכיב מחיר (POST /project/{projectId}/price) שולחים catalogItemId:
- בלי
title- הפירוט נבנה מתבנית הפריט, והמרכיב אוטומטי: הוא יתעדכן לפי פרטי הפרויקט. - עם
title- הפירוט הוא הטקסט ששלחתם (ידני), והמרכיב עדיין משויך לפריט. - בלי
sum- נלקח סכום ברירת המחדל של הפריט. - בלי
excludeVatאוextraCost, או עםnull- הערכים נלקחים מהפריט. פריט שהמע״מ שלו לפי ברירת המחדל הארגונית יוצר ב-API מרכיב כולל מע״מ, כמו כל מרכיב שנוצר ב-API בליexcludeVat: ברירת המחדל הארגונית חלה על מרכיבים שנוספים במסך.
פריט בארכיון, או מזהה שאינו בקטלוג, נדחים עם הודעת שגיאה.
כשהארגון מחייב פריט (requireCatalogItem בתשובת הקטלוג), מרכיב חדש בלי catalogItemId נדחה. כך גם עדכון שמשנה סכום או פירוט של מרכיב בלי פריט, או שמסיר מרכיב מהפריט שלו. מרכיבים ישנים בלי פריט אפשר לעדכן בשדות אחרים, כמו תאריך.
קבוצת תשלומים
מרכיבים עם אותו installmentGroupId (מזהה UUID שאתם בוחרים) הם תשלומים של אותו תשלום, וממוספרים אוטומטית לפי הסדר, גם כשנשלח להם title.
עדכון
- שליחת
titleשונה מהקיים הופכת את הפירוט לידני. שליחת אותוtitleבחזרה, למשל אחרי קריאה, לא משנה דבר. - שליחת
catalogItemIdאחר בליtitleמעבירה את המרכיב לתבנית של הפריט החדש. nullב-catalogItemIdמסיר רק את השיוך לפריט: הפירוט לא משתנה, ומרכיב אוטומטי ממשיך להתעדכן לפי הפרויקט. כדי להפוך אותו לידני, שולחיםtitleחדש.nullב-installmentGroupIdמוציא את המרכיב מקבוצת התשלומים.- מרכיב שכבר נכלל בחשבון עסקה או בתקבול אינו ניתן לעדכון ב-API, גם לא לשיוך לפריט. שיוך כזה עושים בעורך מרכיבי המחיר.
בתשובות של מרכיב מחיר מופיעים גם catalogItemId, installmentGroupId ו-titleAuto (true כשהפירוט נבנה מתבנית). המפרט המלא נמצא בתיעוד למפתחים שבלשונית API.
בעוזר ה-AI
בצ׳אט ה-AI ובחיבור MCP חיצוני, העוזר קורא את הקטלוג (הכלי get_price_catalog) לפני שהוא יוצר מרכיב מחיר, ויוצר את המרכיב לפי הפריט המתאים, עם הנוסח והסכום של המשרד.
לדוגמה, בבקשה "תוסיף לפרויקט 1042 שכר טרחה לשומה ונסיעות" העוזר בוחר את פריטי הקטלוג המתאימים, והפירוט נבנה מפרטי הפרויקט.
יצירת מרכיבי מחיר ועדכונם בעוזר זמינים למנהלים בלבד, כמו שאר הפעולות הכספיות, ובתנאי שהכלים create_price ו-update_price פעילים ברשימת הכלים של הארגון. קריאת הקטלוג זמינה תמיד.
חזרה לסקירת קטלוג הפירוטים.