Skip to main content

Real-World Scenarios

Five situations every Work Card integration runs into. Each one: what happens, what you'll see in the API response, and what to do.

Employee forgets to check out​

What happens: The employee leaves at 17:00, but no check-out event is submitted (forgotten swipe, device left in a drawer, etc.). At 19:30, someone notices and wants to submit it.

What you see: If you submit now with f_date: "...17:00:00+03:00" and f_aitiologia: null, Ergani will reject it — more than 15 minutes have passed since f_date, so f_aitiologia is required.

How to fix it:

Be honest about what the justification codes cover

001–003 cover power/telecom outages, employer system failures, and Ergani connectivity problems. "The employee forgot to swipe" is none of these. Using a code that doesn't match the real cause is a false declaration on a legal record — don't do it to make a 400 go away.

There is no API-level fix that makes this submission both accurate and on-time after the fact. Your options, in order of preference:

  1. Prevent it: build a same-day reminder/alert in your system so missed check-outs are caught within the 15-minute window.
  2. If it's already late: submit the event anyway with the accurate f_date: "...17:00:00+03:00". It will be rejected without f_aitiologia. At that point this becomes a manual/compliance process outside the API — consult the employer's obligations under Ν. 4808/2021 for late declarations. Do not paper over it with a force-majeure code that doesn't apply.

Duplicate event submission​

What happens: Your system submits the same check-in twice — e.g. a retry fired after the first request actually succeeded.

What you see: Both requests return 200 OK, each with its own protocol. Ergani does not detect or reject the duplicate.

How to fix it: Nothing to fix — this is safe by design. Per Repeated events for the same employee and day, Ergani uses the most recently submitted event of a given f_type for a given f_afm + f_reference_date as authoritative. If both submissions have the same f_date (because they're the same retried event), the duplicate has no effect on the Actual Work Calendar. Log both protocol values for your audit trail, but don't build logic to "prevent" this — see Idempotency and deduplication.

Network failure mid-request​

What happens: You send the check-in POST, but the connection drops before you receive a response. You don't know whether Ergani received and processed it.

What you see: A client-side timeout or connection error — no protocol, no message, nothing from Ergani.

How to fix it:

  1. Resubmit the same event (same f_afm, f_type, f_reference_date, f_date). This is safe — see Duplicate event submission above.
  2. If the resubmission also fails and you're approaching the 15-minute on-time window, keep retrying — a request that never reached Ergani doesn't "use up" your window, but each passing minute brings you closer to needing a justification code for connectivity problems (f_aitiologia: "003") if the outage was on your end or Ergani's — not if you're simply slow to retry.
  3. Once a request succeeds, store its protocol. If you resubmitted multiple times, you may end up with multiple protocol values for the same logical event — that's fine, the last one wins.

Split shifts (same day)​

What happens: An employee checks in at 09:00, checks out for a 2-hour break at 13:00, and checks back in at 15:00, finishing at 19:00 — four events for one f_reference_date.

What you see: All four submissions succeed independently, each with its own protocol:

[{ "id": "201", "protocol": "ΕΥΣ201", "submitDate": "06/05/2024 09:00" }]
[{ "id": "202", "protocol": "ΕΥΣ202", "submitDate": "06/05/2024 13:00" }]
[{ "id": "203", "protocol": "ΕΥΣ203", "submitDate": "06/05/2024 15:00" }]
[{ "id": "204", "protocol": "ΕΥΣ204", "submitDate": "06/05/2024 19:00" }]

How to fix it: Nothing to fix — this is supported natively. Submit each event as it happens, with f_type alternating 0/1/0/1 and the same f_reference_date ("2024-05-06") throughout. No special "split shift" flag exists or is needed.

Late correction​

What happens: You submitted a check-in with the wrong time (08:55 instead of the actual 08:47), and you're correcting it now, 40 minutes later.

What you see: Submitting the corrected event (f_date: "...08:47:00+03:00", f_aitiologia: null) is rejected — the gap between f_date (08:47) and the submission time (now, ~09:35) is more than 15 minutes.

How to fix it: This is the same situation as Employee forgets to check out — a data correction, not a force-majeure event. The justification codes don't apply. Practically:

  • If your system catches the mistake within 15 minutes of the original submission (not the original event), resubmit immediately — it will still be late relative to the true f_date, but this is a known limitation of the 15-minute-from-event-time rule, not something the API lets you route around with f_aitiologia.
  • For corrections discovered well after the fact, treat this the same as any other late declaration under your compliance process — see Late Submissions for the legal framework.

What's next​

You've now covered the full Work Card integration surface. For everything else Ergani's API can do (schedules, hiring forms, leaves), see Other declaration types.