כלי הצעות מחיר

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

שלושה כלים: אחד מוצא תבניות, אחד כותב תבנית, אחד מפיק מסמך.

Get-Price-Quote-Templates

בלי פרמטרים. מחזיר objectId ו‑Name לכל תבנית — ולא את ה‑HTML.

JSON

[ { "objectId": "pdft012345", "Name": "הצעת מחיר כולל מע\"מ" },
  { "objectId": "pdft067890", "Name": "תבנית קלאסית-מקצועית" } ]

כדי לקרוא את התוכן עצמו — Get-Data על טבלת PDFTemplate:

JSON

{ "table": "PDFTemplate", "objectId": "pdft012345" }

keys בלי HTML — והתשובה נראית תקינה

שדה ה‑HTML חוזר רק כשלא מעבירים keys בכלל, או כשהוא כלול בהם במפורש (keys: ["Name"] מחזיר שורה בלי HTML; keys: ["Name","HTML"] מחזיר אותו). בטבלה הזו הכי פשוט לשלוף את כל השדות.

שימו לב שהטבלה PDFTemplate מכילה גם את תבניות המסמכים של MyBooks (Invoice, Receipt, Invoice-Receipt ועוד), עם TypeId שמצביע ל‑PDFTemplateTypes (“מסמכי מקור” / “הצעות מחיר”). Get-Price-Quote-Templates מחזיר רק את תבניות ההצעות; Get-Data על הטבלה מחזיר את כולן.

