מה זה ומתי צריך את זה
ה-API הזה מחזיר קובץ טקסט שבו כל החתמת כניסה ויציאה של העובדים היא שורה בפורמט קבוע. תוכנת שכר או מערכת חיצונית יכולה למשוך את הקובץ אוטומטית, בלי להיכנס למסך במערכת. הקריאה עובדת רק לחברה שהוגדרה אצלנו לפורמט הייצוא הזה (ראו פרק 2).
מה המדריך הזה כולל
המדריך כולל: מדריך מקוצר, מי יכול לעשות מה, מה צריך כדי שזה יעבוד, כתובת הקריאה והפרמטרים, מבנה השורה בקובץ (עם פירוק של שורה לדוגמה), אילו דיווחים נכנסים לקובץ ואילו לא, הודעות שגיאה, שאלות נפוצות ופתרון בעיות, מילון מונחים וסיכום מהיר. מדריכי API אחרים של המערכת: "api לקבלת רשימת עובדים", "API לקבלת דוח נוכחות יומי" ו-"API להוספת עובד חדש" (מופיעים גם ב"מאמרים קשורים").
🎬 סרטון הסבר קצר
הסרטון מראה איך מושכים את דיווחי הנוכחות כקובץ טקסט: בדיקה מול התמיכה שהחברה מוגדרת לפורמט, מילוי "מזהה בשכר" בכרטיס העובד, הכנת שם משתמש וסיסמה, בניית כתובת הקריאה, הרצת הקריאה והטיפול בהודעות שגיאה.
מדריך מקוצר
ודאו מול התמיכה של EZTime שהחברה מוגדרת לפורמט הייצוא הזה.
בכרטיס כל עובד מלאו את השדה "מזהה בשכר" כפי שהוא רשום בתוכנת השכר.
הכינו שם משתמש וסיסמה של משתמש פעיל במערכת.
בנו את כתובת הקריאה עם הפרמטרים key, u, p ובחירה של fd, ed, note.
הריצו את הקריאה בשיטת GET. הקובץ יורד כקובץ טקסט.
אם התקבלה הודעה כמו "invalid parameters" או "invalid user", עברו לפרק ההודעות.
1. מי יכול לעשות מה
הקריאה לא נעשית מתוך מסך אלא ממערכת חיצונית, עם שם משתמש וסיסמה של משתמש במערכת.
מי | מה |
מנהל החברה | מעדכן בכרטיס העובד את "מזהה בשכר", ומספק למערכת החיצונית שם משתמש וסיסמה לקריאה. |
מנהל מחלקה, ראש משמרת, עובד | אין להם פעולה ייעודית ב-API הזה. הקובץ מכיל את כל עובדי החברה של המשתמש שהוזדהות בקריאה. |
תמיכת EZTime | מגדירה את החברה לפורמט הייצוא הזה. |
2. מה צריך כדי שזה יעבוד
הגדרת חברה: החברה צריכה להיות מוגדרת אצלנו לפורמט הייצוא הזה. בלי זה מתקבלת ההודעה "invalid client".
משתמש תקין: שם משתמש וסיסמה של משתמש פעיל. משתמש לא פעיל, עובד לא פעיל, משתמש מוקפא, משתמש שתוקפו פג או חברה שתוקפה פג לא יתקבלו, ותתקבל ההודעה "invalid user".
מזהה בשכר: בכרטיס העובד, בשדה "מזהה בשכר". אם השדה ריק, בקובץ יופיע מספר העובד.
מפתח הקריאה: הפרמטר key הוא ערך קבוע:
ZXp0aW1lX3NhbGFyeV9leHBvcnQ=.
3. כתובת הקריאה והפרמטרים
איפה: קריאה בשיטת GET לכתובת:
כל הפרמטרים נשלחים בכתובת (GET). בין fd ל-ed יכולים להיות עד 30 יום, למשל מ-1 עד 31 בחודש.
פרמטר | משמעות | חובה? | דוגמה |
key | מפתח הקריאה (ערך קבוע) | חובה | ZXp0aW1lX3NhbGFyeV9leHBvcnQ= |
u | שם משתמש | חובה | username |
p | סיסמה | חובה | password |
fd | תאריך התחלה, בפורמט שנה-חודש-יום | רשות. אם לא נשלח, התחלת היום הנוכחי | 2019-12-31 |
ed | תאריך סיום, בפורמט שנה-חודש-יום | רשות. אם לא נשלח, סוף היום הנוכחי | 2020-01-09 |
note | הוספת הערת הדיווח לשורת הכניסה. ערך 1 מפעיל | רשות. בלי הפרמטר, ההערות לא נכנסות לקובץ | 1 |
emp | מספר העובד (כמו בכרטיס העובד), כדי למשוך את הדיווחים של עובד אחד בלבד | רשות. בלי הפרמטר, כל העובדים | 1234 |
דוגמה מלאה (את xxx ו-***** מחליפים בשם המשתמש ובסיסמה):
דוגמה עם הערות בשורות:
אם בסיסמה יש תווים מיוחדים כמו & או # או +, יש לקודד אותם בכתובת (URL encoding), אחרת הסיסמה תתקבל שגויה.
4. מה חוזר מהקריאה
הצלחה: קובץ טקסט (שם הקובץ salary_ ואחריו מספר, בסיומת txt) יורד כהורדה. אם אין דיווחים בטווח, הקובץ ריק.
כישלון: מוצגת הודעה קצרה בטקסט: "invalid parameters", "invalid user", "invalid date", "date range max 30 days", "invalid client" או "invalid employee" (פירוט בפרק 7).
5. מבנה השורה בקובץ
כל שורה היא החתמה אחת, באורך קבוע של חלקים. שורה לדוגמה:
01000 0117 00000 17-11-19 001 1308 B
(בקובץ עצמו החלקים רצופים, בלי רווחים; הרווחים כאן רק כדי להראות את החלוקה)
הגרפיקה הבאה מפרקת את השורה הזו לחלקים.
חלק | בדוגמה | משמעות |
קידומת קבועה | 01000 | תמיד אותו ערך |
מספר העובד בשכר | 0117 | "מזהה בשכר" מכרטיס העובד. אם ריק, מספר העובד. מושלם באפסים משמאל עד 4 ספרות לפחות |
אפסים קבועים | 00000 | תמיד אותו ערך |
תאריך | 17-11-19 | יום-חודש-שנה בשתי ספרות (DD-MM-YY) |
קוד קבוע | 001 | תמיד אותו ערך |
שעת החתמה | 1308 | שעה ודקות (HHMM), בלי נקודתיים |
קוד דיווח | B | B = כניסה, E = יציאה |
הערה (רשות) | <הערה בדיווח> | מופיעה רק בשורת הכניסה, בתוך סימני < >, ורק כשנשלח note=1 וקיימת הערה לדיווח |
בין שורה לשורה יש שורה ריקה.
6. אילו דיווחים נכנסים לקובץ
לכל דיווח נוכחות (כניסה/יציאה) נכתבת שורת כניסה (B), ואחריה שורת יציאה (E).
אם לדיווח אין שעת יציאה (עובד שעדיין במשמרת, או שלא החתים יציאה), נכתבת רק שורת הכניסה.
תאריך שורת היציאה הוא תאריך הכניסה, גם אם המשמרת נגמרה אחרי חצות.
סוגי דיווח אחרים (כמו חופשה או מחלה) לא נכנסים לקובץ.
עובדים שנמחקו לא נכנסים. הקובץ כולל רק עובדי החברה של המשתמש שבקריאה.
מומלץ לפנות ל-API פעם או פעמיים ביום, בעיקר בשעות הלילה.
7. הודעות שגיאה
הודעה | משמעות | מה לעשות |
invalid parameters | חסר אחד מהפרמטרים key, u, p, או שערך key שגוי | בדקו שהעתקתם את key בדיוק, ושנשלחו u ו-p |
invalid user | שם המשתמש או הסיסמה שגויים, או שהמשתמש לא פעיל | בדקו שם משתמש וסיסמה, שהמשתמש והעובד פעילים, ושהסיסמה מקודדת נכון בכתובת |
invalid client | החברה לא מוגדרת לפורמט הייצוא הזה | פנו לתמיכת EZTime |
invalid date | תאריך שלא בפורמט שנה-חודש-יום, או תאריך סיום שמוקדם מתאריך ההתחלה | שלחו fd ו-ed בפורמט 2026-10-01, כש-ed אחרי fd או שווה לו |
date range max 30 days | בין fd ל-ed יש יותר מ-30 יום | חלקו את התקופה לכמה קריאות של עד 30 יום |
invalid employee | נשלח emp, ואין בחברה עובד פעיל (שלא נמחק) עם מספר העובד הזה | בדקו את מספר העובד בכרטיס העובד, בלי רווחים |
שאלות נפוצות ופתרון בעיות
❓ קיבלתי "invalid client", אבל השם והסיסמה נכונים
החברה לא מוגדרת אצלנו לפורמט הייצוא הזה. פנו לתמיכה כדי שתגדיר אותה.
❓ קיבלתי "invalid user" והסיסמה נכונה
ייתכן שהמשתמש או העובד אינו פעיל, שהמשתמש מוקפא, שתוקפו פג, או שיש בסיסמה תו מיוחד שלא קודד בכתובת. נסו להיכנס למערכת עם אותו משתמש כדי לוודא.
❓ קיבלתי "invalid parameters"
חסר key, u או p, או ש-key לא זהה לערך הקבוע שבפרק 3.
❓ הקובץ ירד אבל הוא ריק
אין דיווחי נוכחות בטווח התאריכים שנשלח. אם לא שלחתם fd ו-ed, הטווח הוא היום הנוכחי בלבד. שלחו fd ו-ed מפורשים.
❓ לא שלחתי תאריכים וקיבלתי רק את היום
זה כך: בלי fd מתחילים מתחילת היום הנוכחי, ובלי ed מסיימים בסוף היום הנוכחי. כדי לקבל את האתמול, שלחו אותו ב-fd וב-ed.
❓ עובד מסוים לא מופיע בקובץ
בדקו שיש לו דיווח נוכחות רגיל בטווח, שהוא לא נמחק, ושהוא שייך לחברה של המשתמש שבקריאה. אם העובד נמחק, בקשו שחזור או פנו לתמיכה עם שם העובד ותעודת הזהות שלו.
❓ בקובץ יש מספר עובד במקום מזהה השכר
השדה "מזהה בשכר" בכרטיס העובד ריק, ולכן המערכת כותבת את מספר העובד. מלאו את "מזהה בשכר".
❓ יש כניסה בלי יציאה
לדיווח אין שעת יציאה. תקנו או השלימו את היציאה במערכת ומשכו את הקובץ שוב.
❓ משמרת לילה: תאריך היציאה נראה שגוי
שורת היציאה נכתבת עם תאריך הכניסה גם אם היציאה אחרי חצות. התוכנה המקבלת צריכה להתייחס לכך.
❓ ההערות לא מופיעות
הוסיפו לקריאה note=1. ההערה מופיעה רק בשורת הכניסה, ורק אם קיימת הערה לדיווח.
❓ חופשה ומחלה לא מופיעות בקובץ
הקובץ מכיל רק החתמות כניסה ויציאה של דיווחי עבודה, לא ימי חופשה או מחלה.
❓ תיקנתי דיווח אחרי שמשכתי את הקובץ
הקובץ נבנה בכל קריאה מהנתונים העדכניים. משכו אותו שוב והחליפו את הקובץ הישן.
❓ איך מוחקים או מבטלים את הייצוא?
אין מה למחוק: הקריאה רק קוראת נתונים ולא משנה דבר במערכת. כדי להפסיק לקבל קבצים, הפסיקו את הקריאה במערכת החיצונית.
❓ אני לא רואה בשום מסך הגדרה לקריאה הזו
זה כך: הקריאה אינה מסך במערכת. הגדרת החברה נעשית על ידי התמיכה, ומזהה השכר נקבע בכרטיס העובד.
❓ האם המפתח בכתובת סודי?
המפתח הוא ערך קבוע לכל הלקוחות. מי שיש לו את שם המשתמש והסיסמה יכול למשוך את הנתונים, ולכן שמרו אותם בסוד ושלחו את הקריאה רק מהמערכת שלכם.
❓ קיבלתי "date range max 30 days"
קריאה אחת מחזירה עד 30 יום בין fd ל-ed. לחודש שלם (למשל 1 עד 31) זה מספיק; לתקופה ארוכה יותר משכו כמה קבצים, כל אחד של עד 30 יום.
❓ איך מושכים את הדיווחים של עובד אחד?
מוסיפים לכתובת את הפרמטר emp עם מספר העובד שלו, למשל &emp=1234. אם אין עובד פעיל עם המספר הזה מתקבלת ההודעה "invalid employee".
מקרא סמלים וצבעים
קוד | משמעות |
B | כניסה |
E | יציאה |
מילון מונחים
מזהה בשכר: השדה בכרטיס העובד שמזהה אותו בתוכנת השכר.
fd / ed: תאריך התחלה ותאריך סיום של הטווח.
note: פרמטר שמוסיף את הערת הדיווח לשורת הכניסה.
GET: שיטת שליחה שבה הפרמטרים נמצאים בכתובת.
סיכום מהיר
מה רוצים לעשות | איפה | מה זה משנה |
למשוך קובץ | קריאת GET לכתובת הקריאה | יורד קובץ טקסט של כניסות ויציאות |
לקבוע טווח | הפרמטרים fd ו-ed | בלעדיהם, רק היום הנוכחי |
להוסיף הערות | note=1 | ההערה נכתבת בשורת הכניסה |
לקבוע מזהה עובד בקובץ | כרטיס העובד, "מזהה בשכר" | אחרת נכתב מספר העובד |