לדלג לתוכן הראשי

שאלות ותשובות בנושא API

תשובות קצרות על חיבור מערכת חיצונית ל-EZTime דרך ה-API: הזדהות והודעת "no authenticated", חסימת API והודעת no_have_permission, מגבלות של 5 קריאות בשעה ו-60 ימים, ייצוא לשכר, ורשימת כל מדריכי ה-API.

נכתב על ידי EZTIME SUPPORT

תשובות קצרות לשאלות הנפוצות על חיבור מערכת חיצונית ל-EZTime דרך ה-API, עם קישור למדריך המלא של כל קריאה.

מה זה ומתי צריך את זה

ה-API מאפשר למערכת שלכם (שכר, משאבי אנוש, BI) למשוך נתוני נוכחות ולהוסיף עובדים, מחלקות, תפקידים ואתרים בלי להיכנס למסך. המאמר הזה עונה על השאלות שחוזרות: איך מזדהים, למה מתקבלת שגיאה, מה המגבלות ואיפה המדריך של כל קריאה.

מה המאמר הזה כולל

טבלת כל מדריכי ה-API, הזדהות והרשאות (כולל "no authenticated" ו-no_have_permission), מגבלות קצב וטווח תאריכים, ייצוא לשכר, הקריאה getReportEmp (דוח לפי עובד), טבלת הודעות שגיאה, שאלות ותשובות, מילון מונחים וסיכום מהיר. לכל קריאה יש מדריך משלה, והם מופיעים ב"מאמרים קשורים".

מדריך מקוצר

  1. בחרו משתמש מנהל פעיל (לא "עובד") ייעודי לחיבור.

  2. ודאו מול התמיכה שלחברה יש תוכנית שכוללת API ושאין עליה "חסימת API".

  3. שלחו ב-POST את u (שם משתמש) ו-p (סיסמה) ואת פרמטרי הקריאה.

  4. בדקו את השדה status בתשובה, לא את קוד ה-HTTP.

  5. בדוח היומי ובדוח המסכם: עד 5 קריאות בשעה ועד 60 ימים בקריאה.


כל מדריכי ה-API

הטבלה מראה מה רוצים לעשות, איזו קריאה מתאימה ואיפה המדריך המלא.

מה רוצים לעשות

הקריאה

המדריך

למשוך את דיווחי הנוכחות היומיים

api/getDaily

למשוך את הדוח המסכם לכל העובדים

api/total

למשוך את רשימת העובדים

api/getEmp

למשוך את הדיווחים של עובד אחד או של כולם (דוח לפי עובד)

api/getReportEmp

אין מדריך נפרד, ההסבר בהמשך המאמר הזה

להוסיף או לעדכן עובד (שדות טופס)

api/createEmp

להוסיף או לעדכן עובד (JSON)

api/createEmpWithJson

למשוך מחלקות, תפקידים ואתרים

api/getDepts, api/getRoles, api/getPlaces

ליצור מחלקה, תפקיד או אתר

api/createDept, api/createRole, api/createPlace

להוסיף משמרת פתוחה

api/addOpenShift

להוסיף מקום מותר לדיווח

api/add_location

להוריד קובץ החתמות לתוכנת שכר

service/exportSalary

כל הכתובות בנויות כמו https://412.co.il/index.php/api/getDaily, עם שם הקריאה בסוף. לייצוא הקובץ לשכר הכתובת היא https://412.co.il/index.php/service/exportSalary.

שאלות ותשובות

❓ יש לכם API? איפה כל התיעוד?

כן. כל הקריאות והמדריכים שלהן מופיעים בטבלה שלמעלה, וכל מדריך כולל כתובת, פרמטרים, דוגמאות, הודעות שגיאה ושאלות נפוצות.

❓ איך מקבלים מפתח API או TOKEN?

אין מפתח API נפרד לכל לקוח. הקריאות מזדהות בשם המשתמש ובסיסמה של משתמש מנהל במערכת, בפרמטרים u ו-p. רק לייצוא הקובץ לשכר יש פרמטר key, וגם הוא ערך קבוע שמופיע בAPI ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד.

❓ איזה משתמש צריך כדי לקרוא ל-API?

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

