סוגי נתונים והפורמט ב‑JSON

זה העמוד שהכי הרבה אינטגרציות נכשלות בו, ותמיד באותו אופן: הבקשה מחזירה 200 OK והשדה נשאר ריק. הסיבה כמעט תמיד אחת — אותו טיפוס נכתב בצורה שונה בכל שכבה. Pointer ב‑REST הוא אובייקט עטוף; ב‑web2table הוא מחרוזת חשופה. מי שמעתיק snippet משכבה אחת לשנייה מקבל שקט, לא שגיאה.

1 · טבלת הטיפוסים המלאה

הפלטפורמה בנויה על Parse, שמקודד כל טיפוס שאינו JSON טבעי כאובייקט עם מפתח שמור __type. לעולם אל תשתמשו ב‑__type לנתונים משלכם.

טיפוס בסכימה	הפורמט ב‑JSON (קריאה וכתיבה)	הערות
String	"טקסט"	רוב השדות. תוכן עברי הוא UTF‑8 רגיל
Number	42 · 3.14	שדות כסף הם מספרים רגילים — אין טיפוס מטבע
Boolean	true / false
Object	כל אובייקט JSON	למשל Config.Value, _Timeline.data
Array	כל מערך JSON	כולל מערכי בחירה מרובה (§4)
Date	{"__type":"Date","iso":"2026-01-15T10:30:00.000Z"}	UTC, ISO‑8601, עם אלפיות שנייה
Pointer	{"__type":"Pointer","className":"Accounts","objectId":"xK9mP2qRsT"}	מפתח זר. שם השדה מסתיים ב‑Id
Relation	{"__type":"Relation","className":"_User"}	רבים‑לרבים. מסוננים עם $relatedTo, לא מוחזרים inline
File	{"__type":"File","name":"…-photo.jpg","url":"https://…"}	ה‑URL אינו נפתח בלי אישור: קריאה בלי מפתח מנותבת ל‑/authorize-file-access. ראו קבצים
PrivateFile	אותה צורה כמו File; הגישה מתווכת דרך הרשומה	הרחבה של MyBusiness. בשמירה ה‑URL נכתב מחדש לנתיב …/<Table>/<objectId>/<Field> ונוסף לו "private": true
HTML/XML	מחרוזת שמכילה תגיות	הרחבה של MyBusiness לשדות טקסט עשיר
AutoIncrement	מספר, התייחסו אליו כלקריאה בלבד	הרחבה של MyBusiness — מספר רץ שהשרת מקצה כשהשדה חסר בבקשה (ומוחזר כבר בתשובת ה‑POST). אין אכיפה: POST/PUT עם ערך מפורש מתקבלים, המונה ב‑_AutoIncrementValues אינו מתעדכן, ומספרים כפולים אפשריים
GeoPoint	{"__type":"GeoPoint","latitude":32.0853,"longitude":34.7818}	נדיר במוצר — אין אף שדה כזה בבסיס המוצר, אבל הטיפוס נתמך בכתיבה ובקריאה
ACL	{"<userId|role:Name|*>":{"read":true,"write":true}}	הרשאות ברמת שורה; לרוב ריק — השליטה היא ברמת הטבלה (CLP)
Null	null	כל שדה יכול לקבל null ללא קשר לטיפוס שלו

טיפוס של שדה ננעל לנצח — אבל לא תמיד תקבלו על כך שגיאה

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

• שדה Date או Pointer שמקבל טיפוס אחר → נכשל ב‑{"code":111,"error":"schema mismatch for <Table>.<Field>; expected <X> but got <Y>"}. גם מחרוזת ISO שטוחה לשדה Date, וגם objectId חשוף לשדה Pointer, נופלים כאן.
• שדה Number דוחה בוליאני (111), אבל ממיר מחרוזת בשקט: "12" נשמר כ‑12, ו‑"abc" נשמר כ‑null — 201, בלי שגיאה.
• שדה String שמקבל מספר → מתקבל בשקט ומומר למחרוזת: 12345 יישמר כ‑"12345". בוליאני לשדה String דווקא נדחה ב‑111.
• שדה Boolean שמקבל את המחרוזת "true" → 111.

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

2 · טבלת ההמרה בין שלוש השכבות

זו הליבה של העמוד. אותה עובדה עסקית — “קשר את הליד למקור הליד ‘פייסבוק’” — נכתבת בשלוש צורות שונות:

