מה זה ומתי צריך את זה
שלוש קריאות API שיוצרות רשומות בסיס חדשות בחברה בלי להיכנס למסכים: createDept יוצרת מחלקה או סניף, createRole יוצרת תפקיד או פרויקט, ו-createPlace יוצרת אתר (מודול "סעיף תקציבי/אתר"). זה שימושי כשמערכת אחרת, כמו ERP, מערכת משאבי אנוש או מערכת פרויקטים, היא המקור של הרשימות, ורוצים שכל סניף, פרויקט או אתר חדש שנפתח שם ייפתח מיד גם ב-EZTime. כל קריאה מחזירה את המזהה של הרשומה החדשה, כדי שתוכלו לשמור את הקישור אצלכם.
מה המדריך הזה כולל
המדריך כולל: מי יכול להשתמש בקריאות ומה צריך כדי שיעבדו, איך שולחים את הבקשה, הפרמטרים של כל קריאה ומה כל אחד מהם שווה במסך, התשובה בהצלחה, דוגמאות, הודעות שגיאה, מה הקריאות לא עושות (עריכה, מחיקה, כפילויות), שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. קבלת הרשימות הקיימות מוסברת במדריך "API לקבלת רשימת מחלקות, תפקידים ואתרים". הוספת מקום מותר לדיווח על המפה היא קריאה אחרת, במדריך "מדריך API - הוספת מיקום מותר לדיווח".
🎬 סרטון הסבר קצר
הסרטון מראה איך יוצרים מחלקה, תפקיד ואתר דרך API: הכנת שם משתמש וסיסמה של מנהל, בחירת הקריאה, שליחת POST עם u, p והשם, הוספת שדות רשות, שמירת המזהה שחזר ובדיקת הרשומה החדשה במערכת.
מדריך מקוצר
הכינו שם משתמש וסיסמה של משתמש מנהל במערכת (לא עובד רגיל).
בחרו את הקריאה: api/createDept למחלקה, api/createRole לתפקיד, api/createPlace לאתר.
שלחו POST כטופס, עם u, p והשם: name למחלקה ולאתר, role_name לתפקיד.
הוסיפו את השדות הרשות שאתם צריכים, כמו code או parent_id.
אם status בתשובה הוא true, שמרו את המזהה שחזר (DeptID, INTERNAL_ID או id).
בדקו את הרשומה החדשה במסך המתאים במערכת.
1. מי יכול להשתמש
סוג משתמש | מה קורה |
מנהל מערכת או כל סוג מנהל אחר | הרשומה נוצרת בחברה של המשתמש. |
עובד (משתמש רגיל) | נדחה עם ההודעה "no authenticated.". שום דבר לא נוצר. |
מומלץ ליצור משתמש מנהל מערכת ייעודי לחיבור (למשל api_user), במקום המשתמש האישי של מנהל. כך שינוי סיסמה או עזיבה של מנהל לא ישברו את החיבור.
2. מה צריך כדי שזה יעבוד
משתמש מנהל פעיל: אותו שם משתמש וסיסמה שאיתם נכנסים לאתר. המשתמש והעובד שלו פעילים, המשתמש לא מוקפא, ותוקף ההתחברות שלו ושל החברה לא פג.
אין מפתח API נפרד: ההזדהות היא רק ב-u וב-p. החברה נקבעת לפי המשתמש, ואין פרמטר של מספר לקוח.
שליחה כטופס: שלחו POST עם שדות טופס (x-www-form-urlencoded או multipart/form-data), בקידוד UTF-8. גוף JSON לא נקרא, ואז השדות מגיעים ריקים. פרמטרים בכתובת (GET) נקראים גם הם, אבל לקריאות שיוצרות נתונים עדיף POST, כדי שהסיסמה לא תישמר בלוגים של כתובות.
לאתרים: כדי לראות ולנהל את האתרים במסך, מודול "סעיף תקציבי/אתר" צריך להיות פעיל בחברה (במסך "הגדרות גלובליות", בלשונית "הגדרות כלליות").
3. יצירת מחלקה: createDept
פרמטר | חובה? | תיאור | השדה במסך | דוגמה |
u, p | כן | שם המשתמש והסיסמה של משתמש מנהל | - | api_user, MyPass123 |
name | כן | שם המחלקה או הסניף. רווחים בתחילה ובסוף נמחקים. | "שם מחלקה" | סניף חיפה |
code | לא | קוד המחלקה, למשל המספר שלה במערכת השכר | "קוד" | 40 |
parent_id | לא | DeptID של מחלקה קיימת בחברה, שתהיה מחלקת האב של החדשה. בלי הפרמטר המחלקה נוצרת ברמה העליונה של העץ. | "מחלקת אב" | 101 |
בהצלחה התשובה היא {"status": true, "DeptID": …} עם המזהה של המחלקה החדשה.
הקריאה לא מגדירה מנהלי מחלקה. את "מנהלי מחלקה/סניף" בוחרים אחר כך במסך "עובדים" ← "ניהול מחלקות/סניפים", בעריכת המחלקה.
POST https://412.co.il/index.php/api/createDeptu=api_user&p=MyPass123&name=סניף חיפה&code=40&parent_id=101
{ "status": true, "DeptID": 104 }
4. יצירת תפקיד: createRole
פרמטר | חובה? | תיאור | השדה במסך "תפקיד/פרויקט" | דוגמה |
u, p | כן | שם המשתמש והסיסמה של משתמש מנהל | - | api_user, MyPass123 |
role_name | כן | שם התפקיד או הפרויקט | "תפקיד/פרויקט" | מלצר |
ROLE_CODE | לא | קוד התפקיד (באותיות גדולות, בדיוק כך) | "קוד" | 3 |
export_code | לא | קוד התפקיד בייצוא לשכר | "קוד לייצוא שכר" | 103 |
device_code | לא | המספר שהעובד בוחר בשעון הנוכחות כדי לדווח על התפקיד | "קוד תפקיד/פרויקט בשעון נוכחות" | 1 |
price_hour | לא | שכר שעתי לתפקיד, מספר עם נקודה עשרונית | "שכר שעתי לתפקיד/פרויקט זה" | 42.5 |
role_color | לא | צבע התפקיד, כקוד צבע (hex) | "צבע" | #2E7D32 |
role_status | לא | 1 = פעיל (ברירת מחדל), 0 = לא פעיל | "סטטוס" | 1 |
sync_shift_role | לא | מזהה של תפקיד קיים בסידור העבודה, שהתפקיד החדש יסונכרן איתו | "סנכרן תפקיד/פרויקט עם תפקיד לסידור עבודה" | 57 |
group_ids | לא | מזהי תחומים קיימים לשיוך התפקיד. נשלחים כמערך: group_ids[]=4&group_ids[]=7 | "תחום לתפקיד/פרוייקט" | 4 |
בהצלחה התשובה היא {"status": true, "INTERNAL_ID": …} עם המזהה של התפקיד החדש.
role_status: שלחו רק 1 או 0. ערך שאינו מספר (למשל true או active) נשמר כ-0, והתפקיד ייווצר לא פעיל.
group_ids: ערך בודד בלי סוגריים (group_ids=4) לא נקרא, והתפקיד נוצר בלי תחום. גם לתחום אחד שלחו group_ids[]=4.
sync_shift_role: הקריאה רק מקשרת לתפקיד סידור עבודה שכבר קיים. היא לא יוצרת תפקיד חדש בסידור העבודה, כמו שקורה כשמסמנים את האפשרות במסך בזמן הוספת תפקיד.
הגדרות נוספות של התפקיד (למשל הגבלת שעות או "סנכרן להוצאה") לא נשלחות בקריאה. אם צריך אותן, ערכו את התפקיד במסך ניהול דיווחים ← "תפקיד/פרויקט".
POST https://412.co.il/index.php/api/createRoleu=api_user&p=MyPass123&role_name=מלצר&ROLE_CODE=3&export_code=103&device_code=1&price_hour=42.5&group_ids[]=4
{ "status": true, "INTERNAL_ID": 21 }
5. יצירת אתר: createPlace
פרמטר | חובה? | תיאור | השדה במסך "אתרים" | דוגמה |
u, p | כן | שם המשתמש והסיסמה של משתמש מנהל | - | api_user, MyPass123 |
name | כן | שם האתר. רווחים בתחילה ובסוף נמחקים. | "שם אתר" | אתר בנייה נתניה |
code | לא | קוד האתר | "קוד" | N-01 |
status | לא | 1 = פעיל (ברירת מחדל), 0 = כבוי | "סטטוס" ("פעיל" / "כבוי") | 1 |
note | לא | הערה | "הערה" | כניסה משער 2 |
בהצלחה התשובה היא {"status": true, "id": …} עם המזהה של האתר החדש.
הקריאה יוצרת את האתר בלבד. שיוך של "שעוני נוכחות", "מדבקות NFC" ו"טאבלטים" לאתר נעשה במסך ניהול דיווחים ← "אתרים" ← "רשימת אתרים", בעריכת האתר (סמל העיפרון).
POST https://412.co.il/index.php/api/createPlaceu=api_user&p=MyPass123&name=אתר בנייה נתניה&code=N-01&status=1¬e=כניסה משער 2
{ "status": true, "id": 9 }
6. מה חשוב לדעת לפני שמחברים
אין בדיקת כפילויות: שלוש הקריאות לא בודקות אם כבר קיימת רשומה באותו שם. כל קריאה יוצרת רשומה חדשה, גם במחלקות, שבמסך לא מאפשר שני שמות זהים. לפני שיוצרים, משכו את הרשימה הקיימת (getDepts, getRoles, getPlaces) ובדקו אם השם כבר קיים.
אחרי שגיאת רשת: אם לא קיבלתם תשובה, ייתכן שהרשומה נוצרה בכל זאת. בדקו ברשימה לפני שאתם שולחים שוב.
רק יצירה: אין קריאות לעריכה או למחיקה של מחלקה, תפקיד או אתר. קריאה חוזרת עם אותו שם לא מעדכנת, היא יוצרת רשומה נוספת. עריכה ומחיקה נעשות במסכים.
אין מגבלת קריאות: לקריאות האלה אין מגבלה בשעה. כשיוצרים הרבה רשומות, שלחו אותן בזו אחר זו ולא במקביל, ובדקו את status של כל אחת.
אין no_have_permission: הקריאות האלה לא תלויות בהגדרות החבילה, בשונה מ-getDaily, מהדוח המסכם ומרשימת העובדים.
קוד HTTP: גם קריאה שנכשלה מחזירה בדרך כלל קוד 200. בדקו תמיד את status בגוף התשובה.
הודעות שגיאה
בכישלון התשובה היא {"status": false, "errors": {…}}: שם השדה שנכשל, וההודעה עליו. שום רשומה לא נוצרת.
השגיאה | קריאה | מה זה אומר | מה עושים |
"auth": "no authenticated" | כולן | לא נשלחו u ו-p | שלחו אותם כשדות טופס, לא בתוך JSON ולא בכותרות |
"auth": "no authenticated." | כולן | שם משתמש או סיסמה שגויים, משתמש לא פעיל, מוקפא או שתוקפו פג, או משתמש מסוג "עובד" | בדקו כניסה לאתר עם אותם פרטים, והשתמשו במשתמש מנהל |
"name": "name is required" | createDept, createPlace | name חסר או ריק | שלחו שם. אם שלחתם, כנראה שהנתונים נשלחו כ-JSON |
"parent_id": "Parent department not found" | createDept | אין בחברה מחלקה עם ה-DeptID הזה | קחו את המזהה מ-getDepts |
"role_name": "role_name is required" | createRole | role_name חסר או ריק | שלחו את שם התפקיד ב-role_name (לא name) |
"sync_shift_role": "Shift role not found" | createRole | אין בחברה תפקיד סידור עבודה עם המזהה הזה | שלחו בלי הפרמטר, וקשרו במסך אחרי היצירה |
"group_ids": "Group ID … not found" | createRole | אחד התחומים ברשימה לא קיים בחברה (המספר מופיע בהודעה) | תקנו או הסירו את המזהה ושלחו שוב. התפקיד לא נוצר |
{ "status": false, "errors": { "parent_id": "Parent department not found" } }
שאלות נפוצות ופתרון בעיות
❓ שלחתי את הנתונים כ-JSON וקיבלתי "name is required"
הקריאות קוראות רק שדות טופס. שלחו POST עם x-www-form-urlencoded (או multipart/form-data), וכל שדה בנפרד.
❓ קיבלתי "no authenticated."
שם המשתמש או הסיסמה לא נכונים, או שהמשתמש הוא עובד רגיל, לא פעיל או מוקפא. נסו להיכנס לאתר עם אותם פרטים בדיוק. תווים כמו &, + או # בסיסמה צריכים קידוד, וספריות HTTP שמקבלות את השדות כרשימה עושות זאת לבד.
❓ יצרתי מחלקה והיא נוצרה פעמיים
הקריאה לא בודקת כפילויות, אז כל שליחה יוצרת מחלקה. מחקו את המיותרת במסך "עובדים" ← "ניהול מחלקות/סניפים", ובמערכת שלכם בדקו את הרשימה (getDepts) לפני כל יצירה.
❓ קיבלתי "Parent department not found"
parent_id צריך להיות DeptID של מחלקה קיימת באותה חברה, מספר בלבד. קחו אותו מ-getDepts, ולא את שם המחלקה או את קוד המחלקה.
❓ המחלקה נוצרה בלי מנהל
זה מכוון: הקריאה לא מגדירה מנהלי מחלקה. בחרו אותם במסך "ניהול מחלקות/סניפים", בעריכת המחלקה.
❓ שלחתי name ליצירת תפקיד וקיבלתי "role_name is required"
בתפקידים שם השדה הוא role_name, ובמחלקות ובאתרים הוא name.
❓ התפקיד נוצר כ"לא פעיל"
כנראה שנשלח role_status עם ערך שאינו 1, למשל true או active. שלחו 1, או השאירו את הפרמטר בחוץ (ברירת המחדל היא פעיל). את התפקיד שנוצר הפעילו במסך "תפקיד/פרויקט".
❓ שלחתי group_ids והתפקיד נוצר בלי תחום
שלחתם ערך בודד (group_ids=4). שלחו כמערך: group_ids[]=4, וגם group_ids[]=7 לתחום נוסף.
❓ קיבלתי "Group ID 9 not found"
התחום עם המזהה הזה לא קיים בחברה, ולכן התפקיד לא נוצר בכלל. מזהי התחומים של תפקידים קיימים מופיעים ב-group_ids של getRoles. את התחומים עצמם מנהלים במסך, כמו שמוסבר ב"הוספת תחום/קבוצה לתפקידים ופרוייקטים".
❓ איך מקשרים את התפקיד החדש לתפקיד בסידור העבודה?
אם אתם יודעים את מזהה התפקיד בסידור העבודה, שלחו אותו ב-sync_shift_role. אם לא, צרו את התפקיד בלי הפרמטר, ואז במסך ניהול דיווחים ← "תפקיד/פרויקט" ערכו אותו, סמנו "סנכרן תפקיד/פרויקט עם תפקיד לסידור עבודה" ובחרו מהרשימה "תפקידים לסידור עבודה".
❓ יצרתי אתר ואני לא רואה אותו במסך
האפשרות "אתרים" מופיעה בתפריט ניהול דיווחים רק כשמודול "סעיף תקציבי/אתר" פעיל בחברה. אם היא לא מופיעה, פנו לשירות הלקוחות. אם היא מופיעה, חפשו את האתר בשדה החיפוש של "רשימת אתרים", ובדקו שנכנסתם לאותה חברה של המשתמש ששלח את הקריאה.
❓ יצרתי אתר דרך createPlace ועובדים לא יכולים להחתים ממנו לפי מיקום
אתר הוא לא מקום מותר לדיווח על המפה. למקום מותר עם קווי רוחב, אורך ורדיוס יש קריאה אחרת, add_location, במדריך "מדריך API - הוספת מיקום מותר לדיווח".
❓ איך משייכים שעון או מדבקת NFC לאתר שנוצר?
במסך ניהול דיווחים ← "אתרים" ← "רשימת אתרים", לחצו על העיפרון של האתר ובחרו את השעונים, המדבקות או הטאבלטים. הקריאה לא עושה את השיוך.
❓ אפשר לעדכן או למחוק מחלקה, תפקיד או אתר דרך ה-API?
לא. יש רק יצירה. קריאה חוזרת עם אותו שם יוצרת רשומה נוספת. עריכה ומחיקה נעשות במסכים "ניהול מחלקות/סניפים", "תפקיד/פרויקט" ו"אתרים".
❓ איך משייכים עובד למחלקה או לתפקיד שיצרתי?
כשיוצרים או מעדכנים עובד דרך ה-API, שולחים את המחלקה והתפקידים שלו, כמו שמוסבר ב"הוספת עובד JSON API". אפשר גם לשייך במסך, בכרטיס העובד.
❓ איך בודקים לפני שמחברים מערכת?
ב-Postman: POST לכתובת הקריאה, לשונית Body ← x-www-form-urlencoded, ושורה לכל שדה. כל בדיקה יוצרת רשומה אמיתית בחברה, לכן צרו רשומת בדיקה אחת, בדקו אותה במסך, ומחקו אותה שם.
❓ קיבלתי status true אבל המזהה שחזר לא נשמר אצלי
הרשומה נוצרה. כדי לא ליצור אותה שוב, משכו את הרשימה (getDepts, getRoles או getPlaces), מצאו אותה לפי השם ושמרו את המזהה שלה.
מילון מונחים
u / p - שם המשתמש והסיסמה של משתמש מנהל, שבהם הקריאה מזדהה.
DeptID - מזהה המחלקה. חוזר מ-createDept, ומשמש ב-parent_id.
מחלקת אב - המחלקה שמעל המחלקה החדשה בעץ הארגוני.
INTERNAL_ID - מזהה התפקיד. חוזר מ-createRole.
תחום - קבוצה של תפקידים ופרויקטים ("תחום לתפקיד/פרוייקט"), שנשלחת ב-group_ids.
אתר - רשומה במודול "סעיף תקציבי/אתר", שאליה משייכים שעות, שעונים, מדבקות וטאבלטים.
שדות טופס - הדרך שבה נשלחים הפרמטרים (x-www-form-urlencoded), בשונה מ-JSON.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
ליצור מחלקה או סניף | api/createDept עם name (ו-code, parent_id) | מחלקה חדשה, מחזיר DeptID |
ליצור מחלקת בת | createDept עם parent_id = DeptID של האב | המחלקה נכנסת מתחת לאב בעץ |
ליצור תפקיד או פרויקט | api/createRole עם role_name ושדות רשות | תפקיד חדש, מחזיר INTERNAL_ID |
ליצור אתר | api/createPlace עם name (ו-code, status, note) | אתר חדש, מחזיר id |
למנוע כפילויות | getDepts / getRoles / getPlaces לפני היצירה | הקריאות לא בודקות שמות קיימים |
לערוך או למחוק | במסכים בלבד | אין קריאה לעריכה או למחיקה |
מאמרים קשורים