מוסכמות המוצר

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

1 · Accounts היא הטבלה המרכזית — לידים ולקוחות באותו מקום

אין טבלת “לידים” נפרדת. אותה טבלה מחזיקה את שניהם, וההבחנה היא שדה בוליאני יחיד:

IsAccount	המשמעות
false	ליד: פנייה שעדיין לא הפכה ללקוח
true	לקוח

המרה של ליד ללקוח היא הפיכת הדגל, בתוספת חותמת ב‑LeadConversionDate (בבסיס המוצר זה שם השדה; אצל חלק מהלקוחות קיים במקביל גם ConversionDate — שלפו סכימה).

השדות של שני העולמות חיים זה לצד זה על אותה שורה: LeadStatusId, LeadOwnerId, LeadSourceId מצד אחד; StatusId, TypeId, OwnerId מהצד השני. אחרי המרה, השאלה “איזה שדה סטטוס משמעותי כאן” משנה תשובה — וזו סיבה נפוצה לדוחות שמראים מספרים מוזרים.

ספירת “לקוחות” בלי IsAccount היא ספירה שגויה

GET /parse/classes/Accounts?limit=0&count=1 מחזיר לידים ולקוחות יחד. כל ספירה, כל דוח וכל סנכרון חייבים לסנן במפורש: where={"IsAccount":true}.

כל רשומה עסקית אחרת (Sales, Cases, Tasks, Activities, טבלאות מותאמות) מקושרת ל‑Accounts דרך שדה Pointer בשם AccountId. פירוט: מפת הטבלאות.

2 · שמות באנגלית, ערכים בעברית

שמות טבלאות ושדות הם PascalCase / CamelCase באנגלית (Accounts, FirstName, PhoneNumber, LeadStatusId); התוכן עצמו בעברית.

המוסכמה	התבנית	דוגמאות
טבלאות	PascalCase, ברבים לישויות	Accounts, SaleRows, PriceQuotes, Conversations
מחלקות מערכת	קידומת _ (שמורה)	_User, _Timeline, _Dictionary, _syslogTriggers
שדות Pointer	<Entity>Id	AccountId, SaleStatusId, OwnerId
שדה תצוגה	לכל טבלת lookup וישות יש Name:String — חריג אחד במוצר: UserStatuses, עם name באות קטנה	ברירת המחדל של כל רשימה נפתחת
טבלאות lookup	<Entity>Statuses · <Entity>Types · <Entity>States	CaseStatuses, TaskTypes, CaseSubTypes, CaseStates
מטא‑מצב	StateId על טבלת סטטוס → טבלת *States קבועה	CaseStatuses.StateId→CaseStates, LeadStatuses.StateId→AccountStatusesStates
חותמת אוטומציה	updatedByTrigger:String על כל טבלה שטריגר נוגע בה — מזהה הטריגר שכתב אחרון	Accounts, Tasks, SaleRows

אל תחפשו שדה בשם “טלפון”

התוויות שהמשתמש רואה בממשק אינן שמות השדות. הן יושבות בטבלת מערכת נפרדת (_Dictionary) — ראו §4.

3 · שדה Pointer מסתיים ב‑Id

מוסכמת השמות עקבית: שדה שמצביע לטבלה אחרת נקרא <משהו>Id.

השדה	הטבלה שאליה הוא מצביע
AccountId	Accounts
ContactId	Contacts
SaleStatusId	SaleStatuses
LeadSourceId	LeadSource
OwnerId	_User
CurrentUserId	_User

הסיומת היא מוסכמה, לא חוזה

היא נכונה כמעט תמיד — אבל “כמעט” הוא מספיק כדי לשבור קוד. היעד האמיתי של כל Pointer מוחזר בשדה targetClass בתשובת הסכימה, וזה המקור המחייב. ראו סכימות.

איך כותבים Pointer בפועל — ובאיזו צורה בכל שכבה — סוגי נתונים.

4 · התוויות בעברית — _Dictionary

שדות אינם מגיעים עם תווית עברית מהקופסה: במערכת חדשה טבלת _Dictionary כלל אינה קיימת, ואף שדה בתשובת הסכימה אינו נושא dictionary. השכבה הזו נולדת ברגע שמישהו מגדיר label בפעם הראשונה.

כשנוצר שדה עם label (למשל דרך הכלי Add-Field-to-Table), הפלטפורמה כותבת מיד שורה לטבלת המערכת _Dictionary:

JSON

{ "tblName": "Sales", "field": "OwnerSetDate", "value": "תאריך הגדרת אחראי" }

ומאותו רגע התווית חוזרת בתוך הגדרת השדה בתשובת Get-Schema של שכבת ה‑MCP:

JSON

"OwnerSetDate": { "type": "Date", "dictionary": "תאריך הגדרת אחראי" }

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

מגבלה ידועה — ב‑REST התווית לא ממוזגת לסכימה

GET /parse/schemas/<Table> מחזיר את השדה בלי dictionary — גם כששורת ה‑_Dictionary קיימת. רק Get-Schema של MCP מבצע את המיזוג. מי שעובד ב‑REST שולף את _Dictionary בעצמו (עם API Key או Master Key) וממזג לפי tblName + field.

שדה שנוצר בלי label נשאר באנגלית

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

מעל שכבת התוויות יש שכבה שלישית — מילון המונחים, שמחליף את שם הישות שמוצג במערכת (מכירה→פרויקט). היא לא נוגעת בשמות הסכימה כלל. שימו לב ש‑Set-Terminology-Dictionary לבדו לא מעדכן טקסטים שכבר יושבים בתוך עמודים ותפריטים קיימים (“מכירות” נשאר בתפריט אחרי שינוי המילון) — להחלפה בתוכן העמודים יש כלי נפרד, Replace-Terms, שרץ דף אחר דף. ראו מילון מונחים.