טיפוס	REST API	טפסי web2table (שדות table_* / account_*)	כלי MCP (Create-Data, Update-Data)	מה קורה כששולחים לא נכון
String	"טקסט"	"טקסט"	"טקסט"	—
Number	1500	1500 או "1500" (השרת ממיר)	1500	"abc" → נשמר null בשקט, גם ב‑REST וגם בטופס
Boolean	true	true או "true" — שתי הצורות עובדות בשדה בוליאני רגיל	true	חריג: account_IsAccount מקבל רק בוליאני אמיתי
Date	{"__type":"Date","iso":"2026-01-15T10:30:00.000Z"}	"2026-01-15" — מחרוזת ISO שטוחה ומרופדת; גם אובייקט Date עטוף נקלט	{"__type":"Date","iso":"YYYY-MM-DD"}	"2026-1-5" (לא מרופד) → 400 קוד 111, הבקשה כולה נכשלת
Pointer	{"__type":"Pointer","className":"X","objectId":"xK9mP2qRsT"}	"xK9mP2qRsT" — objectId חשוף, בדיוק 10 תווים	{"__type":"Pointer","className":"X","objectId":"…"}	המלכודת מספר 1. בשדות table_* — Pointer עטוף או מזהה באורך אחר → 200 והשדה חסר. בשדות account_* — עטוף נקלט; אורך שגוי → 400/111
Array של Pointer (בחירה מרובה)	ראו §4 — שתי צורות בשטח	מערך של מחרוזות objectId חשופות	כמו REST	אין ולידציה: מערך אובייקטי Pointer, או איבר באורך שגוי, נשמר כפי שנשלח — ב‑REST ובטופס
File / PrivateFile	{"__type":"File","name":"…","url":"…"}	לא נתמך — 400, הבקשה כולה נכשלת	ראו קבצים	—
GeoPoint	{"__type":"GeoPoint","latitude":…,"longitude":…}	אותה צורה כמו REST — נקלט ונשמר	אותה צורה כמו REST, על שדה GeoPoint קיים	כתיבה ב‑MCP לשם שדה חדש יוצרת עמודה שאינה GeoPoint והערך נשמר כמערך
AutoIncrement	לקריאה בלבד	לא לשלוח	לא לשלוח	מתקבל; המונה ב‑_AutoIncrementValues אינו מתעדכן

היסטוריה — המפתח המדומה fieldName בכלי הנתונים של MCP

בגרסאות שרת ישנות הסכימה של Get-Data, Count-Data, Aggregate-Data, Create-Data, Create-Many ו‑Update-Data סימנה fieldName כמפתח חובה בתוך where/data, וקריאה בלעדיו נדחתה בוולידציה. בעדכון שרת עדכני where/data שטוחים עוברים. מול שרת ישן המעקף "fieldName": null עדיין עובד ואינו יוצר עמודה. ראו כלי נתונים.

הכלל שחוסך את רוב שיחות התמיכה

בשכבת ה‑REST — עטפו. בשכבת הטפסים — אל תעטפו. web2table (ו‑web2case) מתעלמת בשקט מכל מפתח שאינה מזהה — table_NoSuchField פשוט נעלם — ובשדות table_* היא זורקת גם ערך Pointer שאינו מחרוזת בת 10 תווים. אין שגיאה, אין אזהרה, אין לוג — רק 200 OK ושדה ריק. מה שכן מחזיר שגיאה: תאריך לא מרופד, קובץ, ו‑Pointer באורך שגוי בשדה account_* — כולם 400, והבקשה כולה נכשלת.

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

הצורה הנכונה, זו מול זו

JSON

// REST API — /parse/classes/Accounts
{
  "Name": "ישראל ישראלי",
  "LeadSourceId": { "__type": "Pointer", "className": "LeadSource", "objectId": "vOZLqOWnQf" },
  "LeadConversionDate": { "__type": "Date", "iso": "2026-01-15T10:30:00.000Z" },
  "IsAccount": false
}

JSON

// web2table — /functions/{appId}/web2table  (ללכידת ליד בלבד: getlead, בשמות שטוחים)
{
  "table": "Sales",
  "phone": "0501234567",
  "account_Name": "ישראל ישראלי",
  "account_LeadSourceId": "vOZLqOWnQf",
  "account_IsAccount": false,
  "table_Name": "פנייה מדף נחיתה",
  "table_ClosingDate": "2026-01-15"
}

JSON

// MCP — Create-Data
{
  "table": "Accounts",
  "data": {
    "Name": "ישראל ישראלי",
    "LeadSourceId": { "__type": "Pointer", "className": "LeadSource", "objectId": "vOZLqOWnQf" },
    "LeadConversionDate": { "__type": "Date", "iso": "2026-01-15" },
    "IsAccount": false
  }
}

ConversionDate אינו בבסיס המוצר — השדה בבסיס הוא LeadConversionDate, ראו מפת הטבלאות.

3 · תאריכים — שלוש הערות שחוסכות באגים

