מה זה ומתי צריך את זה
ה-API הזה מאפשר למערכת חיצונית (למשל מערכת משאבי אנוש) ליצור עובד חדש ב-EZTime בלי להקליד אותו ידנית. אם כבר קיים בחברה עובד עם אותו מספר עובד, הבקשה מעדכנת אותו במקום ליצור עובד נוסף.
מה המדריך הזה כולל
המדריך כולל: מדריך מקוצר, מי יכול להשתמש ב-API, מה צריך לפני השימוש, כתובת ואופן שליחה, טבלת כל הפרמטרים, יצירה מול עדכון, דוגמת בקשה ותשובה, טבלת הודעות שגיאה, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. גרסה נוספת של אותו API, שמקבלת גוף JSON, מתוארת במדריך "הוספת עובד JSON API". מאמרים קשורים מופיעים בסוף.
המדריך מתאים למפתח או לאיש מחשבים של החברה. ה-API אינו מסך במערכת, ולכן אין בו צילומי מסך.
🎬 סרטון הסבר קצר
הסרטון מראה איך מוסיפים עובד חדש דרך ה-API: הכנת שם משתמש וסיסמה של מנהל, בדיקה שהמחלקות, התפקידים, המיקומים, הסניפים וההסכמים קיימים, שליחת הבקשה עם הפרמטרים הנדרשים, בדיקת השדה status בתשובה ובדיקת רשימת העובדים.
מדריך מקוצר
הכינו שם משתמש וסיסמה של מנהל במערכת (לא עובד רגיל).
ודאו שהמחלקות, התפקידים, המיקומים, הסניפים וההסכמים שתשלחו כבר קיימים במערכת, בשמות זהים.
שלחו בקשה לכתובת https://412.co.il/index.php/api/createEmp עם הפרמטרים u, p, empno, fname ו-dept.
בדקו בתשובה את השדה status: true = הצליח, false = נכשל (הפירוט בשדה errors).
פתחו את רשימת העובדים ובדקו שהעובד מופיע.
1. מי יכול לעשות מה
האימות נעשה בעזרת שם משתמש וסיסמה בפרמטרים u ו-p.
סוג משתמש | האם יכול להשתמש ב-API |
מנהל חברה | כן. העובד נוצר או מתעדכן בחברה של המשתמש המאמת, ואי אפשר לבחור חברה אחרת. |
מנהל מחלקה / מנהל משמרות | כן, כל משתמש שאינו עובד רגיל מתקבל. |
עובד רגיל | לא. התשובה: no authenticated. |
2. מה צריך כדי שזה יעבוד
משתמש מנהל פעיל, ששם המשתמש והסיסמה שלו ידועים.
לעובד חדש: מחלקה אחת לפחות. שלחו dept בשם מחלקה קיים, או הגדירו בחברה מחלקת ברירת מחדל לעובדים חדשים.
כל מחלקה, תפקיד, תפקיד משמרת, מיקום, סניף, הסכם עבודה והסכם משמרות שתשלחו חייבים להיות קיימים כבר, בשם זהה לשם במערכת. ה-API לא יוצר אותם.
מספר עובד (empno) מספרי. ה-API מסיר אפסים מובילים לצורך הבדיקה.
3. כתובת ואופן שליחה
כתובת | |
שליחה | הפרמטרים נשלחים כפרמטרים רגילים של הבקשה (מומלץ POST בפורמט form). לשליחה כגוף JSON השתמשו ב"הוספת עובד JSON API". |
תשובה | JSON |
4. הפרמטרים
עמודת "חובה" מתארת מה המערכת בודקת בפועל.
פרמטר | חובה | תיאור וכללים |
u | כן | שם משתמש של מנהל. |
p | כן | סיסמת המנהל. |
empno | כן | מספר העובד. קובע אם זו יצירה או עדכון. חייב להיות מספרי ולא להתחיל ב-0. |
fname | מומלץ תמיד | שם פרטי. ראו "שאלות נפוצות" לגבי עדכון עובד קיים. |
lname | מומלץ תמיד | שם משפחה. |
dept | ליצירת עובד חדש (אלא אם הוגדרה בחברה מחלקת ברירת מחדל) | שמות מחלקות מופרדים בפסיק, למשל dept1,dept2. כל מחלקה חייבת להתקיים. בעדכון, השליחה מחליפה את כל מחלקות העובד. |
status | לא | הערכים המותרים: 1, 2 או 3. בלי הפרמטר העובד נוצר עם 1. ערך אחר גורם לשגיאה. |
לא | כתובת מייל תקינה. | |
phone | לא | בדיוק 10 ספרות, בלי מקפים ובלי רווחים. |
address | לא | אותיות בעברית ובאנגלית, ספרות, רווחים ופסיקים בלבד. |
birthday | לא | תאריך לידה בפורמט YYYY-MM-DD, תאריך שעבר. |
start_work_date | לא | תחילת העסקה, YYYY-MM-DD. |
end_work_date | לא | סיום העסקה, YYYY-MM-DD. |
store | לא | שמות סניפים מופרדים בפסיק. אם סניף אחד לא קיים, השדה כולו נכשל. |
role | לא | שמות תפקידים מופרדים בפסיק. אין לשלוח יחד עם role_code. |
role_code | לא | קודי תפקידים מופרדים בפסיק. אין לשלוח יחד עם role. |
shift_role | לא | שמות תפקידי משמרת מופרדים בפסיק. |
place | לא | שמות מקומות מותרים לדיווח, מופרדים בפסיק. |
place_code | לא | קודי מקומות מופרדים בפסיק. מצטרף למקומות שנשלחו ב-place. |
default_place | לא | שם של מקום קיים, כמקום ברירת המחדל. |
required_gps_location_to_make_record | לא | האם נדרש מיקום GPS כדי להחתים. אם לא נשלח, העובד החדש מקבל את ברירת המחדל של החברה. |
agreement | לא | שם הסכם עבודה, בדיוק כפי שהוא במערכת. בתוקף מה-1 בחודש הנוכחי. לא מוחלף אם לעובד כבר יש הסכם. |
shift_agreement | לא | שם הסכם משמרות. |
soft_block_date | לא | תאריך בפורמט YYYY-MM-DD. |
salary_number | לא | מספר העובד במערכת השכר. |
comment | לא | הערה חופשית. |
username | לא | שם משתמש לכניסת העובד למערכת ולאפליקציה. חייב להיות ייחודי בכל המערכת. חובה אם שולחים password. |
password | לא | סיסמת הכניסה של העובד (לא שם המשתמש). לפחות 8 תווים, הכוללים לפחות אות באנגלית ולפחות ספרה. חובה אם שולחים username. |
5. יצירה מול עדכון
מספר עובד שלא קיים בחברה: נוצר עובד חדש. שדות שלא נשלחו מקבלים את ברירות המחדל של החברה (סניפים, מקומות, תפקידי משמרת, GPS, NFC, תקופת שכר, מחלקות והסכם עבודה), אם הוגדרו.
מספר עובד שכבר קיים: העובד מתעדכן בשדות שנשלחו. ברירות המחדל של החברה לא מוחלות.
מחלקות: שליחת dept בעדכון מוחקת את כל המחלקות הקיימות של העובד ומציבה את הרשימה שנשלחה. שלחו תמיד את הרשימה המלאה.
הסכם עבודה: ההסכם נקבע רק לעובד שאין לו הסכם. לעובד שכבר יש לו הסכם, השינוי נעשה בכרטיס העובד.
כניסה למערכת: אם נשלחו username ו-password, נוצר לעובד משתמש כניסה מסוג עובד.
6. דוגמה לבקשה ולתשובה
בקשה ליצירת עובד (הערכים הם דוגמה בלבד; החליפו אותם בנתוני החברה שלכם):
curl -X POST "https://412.co.il/index.php/api/createEmp" \ -d "u=manager_user" -d "p=manager_password" \ -d "empno=1234" -d "fname=נועה" -d "lname=לוי" \ -d "dept=מכירות" \ -d "agreement=הסכם שעתי" -d "salary_number=88123"
תשובה מוצלחת:
{"status":true,"message":"Employee created successfully","data":{"empId":5821,"empNo":"1234"}}תשובה כשל (כל השגיאות שנמצאו מוחזרות יחד, ושום דבר לא נשמר):
{"status":false,"errors":{"dept":"Department מכירות does not exist","phone":"phone must be a 10-digit number. "}}7. הודעות שגיאה
במקרה של כישלון התשובה היא status: false ואובייקט errors עם מפתח לכל שדה שגוי.
מפתח | ההודעה | משמעות ומה לעשות |
auth | no authenticated / no authenticated. | חסרים פרטי u ו-p, שהם שגויים, או שהמשתמש אינו מנהל. בדקו שם משתמש וסיסמה ושהמשתמש פעיל ומסוג מנהל. |
empno | empno is required | לא נשלח empno. |
empno | empno must be numeric and cannot start with '0'. | המספר אינו מספרי או שהוא 0. שלחו מספר חיובי. |
dept | dept is required. | עובד חדש בלי מחלקה, ואין בחברה מחלקת ברירת מחדל. שלחו dept. |
dept | Department X does not exist | מחלקה לא קיימת. תקנו את השם או צרו אותה קודם במערכת. |
status | status must be one of the following values: 1, 2, 3. | ערך status לא מותר. |
address | Address must not contain special characters | הכתובת כוללת תווים מיוחדים (למשל גרשיים או מקף). הסירו אותם. |
Invalid email format | כתובת מייל לא תקינה. | |
phone | phone must be a 10-digit number. | הטלפון אינו 10 ספרות בדיוק. |
birthday | birthday must be a valid date in YYYY-mm-dd format / birthday must be a date in the past. | פורמט שגוי או תאריך שלא עבר. |
start_work_date / end_work_date | start_work_date must be a valid date in YYYY-mm-dd format. / end_work_date must be a valid date in YYYY-mm-dd format. | תאריך בפורמט שגוי. |
soft_block_date | soft_block_date must be a valid date in YYYY-mm-dd format. | תאריך בפורמט שגוי. |
role_code | cant send role and role code together | נשלחו role ו-role_code יחד. שלחו אחד מהם. |
role | Role X does not exist | תפקיד לא קיים. |
role_code | Role code X does not exist | קוד תפקיד לא קיים. |
shift_role | Shift role X does not exist | תפקיד משמרת לא קיים. |
place | Place X does not exist | מקום לא קיים. |
place_code | Place code X does not exist | קוד מקום לא קיים. |
default_place | default_place X does not exist | מקום ברירת המחדל לא קיים. שלחו את שם המקום. |
store | Store X does not exist | סניף לא קיים. |
agreement | Agreement X does not exist | הסכם עבודה בשם הזה לא קיים. העתיקו את השם בדיוק מ"ניהול הסכמי עבודה". |
shift_agreement | Shift agreement X does not exist | הסכם משמרות לא קיים. |
username | username is required when a password is set | נשלחה סיסמה בלי שם משתמש. |
username | username X already exists. | שם המשתמש תפוס. בחרו אחר. |
password | password is required when a username is set | נשלח שם משתמש בלי סיסמה. |
password | Password does not meet complexity requirements | הסיסמה קצרה מ-8 תווים או שחסרה בה אות באנגלית או ספרה. |
db | Database transaction failed. | שגיאת שרת. הפעולה בוטלה. נסו שוב, ואם חוזר פנו לתמיכה. |
exception | (טקסט השגיאה) | שגיאת שרת. הפעולה בוטלה. פנו לתמיכה עם הבקשה ששלחתם. |
שאלות נפוצות ופתרון בעיות
❓ שלחתי בקשה וקיבלתי "no authenticated"
לא נשלחו u ו-p בכלל. אם התשובה היא "no authenticated." (עם נקודה), הפרטים שגויים או שהמשתמש אינו מנהל או אינו פעיל.
❓ המשתמש שלי הוא עובד רגיל והבקשה נדחית
רק משתמש מנהל יכול להשתמש ב-API. השתמשו בפרטי מנהל.
❓ קיבלתי "Department X does not exist"
המחלקה לא קיימת בחברה או שהשם שונה (כולל רווחים ואותיות). ה-API לא יוצר מחלקות. צרו אותה במערכת או תקנו את השם.
❓ קיבלתי "dept is required." אבל זה עובד קיים
השגיאה חלה רק על עובד חדש. בדקו שמספר העובד שנשלח זהה למספר שבמערכת.
❓ קיבלתי "Agreement X does not exist"
שם הסכם העבודה חייב להיות זהה לשם במערכת. בדקו את השם ב"ניהול הסכמי עבודה". אפשר גם לא לשלוח את הפרמטר: אם הוגדר בחברה הסכם ברירת מחדל, עובד חדש יקבל אותו.
❓ שלחתי הסכם לעובד קיים וההסכם לא התחלף
ה-API קובע הסכם רק לעובד שאין לו הסכם. החליפו הסכם בכרטיס העובד.
❓ קיבלתי "Password does not meet complexity requirements"
הסיסמה צריכה להכיל לפחות 8 תווים, אות באנגלית וספרה. אותיות בעברית אינן נחשבות.
❓ קיבלתי "username X already exists."
שם המשתמש תפוס במערכת (בכל החברות). בחרו שם ייחודי.
❓ העדכנתי עובד קיים והשם שלו נמחק
בעדכון עובד קיים שלחו תמיד גם fname, lname ו-salary_number עם הערכים הנכונים, גם אם לא השתנו, כדי שלא יתאפסו.
❓ עדכנתי מחלקה ונעלמו המחלקות האחרות של העובד
dept מחליף את כל המחלקות. שלחו את הרשימה המלאה, מופרדת בפסיקים.
❓ הבקשה נכשלה ושום דבר לא נשמר, למרות שרק שדה אחד שגוי
כך המערכת פועלת: כל שגיאה בשדה גורמת לכישלון כל הבקשה. תקנו את כל השגיאות שברשימת errors ושלחו שוב.
❓ שלחתי מספר עובד שמתחיל ב-0
שלחו את המספר בלי אפס מוביל. מספר שמורכב מ-0 בלבד נדחה.
❓ קיבלתי "phone must be a 10-digit number."
שלחו בדיוק 10 ספרות, ללא מקפים, רווחים או קידומת בינלאומית.
❓ העובד נוצר אבל לא רואים אותו ברשימת העובדים
בדקו בתשובה ש-status הוא true ושמרו את empId. ודאו שאתם מחפשים בחברה הנכונה.
❓ אני רוצה למחוק עובד או לתקן טעות
למחיקת עובד אין פעולה ב-API הזה. תיקון נעשה בשליחת בקשה חוזרת עם אותו empno ועם הערכים הנכונים, או בכרטיס העובד במערכת.
❓ ראיתי בתיעוד הישן הודעות required_correct_dept, invalid_param ו-duplicated_id
הודעות אלה כבר אינן מוחזרות. ההודעות הנוכחיות מופיעות בטבלת "הודעות שגיאה" למעלה.
מילון מונחים
empno – מספר העובד במערכת. מזהה את העובד ליצירה או עדכון.
salary_number – מספר העובד במערכת השכר.
הסכם עבודה – ההסכם שמגדיר את חוקי חישוב השעות של העובד.
הסכם משמרות – ההסכם של העובד במודול סידור העבודה.
errors – אובייקט בתשובה שמפרט כל שדה שגוי.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
ליצור עובד | /api/createEmp עם empno חדש ו-dept | נוצר עובד, ו-empId חוזר בתשובה |
לעדכן עובד | /api/createEmp עם empno קיים | מתעדכנים השדות שנשלחו |
לתת לעובד כניסה | username ו-password | נוצר משתמש כניסה לעובד |
להחליף הסכם עבודה | כרטיס העובד | ה-API לא מחליף הסכם קיים |