גישת API

מה זה?

עמוד "גישת API" (בהגדרות תחת "כלים ואינטגרציות", בכתובת /settings/api) מאפשר לחבר אתר או מערכת חיצונית ל-CRM בשני הכיוונים, בלי הזנה ידנית. אתה מנפיק מפתח API, מוסר אותו למערכת החיצונית, והיא מדברת עם המערכת בקריאות HTTP: דוחפת לידים, לקוחות ונכסים פנימה, וגם מושכת את הנכסים הפומביים של המשרד החוצה, למשל כדי להציג אותם באתר האישי שלך. העמוד פתוח למנהל המשרד ולאדמין בלבד, ורק כשגישת ה-API מופעלת למשרד.

עמוד גישת API בהגדרות: כותרת 'גישת API', מקטע 'איך משתמשים' עם כתובת הבסיס ודוגמאות קוד, טופס 'הנפקת מפתח חדש' עם שדה שם המפתח, בחירת סוכן ותוקף וכפתור 'הנפק מפתח', וטבלת 'מפתחות קיימים' עם עמודות שם, מפתח, נוצר, תוקף, שימוש אחרון וסטטוס

לפני שמתחילים

העמוד פתוח למנהל המשרד ולאדמין בלבד. סוכן רגיל לא רואה אותו.
גישת ה-API חייבת להיות מופעלת למשרד. אם היא כבויה, פתיחת העמוד תחזיר אותך להגדרות עם ההודעה "גישת API אינה מופעלת למשרד זה."

איך מגיעים לעמוד

1פתח הגדרות.

2גלול אל "כלים ואינטגרציות" ולחץ על הכרטיס "גישת API".

3נפתח עמוד גישת ה-API עם כתובת הבסיס, טופס הנפקת מפתח וטבלת המפתחות הקיימים.

איך מנפיקים מפתח

1במקטע "הנפקת מפתח חדש" מלא את שדה "שם המפתח" בשם מזהה (למשל "אתר הסוכן").

2אופציונלי: בחר "סוכן" שאליו ישויכו הלידים והלקוחות. ריק = קליטה ברמת המשרד.

3אופציונלי: הגדר "תוקף" לתאריך שבו המפתח יפוג.

4לחץ "הנפק מפתח".

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

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

איך משתמשים במפתח

שלח כל קריאה עם המפתח בכותרת Authorization: Bearer <key> (או לחלופין X-Api-Key).
כתובת הבסיס לכל הקריאות: /api/v1.
העמוד מציג דוגמאות קוד מוכנות להעתקה. החלף בהן את YOUR_API_KEY במפתח שלך.
תיעוד מלא של כל הפעולות והשדות: /api/v1/docs.

externalId: זהו מזהה משלך למניעת כפילויות. שליחה חוזרת של אותו ערך תחזיר את הרשומה המקורית במקום ליצור חדשה. שלח בו את המזהה של הרשומה במערכת שלך.

משיכת נכסים להצגה באתר שלך

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

GET /api/v1/properties — רשימת הנכסים הפומביים, עם עימוד וסינון. פרמטרים אפשריים: city, neighborhood, propertyType, dealType, roomsMin, roomsMax, budgetMax, segment, commercialType, sizeMinSqm, sizeMaxSqm, pricePerSqmMin, pricePerSqmMax, yieldMinPct, page, pageSize (ברירת מחדל 24 בעמוד). כל פריט כולל כתובת, עיר, מחיר, חדרים, שטח, תמונת שער ומיקום. כל פריט הוא מודעה פומבית אחת: נכס שמפורסם גם למכירה וגם להשכרה מופיע כשני פריטים, לכל אחד publicId, slug, סוג עסקה ומחיר משלו, ושניהם עם אותו id. סינון לפי שטח ולפי מחיר למ״ר נמדד מול שטח התמחור של הנכס: נטו, ואם אין - בנוי, ואם אין - קרקע. אותו שטח שהשדה pricePerSqm בתשובה מחושב לפיו.
GET /api/v1/properties/{id} — נכס בודד עם כל הפרטים: תיאור מלא, מאפיינים, גלריית תמונות, מיקום ופרטי הסוכן המטפל.
GET /api/v1/info — פרטי המשרד: שם, לוגו, צבע מותג, רשימת הסוכנים הפעילים, ורשימות עזר (סוגי נכס, ערים, שכונות) לבניית מסנני חיפוש באתר.

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