יש גם משאב MCP בשם price-quote-example (URI: price-quote-example://main, מתגלה ב‑resources/list ונקרא ב‑resources/read) שמחזיר תבנית לדוגמה עם כל ה‑placeholders — כ‑4KB של HTML עם windowDiv, בלוק חתימה, data-repeat על <tr> ובלי שום <script>. זו הדרך המהירה ללמוד את הפורמט לפני שכותבים אחת חדשה. על משאבי MCP והדרך לקרוא אותם — כלי קבצים.

Create-Update-Price-Quote-Template

יוצר תבנית חדשה, או מעדכן קיימת כשמעבירים objectId.

הפרמטר	טיפוס	חובה	המשמעות
templateName	String	✔	שם התבנית כפי שיופיע ברשימה
templateContent	String	✔	ה‑HTML המלא
objectId	String		מזהה תבנית קיימת ⇒ עדכון. בלעדיו — נוצרת תבנית חדשה

התשובה ביצירה: { "objectId": "CdbeHAOSBL", "createdAt": "…" }; בעדכון: { "objectId": "…", "updatedAt": "…" }. objectId שאינו קיים ⇒ Error: Object not found.. תבנית שנוצרת דרך הכלי מקבלת אוטומטית TypeId של “הצעות מחיר”, ולכן מופיעה מיד ב‑Get-Price-Quote-Templates.

מגבלה ידועה — התבנית נשמרת בלי שום בדיקה של חוזה ה‑HTML

ארבעת הכללים שלמטה הם דרישות של מנוע ההפקה ושל עמוד החתימה, לא ולידציה של הכלי: תבנית בלי windowDiv, בלי בלוק חתימה, או עם <script> נשמרת בהצלחה, מופיעה ברשימה, ואפילו מפיקה הצעה. הטעות מתגלה רק כשלקוח פותח מסמך שבור. האחריות על הכותב.

עדכון תבנית משפיע על כל ההצעות העתידיות ממנה

תבנית היא נכס משותף. שינוי בה משנה כל הצעה שתופק ממנה מכאן והלאה — כולל הצעות של לקוחות אחרים באותה מערכת. אל תתנסו בתבנית של לקוח. קראו את ה‑HTML, צרו עותק בשם חדש (בלי objectId), ועבדו על העותק.

חוזה ה‑HTML — ארבעה כללים מחייבים

1 · שורש windowDiv

האלמנט החיצוני חייב להיות div עם id="windowDiv":

HTML

<div id="windowDiv" class="rtl"
     style="height: auto; padding: 20px 50px; direction: rtl;
            -webkit-print-color-adjust: exact;
            font-family: 'Noto Sans Hebrew', sans-serif;">
  <!-- כל תוכן המסמך -->
</div>

2 · בלוק החתימה מנוהל על ידי המערכת

HTML

<div id="sigDiv" style="text-align: center; margin-top: 30px;">
  <div id="Signature">חתימה</div>
  <div id="SignatureName">שם חתום</div>
  <div id="SignatureDate">תאריך חתימה</div>
</div>

שלושת המזהים הפנימיים מחויבים בסכימה. העטיפה sigDiv היא מה שהמערכת מסתירה לפני החתימה וחושפת אחריה (בעמוד PriceQuoteSign: לפני החתימה sigDiv מקבל display: none; את שדות החתימה עצמם — תאריך, שם חותם, אימייל, קנבס חתימה — העמוד מוסיף בעצמו).

לכן: אל תסתירו את הבלוק ב‑CSS — display:none שובר את הזרימה — ואל תשנו את שמות המזהים, כי אז הבלוק מוצג ללקוח לפני שחתם.

אחרי חתימה מוצלחת רשומת ה‑PriceQuotes מתעדכנת: StatusId עובר ל‑“אושרה”, ונכתבים SignedAt, SignedByName, SignedByEmail ו‑SignedPdf (שדה PrivateFile, חוזר ב‑Get-Data כ‑resource_link עם URI מסוג file-storage:///…/PriceQuotes/<id>/SignedPdf — ראו המשאב get-file).

3 · שורות חוזרות — data-repeat

התכונה יושבת על ה‑<tr>. לא על ה‑<table> ולא על ה‑<td>:

HTML

<table style="width:100%; border-collapse:collapse;">
  <tr class="brand-thead">
    <td>מוצר</td><td>תיאור</td><td>כמות</td><td>מחיר ליחידה</td><td>סה"כ</td>
  </tr>
  <tr data-repeat="SaleRows">
    <td>{{SaleRows.ProductId.Name}}</td>
    <td>{{SaleRows.Description}}</td>
    <td>{{SaleRows.Quantity}}</td>
    <td>{{SaleRows.PricePerUnit}} &#8362;</td>
    <td>{{SaleRows.Total}} &#8362;</td>
  </tr>
</table>

מופיע רק מוצר אחד? כמעט תמיד ה‑data-repeat הודבק על האלמנט הלא נכון. שתי שורות SaleRows ⇒ שני <tr data-repeat="SaleRows"> בפלט, כל אחד עם הערכים של השורה שלו (הסדר אינו בהכרח סדר היצירה). מכירה בלי שורות ⇒ הטבלה נשארת עם כותרת בלבד, בלי שגיאה.

4 · אין <script> בתבנית

המערכת לא תעצור אתכם — וזו הסיבה להימנע

תבנית עם <script> נשמרת, מפיקה הצעה, והסקריפט אף רץ בעמוד החתימה של הלקוח.

הכלל נשאר בתוקף מסיבה אחרת: הסקריפט רץ בדפדפן של הלקוח ולא בהפקת ה‑PDF, כך שכל “פורמט מספרים” או “הצגה מותנית” שנעשים ב‑JS ייראו במסך ולא במסמך — והם חשופים לכל מי שפותח את הקישור. כל הלוגיקה חייבת להיות CSS בלבד. אין עיצוב מספרים עם מפרידי אלפים, אין הצגה מותנית, אין חישוב בתוך התבנית — מה שצריך להיות מחושב, מגיע מחושב מהרשומה.

ה‑placeholders

סוגריים כפולים. זה מנוע שונה לגמרי מזה של הטריגרים וההודעות, שמשתמש בסוגריים משולשים.

הרמה	Placeholders	מה חוזר בפועל
ההצעה עצמה	{{number}} · {{date}} · {{Vat}} · {{totalIncludingVat}}	10017 (מספר רץ) · 23-08-2026 (DD‑MM‑YYYY) · 180.00 — סכום המע“מ, לא אחוז · 1180.00
המכירה	{{Sales.Total}} · {{Sales.TotalBeforeDiscount}} · {{Sales.DiscountValue}}	הערכים כפי שהם ברשומה, בלי עיצוב (1000, 1100, 100)
הלקוח (דרך Pointer)	{{Sales.AccountId.Name}} · {{Sales.AccountId.Address}} · {{Sales.AccountId.PhoneNumber}} · {{Sales.AccountId.Email}}	כל שדה של Accounts לפי שמו בסכימה. Phone שבתיאור הכלי אינו שדה במערכת vanilla — השדה הוא PhoneNumber, ו‑{{Sales.AccountId.Phone}} מודפס ריק
שורת מוצר	{{SaleRows.ProductId.Name}} · {{SaleRows.Description}} · {{SaleRows.Quantity}} · {{SaleRows.PricePerUnit}} · {{SaleRows.Total}}	שורה לכל רשומת SaleRows של המכירה

הכלל: כל placeholder הוא שם שדה בסכימה (או מסלול דרך Pointer), וכל מה שלא קיים מודפס ריק — לכן Get-Schema על Sales ועל Accounts לפני שכותבים תבנית. {{Sales.Probability}}, {{Sales.ReasonForLost}}, {{Sales.NextStepDate}} קיימים ויעבדו; IsWon / IsLost אינם שדות של Sales במערכת vanilla (הסטטוס הוא SaleStatusId).

שדה ריק מודפס כמחרוזת ריקה — בלי שום סימן

placeholder שהשדה שמאחוריו ריק, או שאינו קיים כלל, מוחלף במחרוזת ריקה — לא נשאר {{...}} גולמי, אבל גם לא נעלם הטקסט שמסביבו. הלקוח מקבל “הנחה: ₪” או “טלפון:” בלי ערך.

הכלל: שדה שיכול להיות ריק — לא שמים בתבנית. החשודים הקבועים הם הנחה ותיאור ברמת השורה. את ההנחה הכוללת מציגים בסיכום, דרך {{Sales.DiscountValue}}.

סוגריים משולשים {{{…}}} (התחביר של טריגרים והודעות) לא עובדים כאן: הזוג הפנימי מוחלף והחיצוני נשאר — {{{Sales.Total}}} מודפס כ‑{1000}.

שדות פנימיים לא הולכים למסמך לקוח

{{Sales.Probability}}, {{Sales.ReasonForLost}}, {{Sales.NextStepDate}} — קיימים ויעבדו. אף אחד מהם לא אמור להגיע ללקוח.

שדות קלט שכותבים בחזרה

<input> ששמו מתחיל ב‑Accounts. או ב‑Sales. נשמר בחזרה לרשומה כשהלקוח שולח את המסמך החתום:

HTML

<input name="Accounts.Address" type="text" />
<input name="Sales.Comment" type="text" />

Accounts.Address ו‑Accounts.City נכתבים ל‑Accounts, Sales.Comment נכתב ל‑Sales, ו‑input בשם אחר (למשל FreeText) לא נשמר בשום מקום. הכתיבה מתבצעת רק כחלק מהחתימה — לא בצפייה במסמך.

שני פרטים: value="{{…}}" על ה‑input לא מונע את השמירה — הערך החדש נשמר — אלא רק מציג את הערך הנוכחי כברירת מחדל; ושם השדה אחרי הקידומת חייב להיות שם שדה אמיתי בסכימה של Accounts / Sales — קחו אותו מ‑Get-Schema.

צבעים ב‑PDF

דפדפנים מסירים צבעי רקע בהדפסה

זו הסיבה מספר 1 ל“נראה מצוין במסך, יוצא לבן ב‑PDF”. כל אלמנט צבוע צריך גם סגנון inline (לתצוגה) וגם מחלקה בבלוק הדפסה עם !important (ל‑PDF):

HTML

<style>
@media print {
  * { -webkit-print-color-adjust: exact !important; print-color-adjust: exact !important; }
  .brand-header { background-color: #001489 !important; color: #fff !important; }
  .brand-thead  { background-color: #00618c !important; color: #fff !important; }
  .brand-light  { background-color: #bfe8de !important; }
}
</style>

<td class="brand-header" style="background-color:#001489; color:#fff;">…</td>

רק אחד מהשניים = צבע חסר באחד משני המדיומים.

לוגו

הנושא	הכלל
מיקום ב‑RTL	ה‑<td> הראשון בשורה מרונדר מימין — הלוגו בתא הראשון
גודל	width: 240px; height: auto. לא max-width / max-height — הם מרנדרים לוגו זעיר כשל‑PNG יש שוליים שקופים
הקובץ	חתכו את השוליים השקופים לפני העלאה
העלאה	Upload-Public-File, ומשם ה‑URL לתוך ה‑HTML

Create-Price-Quote

מפיק מסמך ממכירה קיימת.

הפרמטר	טיפוס	חובה	המשמעות
saleId	String	✔	מזהה רשומת ה‑Sales. המכירה חייבת להתקיים
templateId	String	✔	מזהה התבנית מ‑Get-Price-Quote-Templates
status	Enum	✔	אחד מארבעה, ראו למטה
includeVAT	Boolean		ברירת מחדל true. עם false: vat: 0 ו‑{{Vat}} מודפס 0.00
siteId	String		מזהה האתר (siteId מ‑Get-Sites). ראו למטה

JSON

{ "saleId": "V0sVNyS45K", "templateId": "pdft012345",
  "status": "טיוטה", "includeVAT": true }

התשובה:

JSON

{ "objectId": "91ksfWWkpM",
  "link": "https://<sub>.mbapps.co.il/apps/mybusiness/PriceQuoteSign?oid=91ksfWWkpM",
  "total": 1000, "totalWithVat": 1180, "vat": 180 }

objectId הוא רשומה חדשה ב‑PriceQuotes (עם Number רץ, Content — ה‑HTML הממוזג, ו‑Pointers ל‑SaleId, AccountId, TemplateId, StatusId). saleId או templateId שאינם קיימים ⇒ Error: Object not found.. הכלי אינו בודק שהתבנית היא מסוג “הצעות מחיר” — תבנית Invoice של MyBooks מתקבלת ומופקת כהצעה.

הקישור פתוח לציבור רק בסטטוס נשלחה - בהמתנה לאישור

תיאור הכלי מתעד זאת: only status “נשלחה - בהמתנה לאישור” can be accessed and signed by public user. הצעה בסטטוס הזה נפתחת בדפדפן נקי ללא login, כולל אזור החתימה, ו‑GET אנונימי על הרשומה (App‑Id בלבד) מחזיר 200. ה‑CLP של PriceQuotes לא השתנה (find לתפקידים בלבד) — הפתיחה נעשית במנגנון ייעודי לפי הסטטוס.

היסטוריה: בגרסאות שרת ישנות הקישור דרש משתמש מחובר בכל סטטוס — בדפדפן נקי הוצג “המסמך לא נמצא”. כשההצעה בסטטוס אחר (טיוטה, אושרה…) ההתנהגות הזו היא עדיין מה שהלקוח יראה — העבירו לסטטוס נשלחה - בהמתנה לאישור לפני שליחת הקישור.

מכירה בלי שורות = טבלת מוצרים ריקה

הכלי לא נכשל כשאין SaleRows — הוא מפיק מסמך תקין עם טבלה ריקה (חוזרת כותרת הטבלה בלבד, total לפי Sales.Total). לפני הפקה: ודאו שיש שורות מכירה.

ה‑enum של הסטטוסים — ארבע מחרוזות עבריות מדויקות

הערך	המשמעות
טיוטה	טיוטה
נשלחה - בהמתנה לאישור	נשלחה, ממתינה לאישור הלקוח. הסטטוס היחיד שבו קישור החתימה נפתח ללא התחברות
בוטלהמושהית	בוטלה / מושהית
אושרה	אושרה

שימו לב ל‑בוטלהמושהית

זו המחרוזת כפי שהיא מוגדרת ב‑enum של הסכימה החיה — מילה אחת מחוברת. היא נראית כמו שגיאת הקלדה, והיא הערך התקין: כל אחד מארבעת הערכים ממופה ל‑Pointer הנכון ב‑StatusId (טבלת PriceQuoteStatuses), גם כששם הרשומה בטבלה כתוב אחרת — “טיוטא” עבור טיוטה, ו“בוטלה\מושהית” עבור בוטלהמושהית.

העבירו אותה בדיוק כך, כולל היעדר הרווח. “בוטלה” או “בוטלה/מושהית” נדחים עוד לפני שהקריאה מגיעה לשרת: Input validation error: … status: Invalid option: expected one of "טיוטה"|"נשלחה - בהמתנה לאישור"|"בוטלהמושהית"|"אושרה". שימו לב גם למקף ולרווחים ב‑נשלחה - בהמתנה לאישור.

siteId — פרמטר אופציונלי

הפרמטר מופיע בסכימה החיה של הכלי ואינו חובה. הערך הוא ה‑siteId שמחזיר Get-Sites (מחרוזת hex של 24 תווים); עם הערך התקין ההצעה מופקת בדיוק כמו בלעדיו — במערכת עם אתר אחד אין לו השפעה נראית.

מגבלה ידועה — siteId שאינו קיים מפיל את הקריאה בשגיאת ריצה

ערך שגוי לא מחזיר “Object not found” כמו saleId / templateId, אלא Error: Cannot read properties of undefined (reading 'includes'). במערכת עם אתר אחד: השמיטו אותו. אם אתם מעבירים אותו — רק ערך מ‑Get-Sites.

תקלות נפוצות — טבלת אבחון

התסמין	הבדיקה הראשונה
המסמך “עובד במסך” אבל ה‑PDF שונה	חפשו <script ב‑HTML של התבנית והסירו הכול — JS רץ רק בדפדפן
בלוק החתימה מוצג לפני שחתמו	id="sigDiv" ושלושת המזהים הפנימיים — בדיוק כך
ה‑PDF יוצא בלי צבעים, המסך תקין	חסר בלוק @media print עם !important
אין צבע גם במסך	חסר style inline (צריך גם מחלקה וגם inline)
מוצג רק מוצר אחד	data-repeat="SaleRows" לא על ה‑<tr>
טבלת המוצרים ריקה	למכירה אין רשומות SaleRows
ערך חסר במסמך (תווית בלי ערך)	שגיאת כתיב במסלול · שדה שאינו בסכימה (למשל Phone במקום PhoneNumber) · השדה ריק ברשומה
מודפס {ערך} עם סוגריים	סוגריים משולשים במקום כפולים
Error: Object not found.	saleId / templateId / objectId שאינו קיים
Cannot read properties of undefined (reading 'includes')	siteId שגוי — השמיטו אותו
הלוגו זעיר או הכותרת ענקית	PNG עם שוליים שקופים · max-width במקום width
Get-Data על PDFTemplate חוזר בלי HTML	הוסיפו HTML ל‑keys, או הורידו את הפרמטר
הלקוח רואה “המסמך לא נמצא”	ההצעה אינה בסטטוס נשלחה - בהמתנה לאישור — רק בו הקישור נפתח ללא התחברות (בגרסאות שרת ישנות נדרש login בכל סטטוס)

המשך

• כלי קבצים — העלאת הלוגו וקריאת ה‑PDF שנוצר
• כלי נתונים — קריאה וכתיבה של PDFTemplate ושל Sales
• אינדקס הכלים המלא
• שרת ה‑MCP — ההבדל בין סוגריים כפולים למשולשים