מה זה ומתי צריך את זה
הקריאה הזו מחזירה את נתוני הדוח המסכם של כל העובדים בחברה (או של מחלקות מסוימות) לטווח תאריכים, בפורמט JSON. היא מתאימה כשרוצים למשוך את הסיכומים החודשיים למערכת חיצונית, כמו מערכת שכר או מערכת דוחות פנימית, בלי להוריד את הדוח ידנית.
מה המדריך הזה כולל
המדריך כולל: מי יכול להשתמש בקריאה ומה צריך כדי שתעבוד, כתובת הקריאה והפרמטרים, ברירות המחדל של התאריכים, המגבלות (מספר קריאות בשעה וטווח תאריכים מרבי), מבנה התשובה, דוגמאות, הודעות שגיאה, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. הדוח המסכם עצמו במסך המערכת מוסבר במדריך "הפקת דוח חודשי מרוכז". קריאות נוספות מתוארות במדריכים "API לקבלת דוח נוכחות יומי", "api לקבלת רשימת עובדים" ו"API ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד".
מדריך מקוצר
ודאו שיש לכם שם משתמש וסיסמה של מנהל מערכת או מנהל מחלקה (לא עובד רגיל) ושהקריאה מופעלת לחברה שלכם.
בנו כתובת בצורה https://412.co.il/index.php/api/total?u=שם_משתמש&p=סיסמה.
הוסיפו את הטווח: שנת התחלה sy וחודש התחלה sm. בלי יום סיום מקבלים את כל החודש.
אם צריך מחלקות מסוימות, הוסיפו dept עם מזהי המחלקות מופרדים בפסיק.
שלחו את הקריאה (GET). אם status בתשובה הוא 1, הנתונים נמצאים ב-result.
1. מי יכול לעשות מה
הקריאה מזדהה בשם משתמש וסיסמה, לא דרך מסך במערכת.
סוג משתמש | האם יכול להשתמש בקריאה |
מנהל חברה (מנהל מערכת) | כן |
מנהל מחלקה | כן. סוג המשתמש מספיק כדי להזדהות; הנתונים נקבעים לפי הפרמטר dept שנשלח בקריאה |
מנהל סידור עבודה | כן, כל עוד הוא לא מסוג "עובד" (המערכת מאשרת כל סוג משתמש שאינו עובד) |
עובד רגיל | לא. התשובה: no authenticated. |
2. מה צריך כדי שזה יעבוד
משתמש פעיל של מנהל (שם משתמש וסיסמה של כניסה למערכת), של עובד פעיל שלא נמחק.
הקריאה צריכה להיות מופעלת בחבילה של החברה. אם היא חסומה, התשובה היא no_have_permission. במקרה כזה פנו לתמיכה בכתובת [email protected].
עובדים יופיעו בתשובה רק אם יש להם דיווחים בטווח שביקשתם.
3. כתובת הקריאה והפרמטרים
הכתובת: https://412.co.il/index.php/api/total. אפשר לשלוח את הפרמטרים בשיטת GET (בכתובת) או POST.
פרמטר | תיאור | חובה? | ברירת מחדל |
u | שם משתמש | כן | - |
p | סיסמה | כן | - |
dept | מזהה מחלקה, או כמה מזהים מופרדים בפסיק (למשל 12,15). הערך -1 פירושו כל המחלקות | לא | -1 (כל המחלקות) |
sy | שנת התחלה (4 ספרות) | לא | השנה הנוכחית |
sm | חודש התחלה, שתי ספרות (למשל 09) | לא | החודש הנוכחי |
sd | יום התחלה, שתי ספרות (למשל 01) | לא | 01 |
ey | שנת סיום | לא | שנת ההתחלה |
em | חודש סיום | לא | חודש ההתחלה |
ed | יום סיום | לא | היום האחרון של חודש הסיום |
כתבו חודשים וימים בשתי ספרות (09 ולא 9), כדי שהתאריך יזוהה כתקין.
איך הטווח נקבע
רק sy ו-sm: כל החודש, מהיום הראשון עד היום האחרון בו.
sy, sm, sd בלי ed: מהיום שבחרתם ועד סוף חודש הסיום (שהוא חודש ההתחלה אם לא שלחתם em).
כל ששת פרמטרי התאריך: הטווח המדויק שבחרתם, כולל שני הקצוות.
בלי אף פרמטר תאריך: החודש הנוכחי כולו.
4. מגבלות
מספר קריאות: עד 5 קריאות בשעה לכל חברה. הקריאה השישית באותה שעה נדחית עם rate_limit_exceeded, והתשובה כוללת כמה שניות להמתין (retry_after_seconds).
טווח תאריכים: עד 60 ימים (כולל היום הראשון והאחרון). טווח ארוך יותר נדחה עם date_range_exceeded. כדי לקבל תקופה ארוכה יותר, שלחו כמה קריאות לטווחים קצרים, ושימו לב שגם הן נספרות במכסת 5 הקריאות בשעה.
5. דוגמאות
כל ספטמבר 2026:
GET https://412.co.il/index.php/api/total?u=test&p=123456&sy=2026&sm=09
הטווח שיחושב: 2026-09-01 עד 2026-09-30 (30 ימים).
מ-15 באוגוסט עד 14 בספטמבר 2026, למחלקות 12 ו-15 בלבד:
GET https://412.co.il/index.php/api/total?u=test&p=123456&sy=2026&sm=08&sd=15&ey=2026&em=09&ed=14&dept=12,15
הטווח: 31 ימים, בתוך המגבלה.
טווח שחורג: מ-1 ביולי עד 30 בספטמבר 2026 הוא 92 ימים (31 + 31 + 30), ולכן התשובה:
{"status":0,"result":"date_range_exceeded","max_days":60,"requested_days":92}6. מבנה התשובה
התשובה היא JSON.
שדה | משמעות |
status | 1 = הצלחה. 0 = כישלון (במקרה של no_have_permission הערך הוא false) |
result | בהצלחה: רשימת שורות סיכום, שורה לכל עובד שיש לו דיווחים בטווח (לפי הפרמטר dept אם נשלח). ייתכנו גם שורות נוספות לפי תפקיד, כמו בדוח המסכם. בכישלון: קוד השגיאה או הודעה |
limit, retry_after_seconds | מופיעים רק בשגיאת rate_limit_exceeded: המכסה, וכמה שניות להמתין |
max_days, requested_days | מופיעים רק בשגיאת date_range_exceeded: הטווח המרבי והטווח שביקשתם |
הנתונים בכל שורה זהים לעמודות הדוח המסכם של אותו חודש במערכת (שעות, שעות נוספות, ימי חופשה ומחלה, הוצאות ועוד), ומושפעים מהסכם העבודה של כל עובד.
דוגמה לכישלון בהזדהות:
{"status":0,"result":"no authenticated."}הודעות שגיאה
הודעה | מה זה אומר | מה לעשות |
no authenticated / no authenticated. | שם משתמש או סיסמה חסרים או שגויים, המשתמש לא פעיל, או שהוא עובד רגיל | בדקו את u ו-p, והשתמשו במשתמש מנהל פעיל |
no_have_permission | הקריאה לא מאושרת לחברה (או שאין חבילה) | פנו לתמיכה |
rate_limit_exceeded | עברתם 5 קריאות בשעה | המתינו את מספר השניות ב-retry_after_seconds |
invalid dateformat. | פורמט התאריך שגוי | שלחו שנה בארבע ספרות, חודש ויום בשתי ספרות |
invalid_date | התאריך לא נקרא | תקנו את התאריכים |
invalid_date_range | תאריך ההתחלה אחרי תאריך הסיום | החליפו בין התאריכים |
date_range_exceeded | הטווח ארוך מ-60 ימים | חלקו לכמה קריאות קצרות |
שאלות נפוצות ופתרון בעיות
❓ שלחתי קריאה ואני מקבל "no authenticated."
שם המשתמש או הסיסמה שגויים, המשתמש מושבת, או שהוא משתמש עובד רגיל. השתמשו במשתמש של מנהל מערכת או מנהל מחלקה שיכול להיכנס למערכת.
❓ אני מקבל "no_have_permission"
הקריאה לא מאופשרת לחברה שלכם. פנו לתמיכה.
❓ הקריאה עבדה ופתאום נחסמה עם "rate_limit_exceeded"
המכסה היא 5 קריאות בשעה לחברה, וכל המשתמשים והמערכות של החברה חולקים אותה. המתינו את הזמן שמופיע ב-retry_after_seconds, וצמצמו את תדירות הקריאות.
❓ אני צריך שנה שלמה, והקריאה נדחית עם "date_range_exceeded"
הטווח המרבי הוא 60 ימים. שלחו קריאה לכל חודש בנפרד. שימו לב: 5 קריאות בשעה, כך ששנה שלמה תדרוש שעתיים לפחות.
❓ קיבלתי "invalid dateformat."
בדקו שהשנה בארבע ספרות והחודש והיום בשתי ספרות (למשל 09 ו-05).
❓ קיבלתי "invalid_date_range"
תאריך ההתחלה מאוחר מתאריך הסיום. תקנו אותם.
❓ לא שלחתי תאריכים ואני מקבל נתונים של החודש הנוכחי
זו ברירת המחדל: החודש הנוכחי, מהיום הראשון ועד האחרון בו.
❓ עובד מסוים לא מופיע בתשובה
עובד מופיע רק אם יש לו דיווחים בטווח. בדקו גם שהוא שייך למחלקה שביקשתם ב-dept, ושהוא פעיל.
❓ רוצה נתונים של מחלקה אחת בלבד
שלחו dept עם מזהה המחלקה. כמה מחלקות: מזהים מופרדים בפסיק. בלי dept (או עם -1) מתקבלים כל העובדים.
❓ הנתונים בתשובה שונים ממה שאני רואה בדוח המסכם במסך
בדקו שאותו טווח תאריכים ואותן מחלקות מופיעים בשני המקומות. אם יש הבדל שנשאר, שלחו לתמיכה את הקריאה (בלי הסיסמה) ואת שם העובד.
❓ מקבל מערך ריק ב-result
אין דיווחים בטווח ובמחלקות שביקשתם. בדקו את התאריכים.
❓ אפשר לשלוח את הקריאה בשיטת POST?
כן, הפרמטרים נקראים גם ב-GET וגם ב-POST. מומלץ POST כדי שהסיסמה לא תישמר בכתובת בהיסטוריה.
❓ איך אני מוצא את מזהה המחלקה?
הקריאה api/getDepts מחזירה את המחלקות עם המזהים שלהן (DeptID, DeptName).
❓ מנהל מחלקה קורא ל-API: האם הוא רואה רק את המחלקה שלו?
הקריאה מסננת רק לפי הפרמטר dept ששולחים. אל תסתמכו על כך שהקריאה מגבילה לפי המחלקה של המנהל; הגבילו בעצמכם בעזרת dept.
❓ יש קובץ PDF של המדריך הישן, האם הוא עדיין תקף?
המידע במדריך הזה הוא העדכני.
מילון מונחים
API - כתובת שמערכת חיצונית קוראת לה כדי לקבל נתונים.
דוח מסכם - סיכום שעות העובדים לתקופה, שורה לכל עובד.
JSON - פורמט תשובה שמערכות קוראות בקלות.
status - האם הקריאה הצליחה.
dept - מחלקה או מחלקות לסינון.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
כל החודש הנוכחי | api/total עם u ו-p בלבד | מחזיר את כל העובדים לחודש הנוכחי |
חודש מסוים | sy ו-sm | מהיום הראשון עד האחרון בחודש |
טווח מדויק | sy, sm, sd, ey, em, ed | עד 60 ימים |
מחלקות מסוימות | dept | סינון לפי מזהי מחלקות |
מאמרים קשורים
הפקת דוח חודשי מרוכז
API לקבלת דוח נוכחות יומי
api לקבלת רשימת עובדים
API ליצוא דיווחי הנוכחות כקובץ בפורמט אחיד
API להוספת עובד חדש