1. תמיד UTC. הפורמט הקנוני הוא ISO‑8601 עם אלפיות שנייה ו‑Z בסוף. אם המשתמש בישראל רואה “15/01/2026 12:30”, הערך המאוחסן הוא 2026-01-15T10:30:00.000Z בחורף.

2. createdAt ו‑updatedAt הם חריגים. בתשובה הם חוזרים כמחרוזת ISO שטוחה ("2026-08-20T06:12:44.109Z"), אבל ב‑where הם עדיין דורשים את האובייקט העטוף:

   JSON

   { "createdAt": { "$gt": { "__type": "Date", "iso": "2026-01-01T00:00:00.000Z" } } }

3. בשכבת הטפסים מחרוזת שטוחה מספיקה, ובלבד שהיא מרופדת ("2026-01-15", או ISO מלא). גם אובייקט Date עטוף נקלט. "2026-1-5" לא מרופד → 400 קוד 111 — הבקשה כולה נכשלת, לא רק השדה.

4 · בחירה מרובה — array_<purpose>_Pointer_<TargetTable>

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

array_<purpose>_Pointer_<TargetTable>

חלק	משמעות
array_	קידומת באותיות קטנות — הרנדור יהיה <select multiple>
<purpose>	snake_case חופשי, מתעלמים ממנו בזמן ריצה (languages, tags)
_Pointer_	ליטרל, P גדולה — איברי המערך הם Pointer
<TargetTable>	שם הטבלה המדויק, case‑sensitive

הטיפוס בסכימה חייב להיות Array. שגיאת אותיות (array_x_pointer_Y) או טיפוס Pointer שוברים את המנגנון בשקט.

שתי צורות אחסון בשטח — טפלו בשתיהן בקריאה

בפועל קיים אחסון של אובייקטי Pointer מלאים:

JSON

"array_tags_Pointer_Tags": [
  { "__type": "Pointer", "className": "Tags", "objectId": "zY2p6jpXqm" },
  { "__type": "Pointer", "className": "Tags", "objectId": "io3Z6YsMcG" }
]

לצידו קיים אחסון של מערך מחרוזות objectId חשופות. שתי הצורות מתקבלות בכתיבה (REST, MCP וטפסים) בלי שום ולידציה — גם ["short"] נשמר. בקריאה — קבלו את שתי הצורות; בכתיבה — שלחו מערך מחרוזות חשופות, ואל תערבבו צורות באותו שדה.

צורת הערך בשאילתה חייבת להתאים לצורת האחסון: {"array_tags_Pointer_Tags":{"$in":["zY2p6jpXqm"]}} מוצא רק רשומות שמאחסנות מחרוזות; מול אחסון של אובייקטי Pointer אותה שאילתה מחזירה [] בלי שגיאה, וצריך לשלוח {"$in":[{"__type":"Pointer","className":"Tags","objectId":"zY2p6jpXqm"}]}.

בשאילתה, containedIn ($in) הוא הכלי לריבוי ערכים; שוויון פשוט ({"array_…": "zY2p6jpXqm"}) גם מתאים לאיבר בתוך המערך, כמקובל ב‑Parse. ערך שנבחר ולא נמצא בטבלת ה‑lookup — השמיטו את השדה מהגוף, אל תשלחו מחרוזת ריקה.

5 · פעולות אטומיות (REST PUT)

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

JSON

{ "StockCount": { "__op": "Increment", "amount": -5 } }
{ "Tags":       { "__op": "AddUnique", "objects": ["דחוף"] } }
{ "Tags":       { "__op": "Add",       "objects": ["חוזר"] } }
{ "Tags":       { "__op": "Remove",    "objects": ["דחוף"] } }
{ "Comment":    { "__op": "Delete" } }

__op: "Delete" מוחק את ערך השדה מהרשומה — לא את השדה מהסכימה ולא את הרשומה.

בשכבת ה‑MCP אותן פעולות עוברות כמות שהן דרך data של Update-Data — {"__op":"Increment","amount":n} עובד ומחזיר את הערך המעודכן.

היסטוריה — סכימת Update-Data הציעה $inc

בגרסאות שרת ישנות תיאור הפרמטר data בסכימה של Update-Data אמר «For number field use { $inc: n }» — תחביר MongoDB, לא Parse. התיאור תוקן והוא מתעד עכשיו את {"__op":"Increment","amount":n}. ההתנהגות לא השתנתה: $inc על שדה Number קיים נדחה ב‑schema mismatch … expected Number but got Object (קוד 111), גם ב‑MCP וגם ב‑REST; ועל שם שדה חדש הוא יוצר עמודה מטיפוס Object שמכילה מילולית {"$inc":1}. השתמשו תמיד ב‑{"__op":"Increment","amount":n}.

