API הנוכחות של Finwork

• מה שולחים: לכל עובד/ת — סיכום חודשי (ימים, שעות רגילות, שעות נוספות לפי אחוז, חופשה, מחלה, מילואים, חג), תאריכי היעדרויות, ובאופן אופציונלי גם פירוט יומי.
• לאן: POST https://finwork.co.il/api/v1/attendance/submissions, בגוף JSON.
• איך מזדהים: לכל מעסיק יש מפתח משלו, והוא יוצר אותו ב-Finwork. המפתח עובר בכותרת Authorization: Bearer fwa_live_….
• מה קורה אחר כך: כל עובד/ת מזוהה לפי ת״ז, והנתונים נכנסים לחודש השכר. התשובה מפרטת, לפי מספרי שורות, מה נכנס ומה לא.
• מתי: בסוף כל חודש (final), ושוב אם יש תיקון. עד שהחודש נשלח לעיבוד השכר, שליחה חדשה מחליפה את הנתונים הקודמים.

1. המעסיק יוצר מפתח ב-Finwork: אינטגרציות ← שעון נוכחות. בוחרים את השעון ואז "יצירת מפתח". המפתח מוצג פעם אחת בלבד, והמעסיק מוסר אותו לכם.
2. בודקים את המפתח: GET /ping מחזיר את שם המעסיק. כך מוודאים שחיברתם את הלקוח הנכון.
3. שולחים בדיקה: POST /submissions?dryRun=true עובר את כל הבדיקות ואת התאמת העובדים, ולא שומר כלום. אפשר לחזור על זה כמה פעמים שצריך.
4. עולים לאוויר: שולחים בסוף כל חודש עם "status": "final". ראו גם את רשימת הבדיקות.

כל בקשה נושאת את מפתח המעסיק בכותרת Authorization: Bearer fwa_live_…. המפתח מורכב מ-fwa_live_ ועוד 32 תווים. הוא שייך למעסיק אחד ולשעון אחד, ונותן הרשאה אחת בלבד: לשלוח נתוני נוכחות של אותו מעסיק.

• HTTPS בלבד. בקשה שמגיעה ב-HTTP לא נענית.
• שומרים את המפתח מוצפן, ולא רושמים אותו ביומנים או בהודעות שגיאה.
• אם המעסיק יוצר מפתח חדש, הקודם מפסיק לעבוד מיד ומחזיר 401. אם יש חשד שמפתח דלף, צריך לפנות למעסיק, וגם ל-security@finwork.co.il.
• אל Finwork ניגשים רק במפתח. אנחנו אף פעם לא מבקשים מכם סיסמה או גישה למערכת שלכם.

הכתובת: https://finwork.co.il/api/v1/attendance. כל התשובות ב-JSON, עם הכותרת x-finwork-api-version: 2026-10.

שליחה אחת = חודש אחד של מעסיק אחד. בדוגמה המלאה למטה מופיעים כל השדות.

כל עובד/ת חייב/ת להופיע עם nationalId או עם employeeNumber, לפחות אחד מהם. אותו/ה עובד/ת לא יכול/ה להופיע פעמיים באותה שליחה.

כל הכמויות הן מספרים עשרוניים עם עד 2 ספרות אחרי הנקודה. למשל 8.5 הוא שמונה שעות וחצי, ו-0.5 הוא חצי יום. לא שולחים HH:MM. שדה שלא נשלח לא משנה את מה שכבר רשום, ו-0 הוא אפס.

כל היעדרות היא { type, from, to, days? }. התאריכים בפורמט YYYY-MM-DD וכלולים בטווח. days הוא אופציונלי, למשל בשביל חצי יום. היעדרות שחוצה סוף חודש מפוצלת: החלק של כל חודש נשלח בחודש שלו.

כל יום הוא { date, dayType?, workedMinutes?, absence? }. dayType הוא אחד מ-workday, friday, holiday_eve, rest, holiday. workedMinutes הוא מספר שלם בין 0 ל-1440.

הפירוט היומי לא מחליף את הסיכום. השכר מחושב לפי summary, והימים משמשים לבדיקת עקביות ולתאריכי מחלה כשאין absences.