איך מבטלים מפתח

1בטבלת "מפתחות קיימים" אתר את השורה של המפתח.

2לחץ "בטל" בקצה השורה ואשר את הבקשה.

3הסטטוס משתנה ל"בוטל" וכל מערכת שמשתמשת במפתח מפסיקה לעבוד. הביטול אינו הפיך.

סטטוס מפתח

פעיל — המפתח תקף וניתן לשימוש.
פג תוקף — עבר תאריך התוקף שהוגדר; המפתח כבר לא עובד.
בוטל — המפתח בוטל ידנית ולא ניתן לשחזר אותו.

נכסים מסחריים ב-API

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

1סנן לפי segment (Residential או Commercial) ולפי commercialType כדי למשוך תחום או סוג מסוים.

2הצג נכס מסחרי לפי commercialType ו-netSqm, לא לפי חדרים: בנכס מסחרי rooms ו-baths חוזרים null.

3הצג את המחיר עם הבסיס שלו: priceIncludesVat, managementFeePerSqm, ולצידם pricePerSqm ו-effectiveCostPerSqm (העלות החודשית למ״ר כולל דמי ניהול).

שדות מסחריים בפירוט נכס

שטח ומבנה: netSqm, ceilingHeightM, headcountCapacity, buildingName, buildingClass, fitOutLevel.
חלוקה: divisibility, divisibleUnits, divisibleUnitMinSqm, divisibleUnitMaxSqm.
גישה ושירותים: entranceFrom, toiletsLocation, storageLocation, shelterLocation, parkingAvailability, parkingCostPerSpace.
תשתיות: powerSupplyAmps, floorLoadKgPerSqm.
שימוש ותשואה: permittedUses, ו-advertisedYieldPct במכירה בלבד.

buildingClass חוזר כאות בלבד. A חדש או משופץ, מערכות ברמה גבוהה, מיקום מוביל. B מתוחזק היטב, מפרט ישן או בינוני, מיקום משני. C ישן, גימור בסיסי, דורש השקעה. אתר שמציג את האות בלי ההסבר מציג ללקוח קוד שאין לו דרך לפענח.

שים לב: בנכס מסחרי propertyType מחזיר ערך אחיד לכל הנכסים המסחריים, והסוג האמיתי נמצא ב-commercialType. אתר שמסתמך רק על propertyType יציג מחסן, קליניקה וחנות כאותו דבר.

תפוסה: isTenanted מוחזר רק כשהתפוסה מוצגת בפומבי — במכירה כברירת מחדל, בהשכרה רק אם הסוכן ביקש. אחרת הוא null. תאריך סיום החוזה אינו נשלח ב-API בשום מצב.

שאלות נפוצות

אני לא מוצא את עמוד "גישת API". למה?
העמוד פתוח למנהל המשרד ולאדמין בלבד, ורק כשגישת ה-API מופעלת למשרד. אם אתה סוכן רגיל או שהגישה כבויה, לא תראה אותו.

איבדתי את המפתח, איך אני מקבל אותו שוב?
אי אפשר. המפתח מוצג פעם אחת בלבד בעת ההנפקה ולא נשמר. הנפק מפתח חדש ובטל את הישן.

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

איך אני מונע כפילויות כשהמערכת החיצונית שולחת שוב את אותה רשומה?
שלח שדה externalId עם מזהה משלך. שליחה חוזרת של אותו ערך תחזיר את הרשומה המקורית במקום ליצור כפילות.

מה ההבדל בין Bearer ל-X-Api-Key?
שתי דרכים שקולות להעביר את אותו מפתח בכותרת הבקשה. בחר את מה שנוח למערכת שלך.

אפשר להציג את הנכסים שלי באתר חיצוני דרך ה-API?
כן. משוך אותם עם GET /api/v1/properties ואת הפרטים המלאים עם GET /api/v1/properties/{id}. נחשפים רק נכסים פומביים, בלי פרטי בעלים או מידע פנימי. מומלץ שהשרת של האתר יבצע את הקריאות כדי לא לחשוף את המפתח בדפדפן.