❓ אני שולח את שם המשתמש והסיסמה שאיתם אני נכנס לאתר ומקבל "no authenticated."

זו הודעת השגיאה בכשל הזדהות (לא "Invalid username or password"). המשתמש הוא כנראה מסוג "עובד" רגיל, או שהוא לא פעיל, מוקפא או שתוקפו פג, או שהסיסמה שגויה. בדקו שאפשר להיכנס לאתר עם אותם פרטים בדיוק, השתמשו במשתמש מנהל, וקודדו תווים כמו &, + או # בסיסמה. הפירוט בAPI לקבלת דוח נוכחות יומי.

❓ קיבלתי "no authenticated" בלי נקודה

השרת לא קיבל את u ואת p בכלל. שלחו אותם כשדות טופס או בכתובת, ולא בכותרות (Headers). רק בהוספת עובד JSON API הם נשלחים בתוך גוף ה-JSON.

❓ לשלוח ב-GET או ב-POST?

את u ו-p אפשר לשלוח גם ב-GET וגם ב-POST, ומומלץ POST כדי שהסיסמה לא תישמר בהיסטוריה ובלוגים של כתובות. יש יוצאים מן הכלל: הוספת מקום מותר לדיווח עובדת רק ב-POST, וייצוא הקובץ לשכר רק ב-GET.

❓ אפשר לשלוח JSON?

רק בקריאה createEmpWithJson, שמתוארת בהוספת עובד JSON API. שאר הקריאות קוראות שדות טופס (x-www-form-urlencoded) או פרמטרים בכתובת, וגוף JSON מגיע אליהן ריק.

❓ קיבלתי "no_have_permission"

הקריאה חסומה לחברה. זה קורה כשלחברה אין תוכנית (חבילה) בכלל, או כשסומנה לה "חסימת API" בהגדרות התוכנית שלה. ההודעה מתקבלת בדוח היומי (getDaily), בדוח המסכם (total), ברשימת העובדים (getEmp) ובדוח לפי עובד (getReportEmp). הפתרון: פנו לתמיכה (שירות הלקוחות) כדי להסיר את החסימה או לשייך תוכנית. החסימה היא של החברה כולה, ושינוי משתמש או סיסמה לא יעזור.

❓ מקבל no_have_permission רק בחלק מהקריאות

הבדיקה חלה על ארבע הקריאות שלמעלה. הקריאות getDepts, getRoles, getPlaces, createDept, createRole ו-createPlace לא נבדקות מול התוכנית, ולכן הן יכולות לעבוד גם כשהדוחות חסומים. אם גם ההזדהות נכשלת בהן, התשובה היא "no authenticated" ולא no_have_permission.

❓ כמה קריאות מותר לשלוח?

ל-getDaily ול-total יש מגבלה של 5 קריאות בשעה לכל חברה, לכל אחת מהן בנפרד, ומשותפת לכל המשתמשים והמערכות של החברה. הקריאה השישית נדחית עם "rate_limit_exceeded" ועם retry_after_seconds (כמה שניות לחכות) ו-limit (המגבלה, 5). לשאר הקריאות אין מגבלה בשעה.

❓ אני קורא ל-getDaily כל 10 דקות ונחסם עם "rate_limit_exceeded"

כל 10 דקות זה 6 קריאות בשעה, יותר מ-5. השעה נספרת מהקריאה הראשונה, אז קראו לכל היותר כל 15 דקות, או פעם בשעה עם טווח רחב יותר. הפירוט בAPI לקבלת דוח נוכחות יומי.

❓ מה טווח התאריכים המרבי בקריאה אחת?

ב-getDaily וב-total עד 60 ימים, כולל היום הראשון והאחרון. טווח ארוך יותר נדחה עם "date_range_exceeded" (יחד עם max_days ו-requested_days), ולתקופה ארוכה פצלו לכמה קריאות. בייצוא הקובץ לשכר ההפרש בין fd ל-ed יכול להיות עד 30 ימים, וטווח גדול יותר נדחה עם ההודעה "date range max 30 days".

❓ ב-getDaily היום האחרון של החודש חסר

ב-getDaily היום של to לא נכלל. לכל חודש שלחו ב-to את היום הראשון של החודש הבא, למשל from=2026-09-01 ו-to=2026-10-01.