• השעון מחשב את הפיצול לפי אחוזים לפי חוק שעות עבודה ומנוחה וההסכם של המעסיק: שעות רגילות, השעתיים הנוספות הראשונות ביום ב-125%, מעבר להן 150%. עבודה במנוחה השבועית או בחג היא 150%, ושעות נוספות בהן הן 175% ו-200%.
• כל שעה נספרת פעם אחת בלבד. הסכום regularHours + overtime125Hours + overtime150Hours + restDayHours + overtime175Hours + overtime200Hours הוא כל השעות שעבדו בחודש.
• Finwork מחשבת את השכר: התעריפים, דמי מחלה לפי החוק (יום 1, ימים 2–3, מיום 4), דמי חגים ודמי נסיעה, לפי הנתונים שנשלחו.
• שעות ב-175% וב-200%, שעות לילה, חל״ת, היעדרות לא מוצדקת וימי נסיעה לא נבלעים בשדה אחר. הם נרשמים בחודש השכר כשורה גלויה למשרד, ותשובת השליחה מציינת זאת בקוד EXTRA_HOURS_NOTED.
• אזור הזמן הוא שעון ישראל. תאריכים נכתבים בפורמט YYYY-MM-DD.
• עובד/ת שהתחיל/ה או סיים/ה באמצע החודש נשלח/ת עם הימים שעבד/ה בפועל.
• אילו חודשים מותר לשלוח: החודש הנוכחי, החודש הקודם, או חודש ישן יותר שעדיין פתוח בשכר. חודש שכבר נשלח לעיבוד מחזיר 409 PERIOD_LOCKED.
• נתונים שהמעסיק או המשרד הזינו ידנית לא נדרסים. במקרה כזה התשובה מציינת KEPT_MANUAL בשורה של העובד/ת.

• ניסיון חוזר (למשל אחרי timeout) נשלח עם אותו submissionId ואותו תוכן. הוא מחזיר את אותה תשובה עם "replay": true, והנתונים לא נקלטים פעמיים.
• תיקון נשלח עם submissionId חדש. אפשר לשלוח את כל החודש או רק את העובדים שתוקנו. הנתונים של העובדים שבשליחה מתחלפים, כולל תאריכי המחלה, ושאר העובדים לא משתנים.
• אותו submissionId עם תוכן אחר מחזיר 409 SUBMISSION_CONFLICT. כך תיקון לא נבלע בטעות כניסיון חוזר.
• יותר מ-2,000 עובדים, או גוף גדול מ-2MB, מפצלים לכמה שליחות. לכל שליחה submissionId משלה, וכל אחת חלה רק על העובדים שבה.

1. לפי ת״ז, מול העובדים של המעסיק. אחרי התאמה, מספר העובד שלכם נלמד לחודשים הבאים.
2. לפי מספר עובד שכבר נלמד, מת״ז או משיוך ידני של המעסיק.
3. לפי שם — לא. שני עובדים יכולים לשאת אותו שם. עובד/ת שלא זוהה/תה מסומן/ת EMPLOYEE_NOT_FOUND וממתין/ה למעסיק: קליטה כעובד/ת חדש/ה (כרטיס וקישור לטופס 101), שיוך לעובד/ת קיים/ת, או "לא בשכר". אחרי זה הנתונים נכנסים, ובחודש הבא הזיהוי אוטומטי. עד שמטפלים — המעסיק לא יכול לשלוח את חודש השכר.
4. מי שהמעסיק סימן "לא בשכר" (בעלים, קבלן) מסומן/ת NOT_ON_PAYROLL בכל שליחה, ולא נכנס/ת.
5. אם הת״ז ומספר העובד מצביעים על שני עובדים שונים, מסמנים IDENTITY_CONFLICT ולא מנחשים.

עובד/ת שנקלט/ה במערכת שלכם ומילא/ה שם טופס 101 — שלחו לנו את הטופס החתום, והוא/היא נקלט/ת גם אצלנו בלי למלא שוב. הטופס נקרא לתוך מבנה טופס 101, המס מחושב לפיו, והמעסיק מקבל התראה לבדוק ולאשר.

