הוספת עובד JSON API | EZTIME מרכז עזרה

סקירה כללית

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

פרט	ערך
כתובת	`https://<הדומיין שלכם>/api/createEmpWithJson`
מתודה	`POST`
גוף הבקשה	JSON (`Content-Type: application/json`)
אימות	שם משתמש וסיסמה של מנהל, בשדות `u` ו-`p` בתוך גוף ה-JSON

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

מבנה הבקשה

כל הפרמטרים, כולל פרטי האימות, נשלחים באובייקט JSON אחד בגוף הבקשה. השדות היחידים שחובה לשלוח הם u, p ו-empno. שדה שלא נשלח לא משתנה אצל עובד קיים (חריג אחד: pending_employee, ראו בהערות).

בקשה מינימלית:

{   "u": "manager_user",   "p": "manager_password",   "empno": "1234",   "fname": "ישראל",   "lname": "ישראלי" }

שדות שמקבלים כמה ערכים (מחלקה, תפקיד, מיקום וכו') מקבלים מחרוזת עם פסיקים, למשל "dept": "מכירות,שירות". הערכים נבדקים לפי שם או קוד מדויק כפי שהם מוגדרים במערכת.

שדות

שדה עם ערך לא תקין מדולג ומופיע בתשובה תחת skipped_fields, ושאר השדות נשמרים. רק שגיאות ב-empno, username ו-password מכשילות את כל הבקשה.

שדה	חובה	תיאור וכללים
`u`	כן	שם משתמש של מנהל
`p`	כן	סיסמת המנהל
`empno`	כן	מספר עובד. מספרים בלבד; אפסים מובילים מוסרים (`0123` נשמר כ-`123`). קובע אם זו יצירה או עדכון
`fname`	לא	שם פרטי. ערך ריק לא מוחק שם קיים
`lname`	לא	שם משפחה. ערך ריק לא מוחק שם קיים
`status`	לא	`1` = פעיל, `2` = לא פעיל. עובד חדש בלי השדה = פעיל
`pending_employee`	לא	`1` = ממתין לאישור, `0` = עובד רגיל. ברירת מחדל: `1`
`email`	לא	כתובת תקינה, שלא קיימת אצל עובד אחר בחברה
`phone`	לא	בדיוק 10 ספרות, ללא מקפים (`0501234567`)
`address`	לא	עברית, אנגלית, ספרות, רווחים ופסיקים בלבד
`birthday`	לא	`YYYY-MM-DD`, תאריך שכבר עבר
`start_work_date`	לא	`YYYY-MM-DD`. מתעדכן בתקופת העסקה האחרונה של העובד
`end_work_date`	לא	`YYYY-MM-DD`. מתעדכן בתקופת העסקה האחרונה של העובד
`dept`	לא	שמות מחלקות, מופרדים בפסיק. מחליף את כל המחלקות הקיימות
`dept_code`	לא	קודי מחלקות. מצטרף ל-`dept` אם נשלחו שניהם
`role`	לא	שמות תפקידים. לא יחד עם `role_code`
`role_code`	לא	קודי תפקידים. נשלח יחד עם `role` = מדולג
`shift_role`	לא	שמות תפקידי משמרת
`place`	לא	שמות מיקומים
`place_code`	לא	קודי מיקומים. מצטרף ל-`place`
`default_place`	לא	קוד של מיקום ברירת המחדל (לא שם)
`required_gps_location_to_make_record`	לא	`1` = חובה מיקום GPS כדי להחתים, `0` = לא
`store`	לא	שמות סניפים
`expense_code`	לא	קודי סוגי הוצאות (`030` ו-`30` נחשבים אותו קוד). מפעיל הוצאות לעובד
`agreement`	לא	שם הסכם עבודה. ראו מגבלות בהערות
`shift_agreement`	לא	שם הסכם משמרות
`soft_block_date`	לא	`YYYY-MM-DD`
`salary_number`	לא	מספר עובד במערכת השכר
`comment`	לא	הערה חופשית
`username`	לא	שם משתמש לכניסת העובד. חייב להיות ייחודי בכל המערכת
`password`	לא	סיסמת כניסה. חובה עם `username` לעובד חדש

יצירה מול עדכון

עובד חדש מקבל ברירות מחדל מהגדרות החברה. עובד קיים מתעדכן רק בשדות שנשלחו.

נושא	עובד חדש	עובד קיים
שדות שלא נשלחו	מקבלים את ברירת המחדל של החברה: סניפים, מיקומים, תפקידי משמרת, מחלקות, GPS, NFC, תקופת שכר והסכם עבודה	נשארים כמו שהם
`status`	פעיל, אם לא נשלח	משתנה רק אם נשלח
`pending_employee`	ממתין, אם לא נשלח	ממתין, אם לא נשלח (ראו בהערות)
`fname` / `lname` ריקים	נשמרים ריקים	מתעלמים, השם הקיים נשאר
מחלקות	מהבקשה, אחרת ברירת המחדל של החברה	אם נשלחו, מחליפות את כל המחלקות הקיימות
הסכם עבודה	מהבקשה או ברירת המחדל, בתוקף מ-1 בחודש הנוכחי	לא מוחלף אם כבר קיים הסכם (ראו בהערות)
כניסה (`username` + `password`)	נוצר משתמש כניסה	משתמש הכניסה הקיים מתעדכן. משתנה רק כשנשלחים שני השדות

מבנה התשובה

התשובה היא תמיד JSON עם status. בדקו את status בגוף התשובה ולא רק את קוד ה-HTTP.

הצלחה:

{   "status": true,   "action": "insert",   "message": "Employee created successfully",   "data": {     "empId": 5821,     "empNo": "1234",     "updated_fields": ["fname", "lname", "phone", "status", "pending_employee", "dept"],     "skipped_fields": {       "email": "Invalid email format"     }   } }

שדה	משמעות
`action`	`insert` = עובד חדש נוצר, `update` = עובד קיים עודכן
`data.empId`	מזהה העובד הפנימי במערכת
`data.updated_fields`	שמות השדות שנשמרו. כולל גם שדות שקיבלו ברירת מחדל
`data.skipped_fields`	שדות שלא נשמרו והסיבה. הבקשה עדיין הצליחה

כישלון: שום דבר לא נשמר.

{   "status": false,   "errors": {     "empno": "empno is required"   } }

מפתח ב-`errors`	מתי
`auth`	פרטי מנהל שגויים, חסרים, או משתמש שאינו מנהל
`json`	גוף הבקשה אינו JSON תקין
`empno`	חסר, לא מספרי, או מופיע בחברה יותר מפעם אחת
`username`	תפוס על ידי עובד אחר, או חסר כשנשלחה סיסמה
`password`	חסרה כשנשלח `username` לעובד חדש
`db` / `exception`	שגיאת שרת. הפעולה בוטלה במלואה

דוגמאות

יצירת עובד פעיל עם כניסה לאפליקציה:

{   "u": "manager_user",   "p": "manager_password",   "empno": "1234",   "fname": "דנה",   "lname": "כהן",   "phone": "0501234567",   "email": "[email protected]",   "start_work_date": "2026-10-01",   "dept": "מכירות",   "role_code": "10",   "place_code": "TLV01",   "default_place": "TLV01",   "agreement": "הסכם שעתי",   "salary_number": "88123",   "status": 1,   "pending_employee": 0,   "username": "dana.cohen",   "password": "Initial#2026" }

עדכון עובד קיים – סיום עבודה:

{   "u": "manager_user",   "p": "manager_password",   "empno": "1234",   "end_work_date": "2026-12-31",   "status": 2,   "pending_employee": 0 }

דוגמה ב-curl:

curl -X POST "https://<הדומיין שלכם>/api/createEmpWithJson" \   -H "Content-Type: application/json" \   -d '{"u":"manager_user","p":"manager_password","empno":"1234","phone":"0501234567","pending_employee":0}'

הערות ומגבלות ידועות

סטטוס המתנה ברירת מחדל: כל בקשה שלא שולחת pending_employee שמה את העובד בממתינים, גם עובד קיים שכבר אושר. שלחו "pending_employee": 0 בכל בקשה, אלא אם העובד אמור להמתין לאישור.
הסכם עבודה לעובד קיים: אם לעובד כבר יש הסכם עבודה, ה-API לא מחליף אותו, אף ש-agreement מופיע ב-updated_fields. החלפת הסכם נעשית כרגע דרך מסך העובד במערכת.
תאריך תחילת הסכם: אין שדה לתאריך. הסכם שנקבע דרך ה-API בתוקף מ-1 בחודש שבו נשלחה הבקשה.
מחלקות מוחלפות, לא מתווספות: שליחת dept או dept_code מוחקת את כל המחלקות הקיימות של העובד. שלחו תמיד את הרשימה המלאה. כך גם בתפקידים, מיקומים וסניפים.
ערך אחד שגוי מבטל את כל השדה: ב-role, role_code, shift_role ו-store, אם שם אחד ברשימה לא קיים, כל השדה מדולג. ב-dept ו-place רק הערך השגוי מדולג והשאר נשמרים.
מספר עובד כפול: אם בחברה יש שני עובדים עם אותו empno, הבקשה נכשלת. יש לתקן את הכפילות במערכת קודם.

מאמרים קשורים