❓ מנהל מחלקה שקורא ל-API יקבל רק את המחלקה שלו?

לא. הקריאות לא מצמצמות את הנתונים לפי המחלקות של המנהל, ולכן כל משתמש מנהל שמחובר ל-API יכול למשוך נתונים של כל החברה. בדוח המסכם אפשר לבקש מחלקות מסוימות בפרמטר dept.

❓ איך יודעים אם הקריאה הצליחה?

לפי השדה status בגוף התשובה (true או false, ובחלק מהקריאות 1 או 0). השרת מחזיר בדרך כלל קוד HTTP 200 גם כשהקריאה נכשלה, ולכן אל תסתמכו על קוד ה-HTTP. בדוח היומי ובדוח לפי עובד ההודעה בשדה msg, בדוח המסכם בשדה result, ובקריאות הרשימות והיצירה (מחלקות, תפקידים, אתרים) בשדה errors.

❓ איך משתמשים ב-getReportEmp (דוח לפי עובד)?

הקריאה מחזירה את דיווחי הנוכחות של העובדים, כל דיווח בשורה, ממוינים לפי תאריך ושעה. הפרמטרים: u ו-p (הזדהות), from ו-to (תאריכים, ברירת המחדל לכל אחד היא היום), ו-emp (מספר העובד, נשלח ב-POST). בלי emp, או עם מספר עובד שלא קיים בחברה, מוחזרים כל העובדים. עובד בלי דיווחים בטווח לא מופיע. אין לקריאה מגבלה של 5 בשעה או של 60 ימים, אבל היא חסומה לחברה בלי תוכנית או עם "חסימת API" (no_have_permission). המדריך המלא עוד לא נכתב.

❓ איפה מוצאים את מספר המחלקה לפרמטר dept?

בשדה DeptID שחוזר מ-getDepts, בAPI לקבלת רשימת מחלקות, תפקידים ואתרים. אפשר לקבל את המחלקות כרשימה, או כעץ ארגוני עם getDepTree=1.

❓ איך מוסיפים או מעדכנים עובד ממערכת משאבי אנוש?

בקריאה createEmp (שדות טופס) או createEmpWithJson (JSON). שתיהן יוצרות עובד חדש, או מעדכנות עובד קיים לפי מספר העובד. הפירוט בAPI להוספת עובד חדש ובהוספת עובד JSON API.

❓ אפשר למחוק עובד דרך ה-API?

לא. כדי לסיים העסקה של עובד שלחו בקריאת ה-JSON "status": 2 ותאריך סיום ב-end_work_date, כמו בדוגמה בהוספת עובד JSON API.

❓ אפשר ליצור מחלקות, תפקידים או אתרים דרך ה-API?

כן, בקריאות createDept (חובה name), createRole (חובה role_name) ו-createPlace (חובה name). הן רק יוצרות, לא עורכות ולא מוחקות, ולא בודקות אם השם כבר קיים. הפירוט בAPI ליצירת מחלקה, תפקיד ואתר.

❓ איך מוסיפים מקום מותר לדיווח (נקודה על המפה) מהמערכת שלנו?

בקריאה add_location, ב-POST כשדות טופס, עם name, radius (בקילומטרים: 300 מטר = 0.3), lat ו-lng. הפירוט במדריך API - הוספת מיקום מותר לדיווח.

❓ איך מושכים קובץ לתוכנת השכר?

בקריאה service/exportSalary, ב-GET בלבד (שליחה ב-POST לא תעבוד), עם הפרמטר הקבוע key, שם משתמש וסיסמה (u ו-p) ותאריכים fd ו-ed. הטווח עד 30 ימים. הקריאה עובדת רק לחברות שמוגדר להן סוג שכר מתאים; אחרת מתקבלת "invalid client" ופונים לתמיכה. הפירוט בAPI ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד.

❓ ייצוא השכר מחזיר "invalid client"

החברה לא מוגדרת אצלנו לפורמט הקובץ הזה (סוג השכר שלה אינו מתאים). פנו לתמיכה. זה לא קשור ל"חסימת API".

❓ איך יוצרים משמרת פתוחה ממערכת אחרת?

בקריאה addOpenShift, שיוצרת משמרת חד-פעמית או קבועה בסידור העבודה. הפירוט בAPI להוספת משמרת פתוחה.