5 · בחירה מרובה — תבנית שם מיוחדת

לפלטפורמה אין טיפוס “בחירה מרובה”. במקום זה, שם השדה הוא המטא‑דאטה:

array_<purpose>_Pointer_<TargetTable>

JSON

{ "array_interests_Pointer_Interests": ["uNbbHuMGlK", "j17RjXmHdN"] }

• הטיפוס בסכימה חייב להיות Array.
• _Pointer_ הוא ליטרל עם P גדולה; שם טבלת היעד הוא case‑sensitive.
• שגיאת אותיות (array_x_pointer_Y) או טיפוס Pointer שוברים את המנגנון בשקט — השדה נשמר אבל לא מקבל את הרנדור הנכון.
• ערך שנבחר ולא נמצא בטבלת ה‑lookup — השמיטו את השדה מהגוף, אל תשלחו מחרוזת ריקה.

צורות האחסון (שתיים בשטח) והתחביר לשאילתה: סוגי נתונים.

6 · רשימות תלויות — האב יושב על העמוד, לא על הסכימה

רשימה נפתחת שמסוננת לפי בחירה קודמת (מחלקה → תת‑מחלקה) עובדת בשלושה חלקים:

1. טבלת הבן מחזיקה Pointer יחיד חזרה לטבלת האב.
2. הטבלה המארחת מחזיקה שני שדות Pointer — אחד לאב, אחד לבן.
3. ההפעלה יושבת על שדה הבן בעמוד — לא בסכימה.

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

7 · המוסכמות שאין להן חריגים

הכלל	ההשלכה
objectId הוא בדיוק 10 תווים	מזהה באורך אחר בשדה table_<Field> של web2table נזרק בשקט (200 והשדה ריק); בשדה account_<Field> — ובכל כתיבה ב‑REST — הבקשה כולה נכשלת ב‑400 {"code":111,"error":"schema mismatch … expected Pointer<…> but got String"}. כלי Get-Data של MCP אוכף minLength/maxLength = 10 בסכימה
שם שדה אינו ניתן לשינוי	“תיקון” = שדה חדש + מיגרציה. לכן שדות עם שגיאות כתיב שורדים בייצור לנצח
טיפוס שדה ננעל אחרי הערך הראשון	תכננו שם וטיפוס לפני היצירה. שימו לב לתסמין: שדה Date/Pointer מחזיר שגיאה 111, אבל שדה String ממיר בשקט
אין אכיפת ייחודיות על PhoneNumber / Email	חיפוש‑לפני‑יצירה הוא באחריותכם
טבלה חדשה נולדת חסרת הרשאות	“השדות מופיעים ריקים” — התקלה מספר 1 אחרי הקמה
כל כתיבה מפעילה אוטומציות	גם עם Master Key. ראו §8
הפלטפורמה כן בודקת תלויות במחיקה	מחיקת רשומה שמישהו מצביע עליה נדחית — ראו למטה

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

זו הפתעה נעימה למי שמכיר Parse גנרי. במערכת חדשה דלוק המתג Check dependencies before Delete operation (סביבת הפיתוח ← Databases ← המערכת ← לשונית Settings), ולכן:

JSON

{ "code": 119,
  "error": "Pointer to Object xK9mP2qRsT exists in table Tasks in key AccountId. Delete is not allowed." }

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

דריפט בשמות שדות — Phone מול PhoneNumber

זה הבלבול הנפוץ ביותר. השדה הקנוני, שמנועי זיהוי הכפילויות ושיוך השיחות עובדים מולו, הוא PhoneNumber. בנוסף, מספרי טלפון ישראליים מאוחסנים בפועל בכמה פורמטים (05X…, 972…, +972…, עם מקפים ובלי) והפלטפורמה אינה מנרמלת אותם. אף פעם אל תקודדו רשימת שדות בלי לשלוף סכימה קודם.

8 · כתיבות מפעילות אוטומציות

כל כתיבה — גם דרך Master Key, גם ב‑batch, גם מפונקציית שרת — מפעילה טריגרים מסוג data change.

טעינה של אלפי רשומות יכולה לייצר “סופת טריגרים”: התראות, מיילים והודעות WhatsApp ללקוחות אמיתיים. שרשרת מוגבלת ל‑3 רמות עומק (טריגר שיוצר רשומה שמפעילה טריגר וכן הלאה — הרשומה הרביעית בשרשרת כבר לא נוצרת, וב‑_syslogTriggers נרשם blocked! trigger step is to deep -3) — אבל כל רשומה מפעילה את הרמה הראשונה.

לפני טעינה המונית: תאמו עם מי שמחזיק את האוטומציות. ל‑POST /parse/batch אין דגל השתקה, ודגל skipTriggers ברמת הבקשה פשוט מתעלמים ממנו — הטריגר רץ כרגיל.

Create-Many עם skipTriggers — עובד; המעקף הישן אינו נדרש עוד

הכלי Create-Many של MCP מגדיר skipTriggers ו‑skipTimeline, והם באמת מכובדים באימות Master Key (הרשומה נוצרת בלי שהטריגר רץ ובלי שורת _Timeline). בגרסאות שרת ישנות סכימת הקלט דרשה מפתח ליטרלי fieldName בכל רשומה (וגם ב‑Create-Data / Update-Data), והמעקף "fieldName": "x" יצר עמודה מיותרת בטבלה. בעדכון שרת עדכני data שטוח עובר. ראו כלי נתונים.

ראו batch ו‑מגבלות ומכסות.

המשך מכאן

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