מה זה ומתי צריך את זה
הקריאה getDaily מחזירה את דיווחי הנוכחות היומיים של כל העובדים בחברה לטווח תאריכים, בפורמט JSON: שורה לכל דיווח, עם שעת כניסה ויציאה, סוג הדיווח, מחלקה, הערות ומשמרות. היא מתאימה כשרוצים למשוך את הדיווחים היומיים למערכת חיצונית, כמו מערכת שכר או מערכת דוחות פנימית, בלי להוריד את הדוח היומי ידנית.
מה המדריך הזה כולל
המדריך כולל: מה צריך כדי שהקריאה תעבוד, כתובת הקריאה והפרמטרים, איך הטווח נקבע, המגבלות (מספר קריאות בשעה וטווח תאריכים מרבי), מבנה התשובה וכל השדות בה, דוגמאות לבקשה ולתשובה, הודעות שגיאה, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. קריאות נוספות מתוארות במדריכים "API ליצוא הנתונים של הדוח המסכם לכל העובדים", "api לקבלת רשימת עובדים" ו"API ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד".
🎬 סרטון הסבר קצר
הסרטון מראה איך מושכים דוח נוכחות יומי: הכנת שם משתמש וסיסמה של מנהל, בניית כתובת הקריאה, הוספת טווח התאריכים, שליחת הקריאה וקריאת הדיווחים מהתשובה.
מדריך מקוצר
ודאו שיש לכם שם משתמש וסיסמה של מנהל במערכת (לא עובד רגיל) ושהקריאה פתוחה לחברה שלכם.
בנו כתובת בצורה https://412.co.il/index.php/api/getDaily?u=שם_משתמש&p=סיסמה.
הוסיפו את הטווח: from ו-to בפורמט YYYY-MM-DD, עד 60 ימים.
שלחו את הקריאה (GET או POST).
אם status בתשובה הוא true, הדיווחים נמצאים במערך msg.
1. מה צריך כדי שזה יעבוד
משתמש מנהל: הקריאה מזדהה בשם המשתמש והסיסמה שבהם נכנסים למערכת. משתמש מסוג "עובד" נדחה עם ההודעה "no authenticated.". כל סוג משתמש אחר (מנהל מערכת, מנהל מחלקה, מנהל סידור עבודה) מתקבל.
הקריאה פתוחה לחברה: השימוש בקריאה תלוי בהגדרות החבילה של החברה. אם מתקבלת ההודעה "no_have_permission", פנו לתמיכה כדי לבדוק את ההרשאה.
טווח תאריכים: חובה לשלוח from ו-to. בלי אחד מהם מתקבלת ההודעה "invalid_date".
2. כתובת הקריאה והפרמטרים
הפרמטרים נשלחים בכתובת (GET) או כשדות טופס (POST). השיטה לא משנה את התוצאה. ב-POST הסיסמה לא נשמרת בהיסטוריית הדפדפן ובלוגים של כתובות, ולכן היא עדיפה במערכות קבועות.
פרמטר | תיאור | סוג | דוגמה |
u | שם המשתמש במערכת | מחרוזת | test |
p | הסיסמה | מחרוזת | 123456 |
from | תאריך ההתחלה (כולל) | מחרוזת, YYYY-MM-DD | 2023-07-01 |
to | תאריך הסיום (לא כולל, ראו למטה) | מחרוזת, YYYY-MM-DD | 2023-08-01 |
איך הטווח נקבע
התשובה כוללת דיווחים שתאריכם מ-from ועד היום שלפני to. היום של to עצמו לא נכלל. כדי לקבל את כל חודש יולי 2023 שלחו from=2023-07-01 ו-to=2023-08-01.
הטווח המרבי הוא 60 ימים, כשסופרים גם את יום ההתחלה וגם את יום הסיום. from=2023-07-01 ו-to=2023-08-01 הם 32 ימים ולכן מותרים. טווח ארוך יותר נדחה עם "date_range_exceeded". לתקופה ארוכה פצלו לכמה קריאות.
אם from מאוחר מ-to מתקבלת ההודעה "invalid_date_range".
3. מגבלת קריאות
אפשר לשלוח עד 5 קריאות getDaily בשעה לכל חברה. השעה נספרת מהקריאה הראשונה בחלון. קריאה שישית באותה שעה נדחית עם "rate_limit_exceeded", והתשובה כוללת את limit (המגבלה) ואת retry_after_seconds (בעוד כמה שניות אפשר לנסות שוב). המגבלה משותפת לכל המשתמשים של אותה חברה.
4. מבנה התשובה
התשובה היא JSON עם שני שדות עיקריים:
שדה | תיאור | סוג |
status | האם הקריאה הצליחה | true / false |
msg | בהצלחה: מערך הדיווחים. בכישלון: קוד השגיאה | מערך של אובייקטים, או מחרוזת |
בשגיאות של מגבלה וטווח מופיעים שדות נוספים: limit ו-retry_after_seconds (מגבלת קריאות), או max_days ו-requested_days (טווח תאריכים).
השדות של כל דיווח במערך msg
שדה | תיאור | סוג |
HourRecordID | מזהה הדיווח | מספר |
EmpID | מזהה העובד במערכת | מספר |
empUId | מזהה ייחודי של העובד | מחרוזת |
EmpNo | תעודת הזהות של העובד | מחרוזת |
EmpFirstName | שם פרטי | מחרוזת |
EmpLastName | שם משפחה | מחרוזת |
DeptName | שם המחלקה | מחרוזת |
pict | תמונת העובד | מחרוזת |
date | תאריך הדיווח בפורמט תצוגה | מחרוזת, DD/MM/YYYY |
greg | תאריך הדיווח | מחרוזת, YYYY-MM-DD |
hfrom | שעת כניסה | מחרוזת, HH:MM |
hto | שעת יציאה | מחרוזת, HH:MM |
HourType | סוג הדיווח (טבלה למטה) | מספר |
custom_day | שם הדיווח המיוחד, כש-HourType הוא 7 | מחרוזת |
record_value | ערך הדיווח | מספר |
role_name | שם התפקיד | מחרוזת |
Note | הערה על הדיווח | מחרוזת |
editedRecord | האם הדיווח נערך | מספר |
attach | קובץ מצורף לדיווח | מחרוזת או null |
Flat / Flng | קו רוחב / קו אורך בכניסה | מחרוזת |
Tolat / Tolng | קו רוחב / קו אורך ביציאה | מחרוזת |
txtgps1 / txtgps2 | נתוני מיקום (GPS) נוספים בכניסה / ביציאה | מחרוזת או null |
Device_from / Device_to | המכשיר שממנו דווחו הכניסה / היציאה | מחרוזת או null |
covid_status | מצב קורונה | מחרוזת |
shifts | המשמרות של העובד באותו יום | מערך של אובייקטים |
ערכי HourType
ערך | סוג הדיווח |
0 | דיווח עבודה |
1 | חצי יום מחלה |
2 | חצי יום חופש |
3 | חצי יום מילואים |
4 | מילואים |
5 | חופשה |
6 | מחלה |
7 | מיוחד/אחר (השם ב-custom_day) |
5. דוגמאות
בקשה
GET https://412.co.il/index.php/api/getDaily?u=test&p=123456&from=2023-07-01&to=2023-08-01
תשובה בהצלחה
{ "status": true, "msg": [ { "Note": "", "role_name": "", "editedRecord": 1, "attach": null, "date": "02/07/2023", "greg": "2023-07-02", "HourType": 0, "HourRecordID": 2436, "txtgps1": null, "txtgps2": null, "custom_day": "", "Flng": ".0000000000", "Flat": ".0000000000", "Tolng": ".0000000000", "Tolat": ".0000000000", "Device_from": null, "Device_to": null, "EmpID": 1729, "DeptName": "כללי", "empUId": "EBA40BE2-03FC-4790-AEFA-36F3A9B6C3D1", "EmpFirstName": "ישראל", "EmpLastName": "ישראלי", "pict": "", "EmpNo": "1234", "hfrom": "08:00", "covid_status": "", "hto": "16:00", "record_value": 8, "shifts": [] } ]}
תשובה בכישלון
{ "status": false, "msg": "no authenticated." }
{ "status": false, "msg": "date_range_exceeded", "max_days": 60, "requested_days": 92 }
{ "status": false, "msg": "rate_limit_exceeded", "limit": 5, "retry_after_seconds": 1800 }
הודעות שגיאה
msg | מה זה אומר | מה עושים |
no authenticated | לא נשלחו u ו-p | הוסיפו את שם המשתמש והסיסמה לקריאה |
no authenticated. | שם משתמש או סיסמה שגויים, או שהמשתמש הוא מסוג "עובד" | בדקו את הפרטים, והשתמשו במשתמש מנהל |
no_have_permission | הקריאה לא פתוחה לחברה | פנו לתמיכה |
rate_limit_exceeded | נשלחו כבר 5 קריאות בשעה האחרונה | חכו את מספר השניות שב-retry_after_seconds |
invalid_date | from או to חסר או לא תאריך תקין | שלחו את שניהם בפורמט YYYY-MM-DD |
invalid_date_range | from מאוחר מ-to | החליפו ביניהם |
date_range_exceeded | הטווח ארוך מ-60 ימים | פצלו לכמה קריאות |
invalid_param | המשתמש לא משויך לחברה | השתמשו במשתמש של החברה, או פנו לתמיכה |
שאלות נפוצות ופתרון בעיות
❓ שלחתי קריאה ואני מקבל "no authenticated."
שם המשתמש או הסיסמה שגויים, או שהמשתמש הוא עובד רגיל. נסו להיכנס עם אותם פרטים למערכת, והשתמשו במשתמש מנהל.
❓ אני מקבל "no_have_permission"
הקריאה תלויה בהגדרות החבילה של החברה. פנו לתמיכה כדי לפתוח אותה.
❓ הקריאה עבדה ופתאום נחסמה עם "rate_limit_exceeded"
עברתם את 5 הקריאות בשעה. המגבלה משותפת לכל המשתמשים של החברה, כך שגם מערכת אחרת שקוראת באותו זמן נספרת. חכו את הזמן שב-retry_after_seconds, והגדירו את המערכת שלכם לקרוא בתדירות נמוכה יותר.
❓ אני צריך שנה שלמה, והקריאה נדחית עם "date_range_exceeded"
הטווח המרבי הוא 60 ימים. שלחו קריאה לכל חודש, ושימו לב למגבלה של 5 קריאות בשעה.
❓ ביקשתי עד סוף החודש והיום האחרון חסר
היום של to לא נכלל בתשובה. שלחו ב-to את היום הראשון של החודש הבא, למשל from=2023-07-01 ו-to=2023-08-01 לכל יולי.
❓ קיבלתי "invalid_date"
אחד התאריכים חסר או לא בפורמט תקין. שלחו את from ואת to, שניהם בפורמט YYYY-MM-DD.
❓ קיבלתי "invalid_date_range"
תאריך ההתחלה מאוחר מתאריך הסיום. החליפו ביניהם.
❓ קיבלתי מערך ריק ב-msg
אין דיווחים בטווח שביקשתם. בדקו שהטווח נכון, וזכרו שהיום של to לא נכלל.
❓ עובד מסוים לא מופיע בתשובה
הקריאה מחזירה רק עובדים פעילים שלא נמחקו, ורק ימים שיש בהם דיווח. בדקו שהעובד פעיל ושיש לו דיווח בטווח.
❓ איך יודעים אם הדיווח הוא חופשה או מחלה?
לפי השדה HourType: 5 חופשה, 6 מחלה, 1 ו-2 חצאי ימים, 7 מיוחד/אחר עם השם ב-custom_day. הטבלה המלאה נמצאת למעלה.
❓ אפשר לשלוח את הקריאה בשיטת POST?
כן. אותם פרמטרים נשלחים כשדות טופס, והתשובה זהה.
❓ אפשר לקבל נתונים של מחלקה אחת או עובד אחד בלבד?
לא בקריאה הזו: היא מחזירה את כל העובדים. סננו את התשובה לפי DeptName או EmpNo במערכת שלכם.
❓ מה ההבדל בין התשובה לבין הדוח היומי במסך?
הקריאה מחזירה את הדיווחים עצמם, שורה לכל דיווח, בלי הסינונים והחישובים שאפשר לבחור במסך. לסיכום שעות לכל עובד השתמשו ב"API ליצוא הנתונים של הדוח המסכם לכל העובדים".
❓ איך בודקים את הקריאה לפני שמחברים מערכת?
הדביקו את כתובת הדוגמה עם הפרטים שלכם בדפדפן, או השתמשו בכלי כמו Postman. כל בדיקה נספרת במגבלה של 5 קריאות בשעה.
מילון מונחים
API - כתובת שמערכת חיצונית קוראת לה כדי לקבל נתונים.
JSON - פורמט תשובה שמערכות קוראות בקלות.
status - האם הקריאה הצליחה.
msg - הדיווחים, או קוד השגיאה.
HourType - סוג הדיווח: עבודה, חופשה, מחלה, מילואים או מיוחד.
חלון שעה - שעה מהקריאה הראשונה, שבה נספרות עד 5 קריאות.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
למשוך דיווחים יומיים | api/getDaily עם u, p, from, to | מחזיר את כל הדיווחים בטווח |
לקבל חודש שלם | from = 1 בחודש, to = 1 בחודש הבא | היום של to לא נכלל |
לקבל תקופה ארוכה | כמה קריאות של עד 60 ימים | עד 5 קריאות בשעה לחברה |
לזהות סוג דיווח | השדה HourType | 0 עבודה, 5 חופשה, 6 מחלה ועוד |
מאמרים קשורים
API ליצוא הנתונים של הדוח המסכם לכל העובדים
api לקבלת רשימת עובדים
API ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד
שאלות ותשובות בנושא API