❓ יש לנו כמה חברות במערכת. אפשר למשוך את כולן בקריאה אחת?

לא. החברה נקבעת לפי המשתמש שמזדהה, ואין פרמטר של מספר לקוח. לכל חברה השתמשו במשתמש מנהל שלה.

❓ שיניתי סיסמה למשתמש והחיבור הפסיק לעבוד

הקריאות משתמשות בסיסמה הנוכחית של המשתמש, אז עדכנו אותה גם במערכת שקוראת ל-API. משתמש ייעודי לחיבור, שהסיסמה שלו לא משתנה, חוסך את זה.

❓ איך שומרים על הסיסמה בטוחה?

קראו תמיד לכתובת עם https, שלחו את u ו-p ב-POST, ושמרו את הסיסמה רק בשרת שלכם, לא בתוכנה שרצה בדפדפן או באפליקציה ציבורית.

❓ איך בודקים קריאה לפני שמחברים מערכת?

ב-Postman או בשורת פקודה עם cURL. כל בדיקה של getDaily או total נספרת במגבלה של 5 בשעה, וקריאות שיוצרות נתונים (עובד, מחלקה, תפקיד, אתר, מקום, משמרת) יוצרות רשומה אמיתית בחברה, אז מחקו אותה במסך אחרי הבדיקה.

הודעות שגיאה

ההודעה

מה זה אומר

מה עושים

no authenticated.

שם משתמש או סיסמה שגויים, משתמש לא פעיל, או משתמש מסוג "עובד"

השתמשו במשתמש מנהל פעיל עם הפרטים שנכנסים איתם לאתר

no authenticated

u ו-p לא הגיעו לשרת

שלחו אותם כשדות טופס או בכתובת, לא בכותרות

no_have_permission

לחברה אין תוכנית, או שיש עליה "חסימת API"

פנו לתמיכה להסרת החסימה או לשיוך תוכנית

rate_limit_exceeded

יותר מ-5 קריאות בשעה לדוח היומי או למסכם

חכו retry_after_seconds שניות והפחיתו את תדירות הקריאות

date_range_exceeded

טווח של יותר מ-60 ימים

פצלו לכמה קריאות (אך כל קריאה נספרת במגבלת השעה)

invalid_date, invalid_date_range

תאריך לא תקין, או תאריך התחלה אחרי תאריך הסיום

תקנו את התאריכים

invalid dateformat.

תאריך לא תקין בדוח המסכם

בדקו את sy, sm, sd, ey, em, ed

invalid parameters / invalid user / invalid date / invalid employee

בייצוא לשכר: חסר פרמטר או key שגוי / משתמש שגוי / תאריך לא תקין / מספר עובד לא קיים

בדקו את הפרמטרים

date range max 30 days

ייצוא לשכר: טווח של יותר מ-30 ימים

בקשו טווח קצר יותר

invalid client

ייצוא לשכר: החברה לא מוגדרת לפורמט

פנו לתמיכה

מילון מונחים

  • u, p – שם המשתמש והסיסמה של משתמש מנהל, שולחים בכל קריאה.

  • חסימת API – סימון על התוכנית של החברה שחוסם את הדוחות ורשימת העובדים ב-API.

  • תוכנית – החבילה שמשויכת לחברה; בלעדיה הקריאות החסומות נדחות.

  • rate limit – מגבלת 5 קריאות בשעה לדוח יומי ולדוח מסכם.

  • retry_after_seconds – כמה שניות לחכות עד הקריאה הבאה.

  • DeptID – מספר המחלקה, חוזר מ-getDepts.

סיכום מהיר

מה רוצים לעשות

איפה

מה זה משנה

קיבלתי no_have_permission

פנייה לתמיכה

הסרת "חסימת API" או שיוך תוכנית

קיבלתי no authenticated

בדיקת המשתמש

משתמש מנהל פעיל, u ו-p בטופס או בכתובת

קיבלתי rate_limit_exceeded

תדירות הקריאות

עד 5 בשעה לכל דוח

לייצא תקופה ארוכה

פיצול קריאות

60 ימים בדוחות, 30 בייצוא לשכר


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

האם קיבלת תשובה לשאלתך?