POST https://finwork.co.il/api/v1/attendance/form101
{
  "apiVersion": "2026-10",
  "employee": { "nationalId": "123456782", "employeeNumber": "1042" },
  "file": { "contentBase64": "JVBERi0xLjcK...", "mimeType": "application/pdf", "filename": "101-dana.pdf" }
}

• זיהוי: לפי nationalId (מהבקשה או מהטופס), או לפי employeeNumber שכבר נלמד. ת״ז בבקשה שלא תואמת לטופס — IDENTITY_CONFLICT.
• אין עובד/ת כזה/ו — נפתח כרטיס מהטופס (ת״ז תקינה, שם, נייד או מייל), employeeNumber נלמד, והקישור להשלמת הפרטים והבנק יוצא לנייד. תשובה 201.
• קובץ עד 3MB. הסוג נבדק לפי התוכן: PDF, JPG, PNG או WEBP.
• בטופס רשום מעסיק אחר — FORM101_OTHER_EMPLOYER, ולא נשמר דבר.

שליחה תקינה מחזירה 200, ושליחת draft מחזירה 202. בתשובה יש ספירות, ורשימת issues לפי מספרי שורות: מי לא זוהה, מי נשמר ידנית, ומה נרשם לטיפול המשרד. אם יש שגיאת בדיקה (422), שום דבר לא נשמר. בתשובות אין שמות ואין ת״ז, רק נתיבים וקודים.

HTTP/1.1 200 OK
{
  "submission": {
    "id": "6f1c2b8e-1d3a-4b5c-9e2f-7a8b9c0d1e2f",
    "submissionId": "meckano-48213-2026-10-final-1",
    "period": "2026-10",
    "status": "partial",
    "final": true,
    "receivedAt": "2026-11-01T04:00:03.120Z",
    "employees": { "received": 42, "matched": 41, "applied": 40, "keptManual": 1, "unmatched": 1 }
  },
  "issues": [
    { "path": "employees[17]", "code": "EMPLOYEE_NOT_FOUND", "message": "...", "messageHe": "..." },
    { "path": "employees[3]", "code": "KEPT_MANUAL", "message": "...", "messageHe": "..." }
  ],
  "warnings": [],
  "payrollMonth": { "opened": false }
}

HTTP/1.1 422 Unprocessable Entity
{
  "error": { "code": "VALIDATION_FAILED", "message": "Submission failed validation", "messageHe": "השליחה לא עברה בדיקה" },
  "errors": [
    { "path": "employees[4].nationalId", "code": "INVALID_NATIONAL_ID", "message": "Invalid Israeli ID number (check digit)", "messageHe": "מספר זהות לא תקין (ספרת ביקורת)" },
    { "path": "employees[9].summary.sickDays", "code": "OUT_OF_RANGE", "message": "Value out of allowed range: max 31 per month", "messageHe": "ערך מחוץ לטווח המותר: עד 31 לחודש" }
  ],
  "warnings": [ { "path": "employees[0].summary.mealVouchers", "code": "UNKNOWN_FIELD", "message": "Unknown field — ignored", "messageHe": "שדה לא מוכר — לא נקלט" } ]
}

• עד 60 בקשות ב-10 דקות לכל מפתח, ועד 300 ב-10 דקות מאותה כתובת. מעבר לזה חוזרת התשובה 429, ומנסים שוב בעוד כמה דקות עם המתנה הולכת וגדלה.
• גוף הבקשה עד 2MB, עד 2,000 עובדים בשליחה, ועד 31 ימים בפירוט היומי של עובד/ת.
• שגיאה 500 אפשר לשלוח שוב עם אותו submissionId. הנתונים לא ייקלטו פעמיים.

• מינימום נתונים. לא שולחים טביעות אצבע, תמונות, מיקום GPS או נתונים ביומטריים. לשכר הם לא נחוצים, ואנחנו לא קולטים אותם.
• הנתונים מוצפנים בדרך (TLS). ההרשאה במסד הנתונים מבודדת בין מעסיקים: מפתח של מעסיק אחד לא רואה ולא כותב שום דבר של מעסיק אחר.
• שורות שלא זוהו נשמרות מוצפנות עד שהמעסיק משייך אותן. מהשליחה עצמה נשמרות רק ספירות וקודים.
• פגיעות אבטחה מדווחים ל-security@finwork.co.il. מדיניות האבטחה.

