מה זה ומתי צריך את זה
שלוש קריאות API שמחזירות את רשימות הבסיס של החברה: getDepts מחזירה את המחלקות והסניפים, getRoles מחזירה את התפקידים והפרויקטים, ו-getPlaces מחזירה את האתרים (מודול "סעיף תקציבי/אתר"). כל רשומה חוזרת עם המזהה שלה במערכת, ולכן הקריאות האלה הן הצעד הראשון בכל חיבור: מהן מקבלים את מספר המחלקה לסינון דוחות, את מזהה המחלקה לשיוך עובד חדש, ואת הקודים שמקשרים בין EZTime למערכת השכר או ה-ERP שלכם.
מה המדריך הזה כולל
המדריך כולל: מי יכול להשתמש בקריאות ומה צריך כדי שיעבדו, הכתובת, הפרמטרים, מבנה התשובה וכל השדות של כל אחת משלוש הקריאות (מחלקות כרשימה או כעץ ארגוני, תפקידים, אתרים), דוגמאות לבקשה ולתשובה, הודעות שגיאה, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. יצירה של מחלקה, תפקיד או אתר דרך ה-API מוסברת במדריך "API ליצירת מחלקה, תפקיד ואתר". המקומות המותרים לדיווח (נקודה על המפה עם רדיוס) הם נושא אחר, עם מדריך משלו: "מדריך API - הוספת מיקום מותר לדיווח".
🎬 סרטון הסבר קצר
הסרטון מראה איך מקבלים רשימות של מחלקות, תפקידים ואתרים: הכנת שם משתמש וסיסמה של מנהל, בחירת הקריאה המתאימה, שליחת בקשת POST, הוספת תצוגת עץ למחלקות ובדיקת התשובה.
מדריך מקוצר
הכינו שם משתמש וסיסמה של משתמש מנהל במערכת (לא עובד רגיל).
בחרו את הקריאה: api/getDepts למחלקות, api/getRoles לתפקידים, api/getPlaces לאתרים.
שלחו בקשת POST לכתובת של הקריאה (בפרקים 3 עד 5), עם u ו-p כשדות טופס.
למחלקות בתצוגת עץ הוסיפו getDepTree=1.
אם status בתשובה הוא true, הרשימה נמצאת בשדה result.
1. מי יכול להשתמש
סוג משתמש | מה מקבל |
מנהל מערכת | את כל המחלקות, התפקידים והאתרים של החברה. |
מנהל מחלקה, מנהל סידור עבודה וכל סוג מנהל אחר | גם הם את הרשימה המלאה של החברה. הקריאות לא מצמצמות את התשובה למחלקות שהמנהל אחראי עליהן. |
עובד (משתמש רגיל) | נדחה עם ההודעה "no authenticated.". |
החברה נקבעת לפי המשתמש שמזדהה. אין פרמטר של מספר לקוח, ואין דרך לקבל רשימות של חברה אחרת.
2. מה צריך כדי שזה יעבוד
משתמש מנהל פעיל: אותו שם משתמש וסיסמה שאיתם נכנסים לאתר. המשתמש והעובד שמחזיק אותו צריכים להיות פעילים, המשתמש לא מוקפא ותוקף ההתחברות שלו ושל החברה לא פג.
אין מפתח API נפרד: ההזדהות היא רק בשם המשתמש ובסיסמה (u ו-p). מומלץ ליצור משתמש מנהל ייעודי לחיבור, כדי ששינוי סיסמה של מנהל אחר לא ישבור אותו.
שליחה כטופס או בכתובת: הפרמטרים נקראים כשדות טופס (POST) או מהכתובת (GET). גוף JSON לא נקרא. מומלץ POST, כדי שהסיסמה לא תישמר בהיסטוריה ובלוגים של כתובות.
אתרים: מנהלים אתרים רק כשמודול "סעיף תקציבי/אתר" פעיל בחברה (במסך "הגדרות גלובליות", בלשונית "הגדרות כלליות": "הפעל מודול סעיף תקציבי/אתר"). בחברה בלי אתרים מתקבלת רשימה ריקה.
3. רשימת המחלקות: getDepts
פרמטר | חובה? | תיאור | דוגמה |
u | כן | שם המשתמש במערכת | api_user |
p | כן | הסיסמה | MyPass123 |
getDepTree | לא | 0 (ברירת מחדל): רשימה שטוחה של כל המחלקות. 1: עץ ארגוני, כל מחלקה עם מחלקות הבת שלה. | 1 |
השדות של כל מחלקה
שדה | תיאור | סוג |
DeptID | מזהה המחלקה. זה המספר ששולחים בפרמטר dept בקריאות הדוחות, ובפרמטר parent_id כשיוצרים מחלקת בת. | מספר |
DeptName | שם המחלקה או הסניף, כפי שמופיע במסך "ניהול מחלקות/סניפים" | מחרוזת |
code | השדה "קוד" של המחלקה. ריק (null או מחרוזת ריקה) כשלא הוגדר. | מחרוזת או null |
children | רק בתצוגת עץ (getDepTree=1): מחלקות הבת, באותו מבנה. מחלקה בלי מחלקות בת מקבלת מערך ריק. | מערך |
ברשימה השטוחה אין שדה שמראה מי מחלקת האב. כדי לדעת את המבנה הארגוני, שלחו getDepTree=1: ברמה העליונה של העץ מופיעות המחלקות שאין להן "מחלקת אב", ומתחת לכל אחת מחלקות הבת שלה.
דוגמה: רשימה שטוחה
POST https://412.co.il/index.php/api/getDeptsu=api_user&p=MyPass123
{ "status": true, "result": [ { "DeptID": 101, "DeptName": "מטה", "code": "10" }, { "DeptID": 102, "DeptName": "סניף צפון", "code": null }, { "DeptID": 103, "DeptName": "סניף צפון - מחסן", "code": "" } ]}
דוגמה: עץ ארגוני
POST https://412.co.il/index.php/api/getDeptsu=api_user&p=MyPass123&getDepTree=1
{ "status": true, "result": [ { "DeptID": 101, "DeptName": "מטה", "code": "10", "children": [] }, { "DeptID": 102, "DeptName": "סניף צפון", "code": null, "children": [ { "DeptID": 103, "DeptName": "סניף צפון - מחסן", "code": "", "children": [] } ] } ]}
4. רשימת התפקידים: getRoles
כתובת: https://412.co.il/index.php/api/getRoles (עם R גדולה). פרמטרים: u ו-p בלבד.
שימו לב למבנה: result הוא אובייקט שהמפתחות שלו הם מזהי התפקידים, ולא מערך. עברו על הערכים שלו. בחברה בלי תפקידים בכלל, result מגיע כמערך ריק ([]).
התשובה כוללת את כל התפקידים, גם אלה שסומנו "לא פעיל". סננו לפי role_status אם אתם צריכים רק פעילים.
השדות של כל תפקיד
שדה | תיאור | השדה במסך "תפקיד/פרויקט" |
INTERNAL_ID | מזהה התפקיד (מספר) | - |
role_name | שם התפקיד או הפרויקט | "תפקיד/פרויקט" |
ROLE_CODE | קוד התפקיד | "קוד" |
export_code | קוד התפקיד בייצוא לשכר | "קוד לייצוא שכר" |
device_code | מספר התפקיד שהעובד בוחר בשעון הנוכחות | "קוד תפקיד/פרויקט בשעון נוכחות" |
price_hour | שכר שעתי לתפקיד | "שכר שעתי לתפקיד/פרויקט זה" |
role_color | הצבע של התפקיד | "צבע" |
role_status | 1 = פעיל, 0 = לא פעיל | "סטטוס" |
sync_shift_role | מזהה התפקיד בסידור העבודה שהתפקיד מסונכרן איתו, או null כשאין סנכרון | "סנכרן תפקיד/פרויקט עם תפקיד לסידור עבודה" |
group_ids | מזהי התחומים שהתפקיד משויך אליהם (מערך מספרים, ריק כשאין) | "תחום לתפקיד/פרוייקט" |
שדות שלא מולאו במסך מגיעים ריקים ("") או null.
דוגמה
POST https://412.co.il/index.php/api/getRolesu=api_user&p=MyPass123
{ "status": true, "result": { "12": { "INTERNAL_ID": 12, "role_name": "מלצר", "ROLE_CODE": "3", "role_color": "#2E7D32", "device_code": "1", "price_hour": 40, "role_status": 1, "export_code": "103", "sync_shift_role": 57, "group_ids": [4] }, "15": { "INTERNAL_ID": 15, "role_name": "אחראי משמרת", "ROLE_CODE": "", "role_color": "", "device_code": "", "price_hour": 0, "role_status": 0, "export_code": null, "sync_shift_role": null, "group_ids": [] } }}
5. רשימת האתרים: getPlaces
כתובת: https://412.co.il/index.php/api/getPlaces. פרמטרים: u ו-p בלבד.
האתרים הם הרשימה שבמסך ניהול דיווחים ← "אתרים" ← "רשימת אתרים" (מודול "סעיף תקציבי/אתר"). אלה לא המקומות המותרים לדיווח שעל המפה: לאלה אין כרגע קריאה שמחזירה רשימה.
השדות של כל אתר
שדה | תיאור | השדה במסך |
id | מזהה האתר. שימו לב: הוא עשוי להגיע כמחרוזת (למשל "7"), לכן השוו אותו כטקסט או המירו למספר. | - |
name | שם האתר | "שם אתר" |
code | קוד האתר, ריק כשלא הוגדר | "קוד" |
status | 1 = פעיל, 0 = כבוי | "סטטוס" |
note | הערה | "הערה" |
התשובה כוללת גם אתרים כבויים. השעונים, המדבקות והטאבלטים שמשויכים לאתר לא חוזרים בקריאה הזו.
דוגמה
POST https://412.co.il/index.php/api/getPlacesu=api_user&p=MyPass123
{ "status": true, "result": [ { "id": "7", "name": "אתר בנייה נתניה", "code": "N-01", "status": 1, "note": "" }, { "id": "8", "name": "מחסן ראשי", "code": "", "status": 0, "note": "נסגר בסוף השנה" } ]}
6. מגבלות
לשלוש הקריאות האלה אין מגבלת קריאות בשעה, בשונה מ-getDaily ומהדוח המסכם (5 קריאות בשעה). בכל זאת, הרשימות משתנות לעיתים רחוקות: מספיק למשוך אותן פעם ביום או לפני סנכרון, ולשמור אצלכם.
הקריאות רק קוראות. הן לא משנות שום דבר במערכת.
אין סינון בצד שלנו: כל קריאה מחזירה את הרשימה המלאה של החברה.
הודעות שגיאה
בכישלון התשובה היא {"status": false, "errors": {"auth": "…"}}, כלומר ההודעה נמצאת בתוך errors.auth.
ההודעה ב-errors.auth | מה זה אומר | מה עושים |
no authenticated (בלי נקודה) | לא נשלחו u ו-p | הוסיפו אותם כשדות טופס או בכתובת, לא בתוך JSON ולא בכותרות (Headers) |
no authenticated. (עם נקודה) | שם משתמש או סיסמה שגויים, משתמש לא פעיל, מוקפא או שתוקפו פג, או משתמש מסוג "עובד" | בדקו שאפשר להיכנס לאתר עם אותם פרטים, והשתמשו במשתמש מנהל |
שאלות נפוצות ופתרון בעיות
❓ שלחתי קריאה וקיבלתי "no authenticated."
שם המשתמש או הסיסמה לא נכונים, או שהמשתמש הוא עובד רגיל, מוקפא או לא פעיל. נסו להיכנס לאתר עם אותם פרטים בדיוק, ובדקו שסוג המשתמש הוא מנהל. אם יש בסיסמה תווים כמו &, + או #, ודאו שהם מקודדים בכתובת.
❓ קיבלתי "no authenticated" בלי נקודה
השרת לא קיבל את u ואת p. כנראה שנשלחו בגוף JSON או בכותרות. שלחו אותם כשדות טופס (x-www-form-urlencoded) או בכתובת.
❓ איפה מוצאים את מספר המחלקה לפרמטר dept בדוחות?
זה השדה DeptID בתשובה של getDepts. אותו מספר משמש בפרמטר dept של "API ליצוא הנתונים של הדוח המסכם לכל העובדים".
❓ איך יודעים איזו מחלקה שייכת לאיזו?
שלחו getDepts עם getDepTree=1. כל מחלקה מגיעה עם children, מחלקות הבת שלה. ברשימה השטוחה אין את המידע הזה.
❓ מנהל מחלקה קרא ל-getDepts וקיבל את כל המחלקות של החברה
זה מכוון: הקריאות מחזירות את הרשימה המלאה לכל סוג מנהל. אם המערכת שלכם צריכה רק חלק מהמחלקות, סננו אצלכם לפי DeptID.
❓ קוד המחלקה מגיע לפעמים null ולפעמים ריק
שני המצבים אומרים שלא הוגדר קוד למחלקה. התייחסו לשניהם אותו דבר.
❓ ב-getRoles קיבלתי אובייקט ולא מערך, והחיבור שלי נכשל
result של getRoles הוא אובייקט שהמפתחות שלו הם מזהי התפקידים. עברו על הערכים שלו. כשאין לחברה תפקידים, result מגיע כמערך ריק, אז ודאו שהמערכת שלכם מטפלת בשני המצבים.
❓ תפקיד שהפכתי ל"לא פעיל" עדיין מופיע
getRoles מחזירה את כל התפקידים. תפקיד לא פעיל מגיע עם role_status 0. סננו לפיו.
❓ איך יודעים לאיזה תחום שייך תפקיד?
לפי group_ids: מזהי התחומים שהתפקיד משויך אליהם. את התחומים עצמם מגדירים במסך, כמו שמוסבר ב"הוספת תחום/קבוצה לתפקידים ופרוייקטים". אין קריאה שמחזירה את רשימת התחומים עם השמות שלהם.
❓ getPlaces מחזירה רשימה ריקה
אין אתרים בחברה, או שמודול "סעיף תקציבי/אתר" לא פעיל ולכן לא הוגדרו אתרים. בדקו במסך ניהול דיווחים ← "אתרים". אם האפשרות "אתרים" לא מופיעה בתפריט, פנו לשירות הלקוחות.
❓ חיפשתי ב-getPlaces את המקומות המותרים לדיווח ולא מצאתי
getPlaces מחזירה אתרים (מודול "סעיף תקציבי/אתר"), לא את המקומות המותרים לדיווח שעל המפה. את המקומות המותרים רואים במסך ניהול דיווחים ← "מקומות מותרים לדיווח", ומוסיפים דרך ה-API לפי "מדריך API - הוספת מיקום מותר לדיווח".
❓ id של אתר מגיע כטקסט ולא כמספר
כן, השדה id עשוי להגיע כמחרוזת. השוו אותו כטקסט או המירו אותו למספר לפני ההשוואה.
❓ אני מקבל "no_have_permission"
שלוש הקריאות האלה לא מחזירות את ההודעה הזו. אם קיבלתם אותה, היא הגיעה מקריאה אחרת, כמו getDaily או getEmp, שתלויות בהגדרות החבילה של החברה. פנו לתמיכה לגבי אותה קריאה.
❓ אפשר לקבל רק מחלקה אחת, או לחפש לפי שם?
לא. הקריאות מחזירות את כל הרשימה. חפשו וסננו במערכת שלכם.
❓ איך מוסיפים מחלקה, תפקיד או אתר חדשים דרך ה-API?
בקריאות createDept, createRole ו-createPlace, שמוסברות ב"API ליצירת מחלקה, תפקיד ואתר". אחרי היצירה הרשומה החדשה מופיעה מיד בקריאות של המדריך הזה.
❓ איך בודקים את הקריאה לפני שמחברים מערכת?
ב-Postman: בחרו POST, הדביקו את הכתובת, ובלשונית Body בחרו x-www-form-urlencoded והוסיפו את u ואת p. הקריאות רק קוראות, אז אפשר לבדוק כמה פעמים שצריך.
מילון מונחים
u / p - שם המשתמש והסיסמה של משתמש מנהל, שבהם הקריאה מזדהה.
DeptID - מזהה המחלקה במערכת.
עץ ארגוני - המחלקות לפי "מחלקת אב", כל מחלקה עם מחלקות הבת שלה (getDepTree=1).
INTERNAL_ID - מזהה התפקיד במערכת.
תחום - קבוצה של תפקידים ופרויקטים ("תחום לתפקיד/פרוייקט"), במערך group_ids.
אתר - רשומה במודול "סעיף תקציבי/אתר", שאליה אפשר לשייך שעות, שעונים, מדבקות וטאבלטים.
result - הרשימה שחוזרת כשהקריאה הצליחה.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
לקבל את כל המחלקות | api/getDepts עם u, p | DeptID, DeptName, code לכל מחלקה |
לקבל את המבנה הארגוני | api/getDepts עם getDepTree=1 | כל מחלקה עם children |
לקבל את התפקידים והקודים שלהם | api/getRoles עם u, p | אובייקט לפי מזהה, כולל לא פעילים |
לקבל את האתרים | api/getPlaces עם u, p | id, name, code, status, note לכל אתר |
להוסיף מחלקה, תפקיד או אתר | createDept, createRole, createPlace | ראו "API ליצירת מחלקה, תפקיד ואתר" |
מאמרים קשורים