ממשק ה-API של מערכת OXS

מהו ממשק ה-API של OXS

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

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

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

היתרונות: למה כדאי להשתמש בממשק

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

אוטומציה ואינטגרציה

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

שירות לדיירים

• הצגת קריאות השירות של הדיירים באתר או באפליקציה של החברה.

כספים וגבייה

• משיכת חובות דיירים לדוחות פנימיים או למערכת הנהלת חשבונות.
• הצגת אחוז הגבייה לכל בניין ולחברה כולה, ומעקב אחר מגמות (החודש מול הקודם).

אחזקה ותפעול

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

דיווח

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

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

הפעלת השירות

גישת API אינה פעילה כברירת מחדל; היא מופעלת על ידי תמיכת OXS בלבד.

1. פנו לתמיכת OXS ובקשו להפעיל את שירות ה-API.
2. לאחר ההפעלה יופיע טאב חדש, "מפתחות API", במסך "הגדרות חברה". לפני ההפעלה הטאב אינו מוצג כלל.
3. צרו מפתח לכל מערכת חיצונית (ראו "ניהול מפתחות" בהמשך).

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

מודולים ורמות גישה

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

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

פירוט המודולים

קריאות שירות

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

חובות דיירים

המודול חושף חובות ויתרות של דיירים, ושתי יכולות נוספות:

• קישור תשלום: המודול מחזיר לכם קישור תשלום לדייר, אך אינו שולח אותו. אתם מחליטים איך ומתי לשלוח. השליחה האוטומטית מתוך OXS (לשונית "הודעות" של הדירה) ממשיכה לעבוד בנפרד.
• סיכום גבייה: לכל החברה או לבניין אחד, לטווח של עד 24 חודשים. מוחזרים יעד גבייה, כמה נגבה, יתרה פתוחה ואחוז גבייה.

איך לקרוא את סיכום הגבייה:

• תשלומים שוטפים מוצגים בסך הכול ולכל חודש; תשלומים מיוחדים לכל חיוב בנפרד ובסך הכול; ובנוסף סך הכול משולב.
• אחוז הגבייה המשולב מחושב מהסכומים המחוברים, לא כממוצע.
• "חודש" הוא החודש שעבורו החיוב. "נגבה" הוא מה ששולם על חיובי אותו חודש, מתי שלא שולם.
• נתוני חודשים קודמים משתנים כשדייר משלם חוב ישן. לצורך היסטוריה קפואה, שמרו תמונת מצב אצלכם.
• נספרים רק בניינים ודירות הפעילים היום, כמו במסכי OXS.
• הנתונים זהים למסך התשלומים של הבניין. במסך הסכומים מעוגלים לשקל, לכן אחוז הגבייה עשוי להיות שונה ב-1. ב-API מוצגים כל החיובים המיוחדים, ולא רק 12.
• היתרה הפתוחה כוללת גם חודשים שמועדם טרם הגיע, ולכן אינה זהה לחוב בדוח החובות.

מידע כללי

רשימת בניינים, דירות בבניין, דיירים בבניין והיסטוריית תשלומים, ברמת קריאה בלבד. שתי הפעולות לצפייה בדיירים במודול זה יוצאות משימוש; מומלץ לעבור למודול "דיירים". מועד הסגירה טרם נקבע, ותינתן הודעה מראש.

דיירים

המודול מאפשר לעבוד עם הדיירים ואנשי הקשר בדירות, בדיוק כמו מנהל במסך הדירה ב-OXS.

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

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

פרטי אשראי, תעודת זהות ונתוני אפליקציה לעולם אינם מוחזרים.

אחזקה

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

מה אפשר לקבל:

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

בכל סיכום בוחרים לספור לפי התאריך המתוכנן (מה היה אמור להתבצע וכמה בוצע) או לפי תאריך הסגירה (מה נסגר בפועל בתקופה).

חשוב לדעת:

• הסטטוס הוא תמיד המצב היום; אין היסטוריית סטטוסים.
• משימה שבוצעה בשטח אך לא נסגרה במערכת נספרת כפתוחה או כחריגה. סגרו משימות ב-OXS כדי שהנתונים יהיו מדויקים.
• משימה ללא עלות בפועל תופיע עם עלות 0.
• לביקורת אין תוצאת "עבר / נכשל" או תוקף אישור; מוחזרים רק סטטוס הסגירה, הערת הסגירה ומספר הקבצים.
• ביקורת היא סוג משימה המסומן כביקורת (היום: "ביקורת" ו"ביקורת מעליות"); כל השאר נספר כאחזקה.
• קריאות שירות אינן חלק מהמודול.
• טווח תאריכים בבקשה: עד 24 חודשים. רשימות מוחזרות בעמודים של 50.
• פרטי קשר של צוות וספקים, קבצים, תמונות ויומן הטיפול אינם מוחזרים.

ניהול מפתחות

כל הפעולות על המפתחות מרוכזות בטאב "מפתחות API" שבהגדרות החברה.

יצירת מפתח

לחצו על "יצירת מפתח חדש" ומלאו:

• שם (חובה): למשל "אתר החברה" או "הנהלת חשבונות". זו הדרך היחידה לזהות את המפתח לאורך זמן.
• מודול: התחום שהמפתח יקבל אליו גישה.
• רמת גישה: קריאה בלבד או שליטה מלאה, לפי המודול.
• תאריך תפוגה: ברירת המחדל היא שנה; אפשר לבחור עד שנתיים קדימה.

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

רוטציה

: החלפת מפתח

רוטציה יוצרת מפתח חדש במקום הקיים, והמפתח הישן ממשיך לעבוד 24 שעות כדי למנוע השבתה (OXS יכולה להגדיר חלון של עד 7 ימים). בחלון הזה עדכנו את המפתח החדש בכל המערכות. משתמשים ברוטציה כשמפתח נחשף או כנוהג אבטחה תקופתי.

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

השבתה והפעלה

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

תפוגה ותזכורות

לכל מפתח יש תאריך תפוגה; אין מפתחות נצחיים.

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

פעולות שדורשות פנייה לתמיכה

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

מעקב שימוש, סטטוסים ומגבלות

מעקב שימוש

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

סטטוסים בטבלת המפתחות

מגבלות קצב

לכל מפתח: 60 בקשות בדקה ו-1,000 בקשות בשעה. חריגה גורמת לדחייה זמנית של בקשות עד תחילת החלון הבא. צריכים יותר? פנו לתמיכת OXS.

כללי אבטחה

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

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

כל מפתח מוגבל לחברה שלכם בלבד; ניסיון לגשת לנתוני חברה אחרת נדחה.

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

עלויות