כל הבדיקות האלה רצות עם ?dryRun=true, מול מפתח אמיתי של לקוח משותף, ובלי לשמור כלום:

1. GET /ping מחזיר את שם המעסיק הנכון.
2. שליחה של חודש מלא עוברת בלי שגיאות, וכל העובדים מזוהים.
3. ת״ז עם ספרת ביקורת שגויה מחזירה INVALID_NATIONAL_ID בשורה הנכונה.
4. עובד/ת שלא קיים/ת אצל המעסיק מחזיר/ה EMPLOYEE_NOT_FOUND, ושאר השליחה עוברת.
5. ימי מחלה עם תאריכים: סך הימים ב-absences שווה ל-sickDays, ואין אזהרה.
6. עובד/ת עם שעות 175% מקבל/ת EXTRA_HOURS_NOTED, ולא שגיאה.
7. אחרי עלייה לאוויר: ניסיון חוזר עם אותו מזהה מחזיר "replay": true, ותיקון נשלח עם מזהה חדש.

• finwork-attendance-api.json — הגדרת OpenAPI 3.1, לייבוא ל-Postman או ליצירת קוד.
• attendance-sample.json — שליחה לדוגמה, אותה דוגמה כמו בעמוד הזה.
• attendance-template.csv — לשעון שעוד לא מחובר: קובץ חודשי שהמעסיק מעלה בחודש השכר, עם אותם שדות.

{
  "apiVersion": "2026-10",
  "submissionId": "meckano-48213-2026-10-final-1",
  "period": "2026-10",
  "status": "final",
  "generatedAt": "2026-11-01T06:00:00+02:00",
  "source": { "system": "Meckano", "version": "5.12" },
  "employer": { "companyNumber": "511234567" },
  "employees": [
    {
      "nationalId": "123456782",
      "employeeNumber": "1042",
      "firstName": "דנה",
      "lastName": "כהן",
      "phone": "0521234567",
      "startDate": "2026-09-14",
      "summary": {
        "workDays": 20,
        "regularHours": 172.5,
        "overtime125Hours": 6,
        "overtime150Hours": 1.5,
        "restDayHours": 0,
        "vacationDays": 1,
        "sickDays": 2,
        "reserveDays": 0,
        "holidayDays": 0,
        "travelDays": 20
      },
      "absences": [
        { "type": "sick", "from": "2026-10-12", "to": "2026-10-13" },
        { "type": "vacation", "from": "2026-10-20", "to": "2026-10-20" }
      ],
      "days": [
        { "date": "2026-10-01", "dayType": "workday", "workedMinutes": 545 },
        { "date": "2026-10-12", "dayType": "workday", "absence": "sick" }
      ]
    }
  ]
}

# 1. המפתח תקין, ולאיזה מעסיק הוא שייך
curl -s https://finwork.co.il/api/v1/attendance/ping \
  -H "Authorization: Bearer $FINWORK_KEY"

# 2. בדיקה בלי לשמור (מומלץ בכל פיתוח)
curl -s -X POST "https://finwork.co.il/api/v1/attendance/submissions?dryRun=true" \
  -H "Authorization: Bearer $FINWORK_KEY" \
  -H "Content-Type: application/json" \
  --data @october.json

# 3. השליחה האמיתית
curl -s -X POST https://finwork.co.il/api/v1/attendance/submissions \
  -H "Authorization: Bearer $FINWORK_KEY" \
  -H "Content-Type: application/json" \
  --data @october.json

# 4. מצב שליחה
curl -s https://finwork.co.il/api/v1/attendance/submissions/6f1c2b8e-1d3a-4b5c-9e2f-7a8b9c0d1e2f \
  -H "Authorization: Bearer $FINWORK_KEY"

דרך המעסיק המשותף, או בווטסאפ 050-2277087. כדי שנוכל לבדוק, ציינו את מזהה השליחה (submission.id), ולא את המפתח.