Skip to main content

Core Concepts

Read this before Workflows. It explains the five ideas that make Ergani's Work Card system make sense — no API syntax, just the mental model.

Work Card event​

A Work Card event records one moment: an employee arriving at or leaving a workplace. Every event is one of two types — a check-in or a check-out.

Each event carries:

  • who — the employee (ΑΦΜ, name)
  • when — the exact timestamp of the arrival/departure
  • which work-day it belongs to (the "reference date")

You send events to Ergani in real time, as they happen.

Check-in vs. check-out​

  • Check-in (Προσέλευση) — the employee arrives.
  • Check-out (Αποχώρηση) — the employee leaves.

A normal day produces exactly one check-in and one check-out. A split shift (employee leaves and returns during the day) produces more — see Split shifts.

The reference date​

Every event belongs to a reference date — the calendar work-day it counts toward, not necessarily the calendar date of the timestamp.

This matters for night shifts. If an employee checks in at 21:00 on Monday and checks out at 05:00 on Tuesday, both events have a reference date of Monday — they belong to the same shift.

Submission lifecycle​

Every event you send goes through the same lifecycle:

  1. You submit a check-in or check-out event.
  2. Ergani validates it (employee exists, Work Card is active for them, timestamps make sense).
  3. Accepted → Ergani returns a protocol number. The event is now part of the employee's official record.
  4. Rejected → Ergani returns 400 Bad Request with a message explaining why. Nothing is recorded.

There is no "pending" state — a submission is accepted or rejected immediately, in the same response.

What the protocol number means​

The protocol value (e.g. "ΕΥΣ92") returned on success is your proof of acceptance. It is:

  • unique to this submission,
  • required if you ever need to retrieve the submitted document as a PDF,
  • the thing you log for audit purposes.

No protocol in the response means the event was not recorded. Treat "accepted" and "has a protocol" as the same thing.

On-time vs. late​

Ergani measures the time between the event itself (f_date) and the moment you submit it. If that gap is 15 minutes or less (± 1 minute), the event is on time and f_aitiologia must be null.

If the gap is more than 15 minutes, the event is late, and the submission is rejected unless you provide a justification code in f_aitiologia. Justification codes only cover force-majeure situations (power/telecom outage, system failure) — see Late and justified submissions.

Practical rule: submit every event within 15 minutes of it happening. If your system can't guarantee that (offline devices, batch syncs), read Network failure mid-request before you build your retry logic.

Corrections, not edits​

There is no "edit" or "delete" endpoint for Work Card events. To correct a mistake, submit a new event of the same type for the same employee and reference date — the most recently submitted one wins. See Corrections.

What's next​