תשובות קצרות לשאלות הנפוצות על חיבור מערכת חיצונית ל-EZTime דרך ה-API, עם קישור למדריך המלא של כל קריאה.
כל מדריכי ה-API
מה רוצים לעשות | הקריאה | המדריך |
למשוך את דיווחי הנוכחות היומיים | api/getDaily | |
למשוך את הדוח המסכם לכל העובדים | api/total | |
למשוך את רשימת העובדים | api/getEmp | |
להוסיף או לעדכן עובד (שדות טופס) | 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."
המשתמש הוא כנראה מסוג "עובד", או שהוא לא פעיל, מוקפא או שתוקפו פג, או שהסיסמה שגויה. בדקו שאפשר להיכנס לאתר עם אותם פרטים בדיוק, השתמשו במשתמש מנהל, וקודדו תווים כמו &, + או # בסיסמה. הפירוט בAPI לקבלת דוח נוכחות יומי.
❓ קיבלתי "no authenticated" בלי נקודה
השרת לא קיבל את u ואת p בכלל. שלחו אותם כשדות טופס או בכתובת, ולא בכותרות (Headers). רק בהוספת עובד JSON API הם נשלחים בתוך גוף ה-JSON.
❓ לשלוח ב-GET או ב-POST?
רוב הקריאות מקבלות את הפרמטרים בשתי הדרכים, ומומלץ POST כדי שהסיסמה לא תישמר בהיסטוריה ובלוגים של כתובות. יש יוצאים מן הכלל: הוספת מקום מותר לדיווח עובדת רק ב-POST, וייצוא הקובץ לשכר רק ב-GET.
❓ אפשר לשלוח JSON?
רק בקריאה createEmpWithJson, שמתוארת בהוספת עובד JSON API. שאר הקריאות קוראות שדות טופס (x-www-form-urlencoded) או פרמטרים בכתובת, וגוף JSON מגיע אליהן ריק.
❓ קיבלתי "no_have_permission"
הקריאה לא פתוחה בהגדרות החבילה של החברה. זה קורה בדוח היומי (getDaily), בדוח המסכם (total) וברשימת העובדים (getEmp). פנו לתמיכה כדי לבדוק את ההרשאה.
❓ כמה קריאות מותר לשלוח?
ל-getDaily ול-total יש מגבלה של 5 קריאות בשעה לכל חברה, לכל אחת מהן בנפרד, ומשותפת לכל המשתמשים והמערכות של החברה. הקריאה השישית נדחית עם "rate_limit_exceeded" ועם retry_after_seconds (כמה שניות לחכות). לשאר הקריאות אין מגבלה בשעה.
❓ אני קורא ל-getDaily כל 10 דקות ונחסם עם "rate_limit_exceeded"
כל 10 דקות זה 6 קריאות בשעה, יותר מ-5. השעה נספרת מהקריאה הראשונה, אז קראו לכל היותר כל 15 דקות, או פעם בשעה עם טווח רחב יותר. הפירוט בAPI לקבלת דוח נוכחות יומי.
❓ מה טווח התאריכים המרבי בקריאה אחת?
ב-getDaily וב-total עד 60 ימים, כולל היום הראשון והאחרון. טווח ארוך יותר נדחה עם "date_range_exceeded", ולתקופה ארוכה פצלו לכמה קריאות. בייצוא הקובץ לשכר ההפרש בין 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.
❓ איפה מוצאים את מספר המחלקה לפרמטר dept?
בשדה DeptID שחוזר מ-getDepts, בAPI לקבלת רשימת מחלקות, תפקידים ואתרים.
❓ איך מוסיפים או מעדכנים עובד ממערכת משאבי אנוש?
בקריאה createEmp (שדות טופס) או createEmpWithJson (JSON). שתיהן יוצרות עובד חדש, או מעדכנות עובד קיים לפי מספר העובד. הפירוט בAPI להוספת עובד חדש ובהוספת עובד JSON API.
❓ אפשר למחוק עובד דרך ה-API?
לא. כדי לסיים העסקה של עובד שלחו בקריאת ה-JSON "status": 2 ותאריך סיום ב-end_work_date, כמו בדוגמה בהוספת עובד JSON API.
❓ אפשר ליצור מחלקות, תפקידים או אתרים דרך ה-API?
כן, בקריאות createDept, createRole ו-createPlace. הן רק יוצרות, לא עורכות ולא מוחקות, ולא בודקות אם השם כבר קיים. הפירוט בAPI ליצירת מחלקה, תפקיד ואתר.
❓ איך מוסיפים מקום מותר לדיווח (נקודה על המפה) מהמערכת שלנו?
בקריאה add_location, ב-POST כשדות טופס, עם name, radius (בקילומטרים: 300 מטר = 0.3), lat ו-lng. הפירוט במדריך API - הוספת מיקום מותר לדיווח.
❓ איך מושכים קובץ לתוכנת השכר?
בקריאה service/exportSalary ב-GET, עם הפרמטר הקבוע key, שם משתמש וסיסמה ותאריכים. ההודעה "invalid client" אומרת שהחברה לא מוגדרת אצלנו לפורמט הזה, ואז פנו לתמיכה. הפירוט בAPI ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד.
❓ איך יוצרים משמרת פתוחה ממערכת אחרת?
בקריאה addOpenShift, שיוצרת משמרת חד-פעמית או קבועה בסידור העבודה. הפירוט בAPI להוספת משמרת פתוחה.
❓ יש לנו כמה חברות במערכת. אפשר למשוך את כולן בקריאה אחת?
לא. החברה נקבעת לפי המשתמש שמזדהה, ואין פרמטר של מספר לקוח. לכל חברה השתמשו במשתמש מנהל שלה.
❓ שיניתי סיסמה למשתמש והחיבור הפסיק לעבוד
הקריאות משתמשות בסיסמה הנוכחית של המשתמש, אז עדכנו אותה גם במערכת שקוראת ל-API. משתמש ייעודי לחיבור, שהסיסמה שלו לא משתנה, חוסך את זה.
❓ איך שומרים על הסיסמה בטוחה?
קראו תמיד לכתובת עם https, שלחו את u ו-p ב-POST, ושמרו את הסיסמה רק בשרת שלכם, לא בתוכנה שרצה בדפדפן או באפליקציה ציבורית.
❓ איך בודקים קריאה לפני שמחברים מערכת?
ב-Postman או בשורת פקודה עם cURL. כל בדיקה של getDaily או total נספרת במגבלה של 5 בשעה, וקריאות שיוצרות נתונים (עובד, מחלקה, תפקיד, אתר, מקום, משמרת) יוצרות רשומה אמיתית בחברה, אז מחקו אותה במסך אחרי הבדיקה.
מאמרים קשורים