6 · שדות מערכת שקיימים בכל רשומה

שדה	טיפוס	נקבע על ידי
objectId	String	השרת — בדיוק 10 תווים
createdAt	Date	השרת, בלתי משתנה — PUT עם createdAt מוחזר 200 ומתעלם מהערך
updatedAt	Date	השרת, בכל שמירה
ACL	ACL	האפליקציה; לרוב ריק
createdBy	Pointer→_User	השרת — הרחבה של MyBusiness. בכתיבה עם Master Key או API Key ה‑objectId הוא המחרוזת "Master", לא משתמש אמיתי
updatedBy	Pointer→_User	השרת — הרחבה של MyBusiness; אותו כלל

אל תשלחו אף אחד מהם ביצירה. createdAt מפורש פשוט מתעלמים ממנו; אבל objectId מפורש כן מתקבל כשכותבים עם Master Key (POST {"objectId":"abcdefghij"} → 201 עם המזהה הזה) — אל תעשו זאת, זה פותח את הדלת להתנגשויות.

שני מרחבי מזהים באותה מערכת

רשומות נתונים, וגם טריגרים והפעולות שלהם, מזוהים ב‑מזהה בן 10 תווים ("_id":"n2jvqclaL5" ב‑Get-Triggers, וזה גם הערך שנכתב ל‑updatedByTrigger ול‑_syslogTriggers.triggerId). עמודים, תפריטים והאתר עצמו מזוהים ב‑מזהי MongoDB — 24 תווים הקסדצימליים (6a8a95b93cd0a41edaebef84). הזנת מזהה ממרחב אחד לממשק שמצפה לאחר נכשלת או, גרוע יותר, מתקבלת ולא עושה כלום.

בנוסף, טבלאות שאוטומציות נוגעות בהן נושאות שדה updatedByTrigger:String (בבסיס המוצר: Accounts, Tasks, SaleRows, _Notification) — שומר הלולאה של מנוע הטריגרים, וגם רמז ביקורת ש“טריגר נגע ברשומה הזו”: הערך הוא מזהה הטריגר שכתב אחרון.

7 · דוט‑נוטציה — קריאה דרך Pointer

בדוחות, בתנאים, בהגדרות טריגרים ובאגרגציות אפשר לפנות לשדה בטבלה המקושרת:

<PointerField>.<TargetClass>.<TargetField>

לדוגמה AccountId.Accounts.Email · SaleStatusId.SaleStatuses.Name · array_tags_Pointer_Tags.Tags.Name.

ב‑placeholders של הודעות (טריגרים, תבניות מייל/SMS) התחביר קצר יותר — קפיצה אחת בלבד:

{{{Name}}}
{{{AccountId.Name}}}
{{{SaleDate.format(date,he-IL,Asia/Jerusalem)}}}

שתי מערכות סוגריים, ואל תערבבו

הודעות טריגר, מייל ו‑SMS משתמשות ב‑סוגריים משולשים {{{ }}} — כך מגדירה סכימת Set-Trigger-Action, וכך בנויות תבניות המייל של המוצר ({{{PriceQuoteLink}}}). תבניות ה‑PDF של הצעות המחיר (PDFTemplate.HTML) הן Mustache: רוב השדות ב‑סוגריים כפולים {{ }} ({{Sales.AccountId.Name}}, {{SaleRows.Quantity}}), וערכים שלא עוברים escape ב‑{{{ }}} ({{{settings.NameHeb}}}). סוגריים כפולים בהודעת טריגר מייצרים טקסט מילולי בפלט במקום ערך.

8 · צ’קליסט לפני הכתיבה הראשונה

1. שלפו את הסכימה של הטבלה — סכימות. לעולם אל תקודדו רשימת שדות מהזיכרון.
2. לכל שדה Pointer בטופס, שלפו את טבלת ה‑lookup וקבעו מיפוי תווית → objectId.
3. בנו את הערכים בפורמט של השכבה שאליה אתם פונים, לפי §2.
4. השמיטו שדות ריקים לגמרי מהגוף — אל תשלחו "" או null “ליתר ביטחון”.
5. אחרי הכתיבה הראשונה — קראו את הרשומה בחזרה וּודאו שכל שדה נשמר. זו הבדיקה היחידה שתופסת השמטה שקטה.

המשך מכאן

• מוסכמות המוצר — למה Accounts מחזיקה גם לידים, ומאיפה מגיעות התוויות בעברית
• מפת הטבלאות — לאיזו טבלה בכלל כותבים
• סכימות — לקרוא לפני שכותבים
• getlead · web2table — הדיאלקט של שכבת הטפסים
• שגיאות ופתרון תקלות — “200 אבל השדה ריק” מסודר לפי תסמין