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

הצעת מחיר היא מסמך 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 על הטבלה מחזיר את כולן.

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

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>

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

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.

צבעים ב‑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, או הורידו את הפרמטר
הלקוח רואה “המסמך לא נמצא”	ההצעה אינה בסטטוס נשלחה - בהמתנה לאישור — רק בו הקישור נפתח ללא התחברות

המשך

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