מה זה ומתי צריך את זה
הקריאה createEmpWithJson יוצרת עובד חדש או מעדכנת עובד קיים, לפי מספר העובד (empno), בבקשת JSON אחת. אם אין בחברה עובד עם המספר הזה נוצר עובד חדש; אם יש, העובד הקיים מתעדכן רק בשדות שנשלחו. היא מתאימה כשמערכת שכר, מערכת משאבי אנוש או אתר גיוס צריכים לפתוח ולעדכן עובדים במערכת בלי הקלדה ידנית.
מה המדריך הזה כולל
המדריך כולל: מי יכול להשתמש בקריאה, כתובת הקריאה ומבנה הבקשה, כל השדות והכללים שלהם, ההבדל בין יצירה לעדכון, מבנה התשובה והודעות השגיאה, דוגמאות, מלכודות ידועות, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. אותה קריאה מתוארת באנגלית במדריך "Developer Guide: Create/Update Employee API". הוספת עובד בשליחת טופס מתוארת במדריך "API להוספת עובד חדש", ושליפת רשימת העובדים במדריך "api לקבלת רשימת עובדים".
🎬 סרטון הסבר קצר
הסרטון מראה איך מוסיפים או מעדכנים עובד בבקשת JSON אחת: הכנת שם משתמש וסיסמה של מנהל, בניית אובייקט JSON, הוספת "pending_employee": 0, שליחה ב-POST ובדיקת התשובה.
מדריך מקוצר
ודאו שיש לכם שם משתמש וסיסמה של מנהל במערכת (לא עובד רגיל).
בנו אובייקט JSON עם u, p, empno והשדות שרוצים לקבוע.
הוסיפו "pending_employee": 0, אחרת העובד יעבור לממתינים לאישור.
שלחו אותו ב-POST אל https://412.co.il/index.php/api/createEmpWithJson.
בדקו בתשובה את status, את action (insert או update) ואת skipped_fields.
1. מי יכול לעשות מה
סוג משתמש | האם יכול להשתמש בקריאה |
מנהל מערכת | כן |
מנהל מחלקה / מנהל סידור עבודה | כן. כל סוג משתמש שאינו "עובד" מתקבל |
עובד רגיל | לא. התשובה: "no authenticated." |
העובד נוצר או מתעדכן בחברה שאליה שייך המשתמש המאמת. אין אפשרות לבחור חברה אחרת.
2. כתובת הקריאה ומבנה הבקשה
פרט | ערך |
כתובת | |
שיטה | POST |
גוף הבקשה | JSON, עם הכותרת Content-Type מסוג JSON |
אימות | שם משתמש וסיסמה של מנהל, בשדות u ו-p בתוך גוף ה-JSON (לא בכותרות) |
כל הפרמטרים, כולל פרטי האימות, נשלחים באובייקט JSON אחד. השדות היחידים שחובה לשלוח הם u, p ו-empno. בקשה מינימלית:
{ "u": "manager_user", "p": "manager_password", "empno": "1234", "fname": "ישראל", "lname": "ישראלי", "pending_employee": 0}
שדות שמקבלים כמה ערכים (מחלקה, תפקיד, מיקום, סניף) מקבלים מחרוזת מופרדת בפסיקים, למשל "dept": "מכירות,שירות". הערכים נבדקים לפי השם המדויק או קוד הפריט המדויק כפי שהם מוגדרים במערכת.
3. השדות
שדה עם ערך לא תקין מדולג ומופיע בתשובה תחת skipped_fields, ושאר השדות נשמרים. רק שגיאות ב-empno, username ו-password מכשילות את כל הבקשה.
שדה | חובה | תיאור וכללים |
u | כן | שם משתמש של מנהל |
p | כן | סיסמת המנהל |
empno | כן | מספר העובד (תעודת זהות). ספרות בלבד; אפסים מובילים מוסרים (0123 נשמר כ-123). קובע אם זו יצירה או עדכון |
fname | לא | שם פרטי. אצל עובד קיים, ערך ריק לא מוחק את השם |
lname | לא | שם משפחה. אצל עובד קיים, ערך ריק לא מוחק את השם |
status | לא | 1 = פעיל, 2 = לא פעיל. עובד חדש בלי השדה = פעיל. ערך אחר מדולג |
pending_employee | לא | 1 = ממתין לאישור, 0 = עובד רגיל. ברירת המחדל בכל בקשה: 1 |
לא | כתובת תקינה שלא קיימת אצל עובד אחר בחברה | |
phone | לא | בדיוק 10 ספרות, בלי מקפים ורווחים |
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, role_code מדולג |
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 לעובד חדש |
4. יצירה מול עדכון
עובד חדש מקבל ברירות מחדל מהמסך "ערכי ברירת מחדל לעובד" (כפתור ברשימת העובדים). עובד קיים מתעדכן רק בשדות שנשלחו.
נושא | עובד חדש | עובד קיים |
שדות שלא נשלחו | מקבלים את ברירת המחדל של החברה: סידורי עבודה, מיקומים, תפקידי משמרת, מחלקות, GPS, NFC, תקופת שכר והסכם עבודה | נשארים כמו שהם |
status | פעיל, אם לא נשלח | משתנה רק אם נשלח |
pending_employee | ממתין, אם לא נשלח | ממתין, אם לא נשלח |
fname / lname ריקים | נשמרים ריקים | השם הקיים נשאר |
מחלקות | מהבקשה, אחרת ברירת המחדל של החברה | אם נשלחו, מחליפות את כל המחלקות הקיימות |
הסכם עבודה | מהבקשה או ברירת המחדל, בתוקף מ-1 בחודש הנוכחי | לא מוחלף אם כבר יש לעובד הסכם |
כניסה (username + password) | נוצר משתמש כניסה | משתמש הכניסה הקיים מתעדכן, רק כשנשלחים שני השדות |
5. מבנה התשובה
התשובה היא תמיד JSON עם status. בדקו את status בגוף התשובה, לא רק את קוד ה-HTTP.
הצלחה
{ "status": true, "action": "insert", "message": "Employee created successfully", "data": { "empId": 5821, "empNo": "1234", "updated_fields": ["fname", "lname", "status", "pending_employee", "dept"], "skipped_fields": { "email": "Invalid email format" } }}
שדה | משמעות |
action | insert = עובד חדש נוצר, update = עובד קיים עודכן |
message | "Employee created successfully" או "Employee updated successfully" |
data.empId | המזהה הפנימי של העובד במערכת |
data.empNo | מספר העובד כפי שנשמר |
data.updated_fields | השדות שנשמרו, כולל שדות שקיבלו ברירת מחדל |
data.skipped_fields | שדות שלא נשמרו והסיבה. הבקשה עדיין הצליחה |
כישלון
שום דבר לא נשמר.
{ "status": false, "errors": { "empno": "empno is required" } }
6. דוגמאות
יצירת עובד פעיל עם כניסה לאפליקציה
{ "u": "manager_user", "p": "manager_password", "empno": "1234", "fname": "דנה", "lname": "כהן", "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": "Initial2026"}
עדכון עובד קיים: סיום עבודה
{ "u": "manager_user", "p": "manager_password", "empno": "1234", "end_work_date": "2026-12-31", "status": 2, "pending_employee": 0}
שליחה ב-curl (גרסה 7.82 ומעלה, האפשרות --json שולחת POST עם כותרת JSON)
curl --json '{"u":"manager_user","p":"manager_password","empno":"1234","fname":"דנה","pending_employee":0}' "https://412.co.il/index.php/api/createEmpWithJson"
7. מלכודות ידועות
סטטוס ממתין כברירת מחדל: כל בקשה שלא שולחת pending_employee מעבירה את העובד לממתינים לאישור, גם עובד קיים שכבר אושר. שלחו "pending_employee": 0 בכל בקשה, אלא אם העובד אמור להמתין לאישור.
הסכם עבודה לעובד קיים: אם לעובד כבר יש הסכם עבודה, הקריאה לא מחליפה אותו, אף ש-agreement מופיע ב-updated_fields. החלפת הסכם נעשית בכרטיס העובד במערכת.
תאריך תחילת ההסכם: אין שדה לתאריך. הסכם שנקבע דרך הקריאה בתוקף מ-1 בחודש שבו נשלחה הבקשה.
רשימות מוחלפות, לא מתווספות: שליחת dept או dept_code מוחקת את כל המחלקות הקיימות של העובד. כך גם בתפקידים, מיקומים וסידורי עבודה. שלחו תמיד את הרשימה המלאה.
ערך אחד שגוי מבטל את כל השדה: ב-role, role_code, shift_role ו-store, אם שם אחד ברשימה לא קיים, כל השדה מדולג. ב-dept ו-place רק הערך השגוי מדולג והשאר נשמרים.
מספר עובד כפול: אם בחברה יש שני עובדים עם אותו empno, הבקשה נכשלת. תקנו קודם את הכפילות במערכת.
הודעות שגיאה
מפתחות ב-errors (הבקשה נכשלה ושום דבר לא נשמר):
מפתח | ההודעה | מה עושים |
auth | "no authenticated" (לא נשלחו u ו-p) או "no authenticated." (פרטים שגויים, או משתמש שאינו מנהל) | בדקו את u ו-p בגוף ה-JSON, והשתמשו במשתמש מנהל |
auth / json | "Invalid JSON data: …" | גוף הבקשה אינו JSON תקין. בדקו מרכאות, פסיקים וקידוד UTF-8 |
empno | "empno is required" | הוסיפו את empno |
empno | "empno must be numeric and cannot start with '0'." | שלחו ספרות בלבד |
empno | "EmpNo is duplicated" | בחברה יש שני עובדים עם המספר. תקנו את הכפילות במערכת |
username | "username … already exists." | שם המשתמש תפוס. בחרו שם אחר |
username | "username is required when a password is set" | שלחו username יחד עם password |
password | "password is required when a username is set for a new employee" | לעובד חדש שלחו גם password |
db / exception | שגיאת שרת | הפעולה בוטלה במלואה. נסו שוב, ואם חוזר פנו לתמיכה |
הודעות ב-skipped_fields (הבקשה הצליחה, השדה לא נשמר):
שדה | ההודעה |
dept / dept_code | "Department … does not exist" |
role / role_code | "Role … does not exist" / "Role code … does not exist" / "cant send role and role code together" |
shift_role | "Shift role … does not exist" |
place / place_code / default_place | "Place … does not exist" / "Place code … does not exist" / "default_place … does not exist" |
store | "Store … does not exist" |
expense_code | "Expense code … does not exist" |
agreement / shift_agreement | "Agreement … does not exist" / "Shift agreement … does not exist" |
"Invalid email format" / "Email is duplicated" | |
phone | "phone must be a 10-digit number." |
address | "Address must not contain special characters" |
birthday | "birthday must be a valid date in YYYY-mm-dd format" / "birthday must be a date in the past." |
status | "status must be 1 (active) or 2 (inactive)." |
start_work_date / end_work_date / soft_block_date | "… must be a valid date in YYYY-mm-dd format." |
שאלות נפוצות ופתרון בעיות
❓ שלחתי בקשה וקיבלתי "no authenticated."
שם המשתמש או הסיסמה שגויים, או שהמשתמש הוא עובד רגיל. ודאו ש-u ו-p נמצאים בתוך גוף ה-JSON ולא בכותרות, והשתמשו במשתמש מנהל.
❓ העובד נוצר אבל מופיע בממתינים לאישור
לא נשלח "pending_employee": 0. ברירת המחדל היא ממתין. שלחו את הבקשה שוב עם הערך 0, או אשרו את העובד במערכת.
❓ עדכנתי עובד מאושר והוא חזר לממתינים
אותה סיבה: כל בקשה בלי pending_employee מחזירה את העובד לממתינים. הוסיפו "pending_employee": 0 לכל בקשת עדכון.
❓ הבקשה הצליחה, אבל שדה מסוים לא נשמר
חפשו את השדה ב-skipped_fields בתשובה. שם כתובה הסיבה, למשל מחלקה שלא קיימת או טלפון שאינו 10 ספרות.
❓ שלחתי מחלקה חדשה והעובד איבד את המחלקות הקודמות
dept מחליף את כל המחלקות. שלחו את הרשימה המלאה, מופרדת בפסיקים.
❓ שלחתי הסכם עבודה חדש לעובד קיים והוא לא השתנה
הקריאה לא מחליפה הסכם קיים. החליפו את ההסכם בכרטיס העובד במערכת.
❓ ההסכם שנקבע מתחיל ב-1 בחודש ולא בתאריך תחילת העבודה
כך זה עובד: הסכם שנקבע דרך הקריאה בתוקף מ-1 בחודש שבו נשלחה הבקשה. אם צריך תאריך אחר, שנו אותו בכרטיס העובד.
❓ קיבלתי "default_place … does not exist" למרות שהמיקום קיים
ב-default_place שולחים את קוד המיקום, לא את השם.
❓ שלחתי תפקיד אחד שגוי ברשימה וכל התפקידים לא נשמרו
ב-role, role_code, shift_role ו-store ערך אחד שגוי מבטל את כל השדה. תקנו את השם או את קוד הפריט ושלחו שוב.
❓ קיבלתי "username … already exists."
שם המשתמש תפוס על ידי עובד אחר, גם בחברה אחרת: שמות משתמש ייחודיים בכל המערכת. בחרו שם אחר.
❓ מספר העובד נשמר בלי האפס בהתחלה
אפסים מובילים ב-empno מוסרים. 0123 נשמר כ-123, וכל בקשה עם 0123 תעדכן את העובד 123.
❓ קיבלתי "Invalid JSON data"
גוף הבקשה אינו JSON תקין: בדקו מרכאות כפולות, פסיקים מיותרים בסוף ושהטקסט נשלח ב-UTF-8.
❓ איך מוחקים עובד דרך הקריאה?
הקריאה לא מוחקת עובדים. כדי להפסיק עובד שלחו "status": 2 ו-end_work_date.
❓ איך יודעים אם נוצר עובד חדש או עודכן קיים?
לפי action בתשובה: insert לעובד חדש, update לעובד קיים.
מילון מונחים
API - כתובת שמערכת חיצונית קוראת לה כדי לבצע פעולה במערכת.
JSON - פורמט טקסט של שדות וערכים שמערכות קוראות בקלות.
empno - מספר העובד (תעודת זהות), שלפיו הקריאה מחליטה אם ליצור או לעדכן.
ממתין לאישור - עובד שנוצר ועדיין לא אושר במערכת.
skipped_fields - שדות שלא נשמרו, עם הסיבה.
updated_fields - שדות שנשמרו.
ערכי ברירת מחדל לעובד - ההגדרות שעובד חדש מקבל כשהשדה לא נשלח.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
ליצור עובד | POST עם empno חדש | עובד חדש עם ברירות המחדל של החברה |
לעדכן עובד | POST עם empno קיים | רק השדות שנשלחו משתנים |
לא להעביר לממתינים | "pending_employee": 0 | העובד נשאר מאושר |
לסיים עבודה | "status": 2 ו-end_work_date | העובד לא פעיל |
לתת כניסה לאפליקציה | username ו-password | נוצר או מתעדכן משתמש כניסה |
מאמרים קשורים
Developer Guide: Create/Update Employee API
API להוספת עובד חדש
api לקבלת רשימת עובדים
שאלות ותשובות בנושא API