Skip to content

withlogicco/ergani-python-sdk

BranchesTags

Repository files navigation

Ergani Python SDK

ergani is a Python SDK for interacting with the API of Ergani.

Requirements

Python 3.10 or later

Installation

The ergani package is available on PyPI and you can install it through your favorite package manager:

pip install ergani

Usage

Create a client

To create a new Ergani client you have to set your Ergani username, password and optionally the Ergani API base URL, that defaults to https://trialeservices.yeka.gr/WebServicesAPI/api.

import os
from ergani.client import ErganiClient

ERGANI_USERNAME = os.environ.get("ERGANI_USERNAME", "")
ERGANI_PASSWORD = os.environ.get("ERGANI_PASSWORD", "")
ERGANI_BASE_URL = os.environ.get("ERGANI_BASE_URL", "")

ergani_client = ErganiClient(ERGANI_USERNAME, ERGANI_PASSWORD)

If you intend to use this package for multiple company entities, it is necessary to create separate client instances for each entity with the appropriate credentials.

We are going to use the aforementioned ergani_client for the following usage examples.

Work card

Submit work card records to Ergani in order to declare an employee's movement (arrival, departure).

def submit_work_card(company_work_cards: List[CompanyWorkCard]) -> (Response | None)

Example

from datetime import datetime, timedelta
from ergani.models import CompanyWorkCard, WorkCard

today = datetime.today()
yesterday = today - timedelta(days=1)

work_card_1 = WorkCard(
    employee_tax_identification_number="123456789",
    employee_first_name="first_name",
    employee_last_name="last_name",
    work_card_movement_type="ARRIVAL",
    work_card_submission_date=today.date(),
    work_card_movement_datetime=today,
)

work_card_2 = WorkCard(
    employee_tax_identification_number="123456789",
    employee_first_name="first_name",
    employee_last_name="last_name",
    work_card_movement_type="ARRIVAL",
    work_card_submission_date=today.date(),
    work_card_movement_datetime=today,
)

company_work_card_1 = CompanyWorkCard(
    employer_tax_identification_number="123456789",
    business_branch_number=1,
    card_details=[work_card_1, work_card_2],
)

work_card_3 = WorkCard(
    employee_tax_identification_number="123456789",
    employee_first_name="first_name",
    employee_last_name="last_name",
    work_card_movement_type="ARRIVAL",
    work_card_submission_date=today.date(),
    work_card_movement_datetime=yesterday,
    late_declaration_justification="POWER_OUTAGE",
)

company_work_card_2 = CompanyWorkCard(
    employer_tax_identification_number="123456789",
    business_branch_number=2,
    card_details=[work_card_3],
)

company_work_cards = [company_work_card_1, company_work_card_2]
response = ergani_client.submit_work_card(company_work_cards=company_work_cards)

Note: You can submit work cards for various employees across multiple company branches simultaneously as shown above.

Overtime

Submit overtime records to Ergani in order to declare employees overtimes.

def submit_overtime(company_overtimes: List[CompanyOvertime]) -> (Response | None)

Example

from datime import datetime
from ergani.models import CompanyOvertime, Overtime

today = datetime.today()

overtime = Overtime(
    employee_tax_identification_number="123456789",
    employee_social_security_number="123456789",
    employee_first_name="first_name",
    employee_last_name="last_name",
    overtime_date=today.date(),
    overtime_start_time=time(hour=18),
    overtime_end_time=time(hour=20),
    overtime_cancellation=False,
    employee_profession_code="123456",
    overtime_justification="EXCEPTIONAL_WORKLOAD",
    weekly_workdays_number=5,
)

company_overtime = CompanyOvertime(
    business_branch_number=1,
    sepe_service_code="12345",
    business_primary_activity_code="1234",
    business_branch_activity_code="1234",
    kallikratis_municipal_code="12345678",
    legal_representative_tax_identification_number="123456789",
    employee_overtimes=[overtime],
)

company_overtimes = [company_overtime]
response = ergani_client.submit_overtime(company_overtimes=company_overtimes)

Note: You can submit overtime records for various employees across multiple company branches simultaneously.

Daily schedule

Submit daily schedules to Ergani in order to declare schedules for employees that don't have a fixed schedule (e.g. shift workers).

def submit_daily_schedule(company_daily_schedules: List[CompanyDailySchedule]) -> (Response | None)

Example

from datime import datetime, timedelta
from ergani.models import CompanyDailySchedule, EmployeeDailySchedule, WorkdayDetails

today = datetime.today()
tomorrow = today + timedelta(days=1)

workday_details = WorkdayDetails(
    work_type="WORK_FROM_HOME", start_time=time(hour=9), end_time=time(hour=17)
)

employee_daily_schedule = EmployeeDailySchedule(
    employee_tax_identification_number="123456789",
    employee_first_name="first_name",
    employee_last_name="last_name",
    schedule_date=tomorrow.date(),
    workday_details=[workday_details],
)

company_daily_schedule = CompanyDailySchedule(
    business_branch_number=1, employee_schedules=[employee_daily_schedule]
)

company_daily_schedules = [company_daily_schedule]
response = ergani_client.submit_daily_schedule(
    company_daily_schedules=company_daily_schedules
)

Weekly schedule

Submit weekly schedules to Ergani in order to declare schedules for employees that have a fixed schedule.

def submit_weekly_schedule(company_weekly_schedules: List[CompanyWeeklySchedule]) -> (Response | None)

Example

from datime import datetime, timedelta
from ergani.models import CompanyDailySchedule, EmployeeDailySchedule, WorkdayDetails

today = datetime.today()
days_until_next_monday = (0 - today.weekday() + 7) % 7
next_week_monday = today + timedelta(days=days_until_next_monday)

next_week_start = next_week_monday.replace(hour=0, minute=0, second=0, microsecond=0)
next_week_end = next_week_start + timedelta(days=5)

workday_details = WorkdayDetails(
    work_type="WORK_FROM_HOME", start_time=time(hour=9), end_time=time(hour=17)
)

employee_weekly_schedule = []

for i in range(5):  # 5 days in a work week (Monday to Friday)
    current_day = next_week_start + timedelta(days=i)

    schedule = EmployeeWeeklySchedule(
        employee_tax_identification_number="123456789",
        employee_first_name="first_name",
        employee_last_name="last_name",
        schedule_date=current_day.date(),
        workday_details=[workday_details],
    )

    employee_weekly_schedule.append(schedule)

company_weekly_schedule = CompanyWeeklySchedule(
    business_branch_number=1,
    employee_schedules=[employee_weekly_schedule],
    start_date=next_week_start,
    end_date=next_week_end,
)

company_weekly_schedules = [company_weekly_schedule]
response = ergani_client.submit_weekly_schedule(
    company_weekly_schedules=company_weekly_schedules
)

Note: You can submit weekly schedules for various employees across multiple company branches simultaneously.

Full reference documentation is available at https://ergani.withlogic.dev/.

Glossary

The glossary might help you if you're taking a look at the official documentation of the Ergani API (https://eservices.yeka.gr/(S(ayldvlj35eukgvmzrr055oe5))/Announcements.aspx?id=257).

Work card

Original Original help text (in Greek) Translated
f_afm_ergodoti Α.Φ.Μ Εργοδότη (Για επαλήθευση) employer_tax_identification_number
f_aa Α/Α Παραρτήματος business_branch_number
f_comments ΣΧΟΛΙΑ comments
f_afm ΑΡΙΘΜΟΣ ΦΟΡΟΛΟΓΙΚΟΥ ΜΗΤΡΩΟΥ (Α.Φ.Μ.) employee_tax_indentification_number
f_eponymo ΕΠΩΝΥΜΟ employee_last_name
f_onoma ΟΝΟΜΑ employee_first_name
f_type Τύπος Κίνησης work_card_movement_type
f_reference_date ΗΜ/ΝΙΑ Αναφοράς work_card_submission_date
f_date ΗΜ/ΝΙΑ Κίνησης work_card_movement_datetime
f_aitiologia ΚΩΔΙΚΟΣ ΑΙΤΙΟΛΟΓΙΑΣ (Σε περίπτωση Εκπρόθεσμου) late_declaration_justification

Work card movement types

Original API code Original help text (in Greek) Translated
0 ΠΡΟΣΕΛΕΥΣΗ ARRIVAL
1 ΑΠΟΧΩΡΗΣΗ DEPARTURE

Work card justifications

Original API code Original help text (in Greek) Translated
001 ΠΡΟΒΛΗΜΑ ΣΤΗΝ ΗΛΕΚΤΡΟΔΟΤΗΣΗ/ΤΗΛΕΠΙΚΟΙΝΩΝΙΕΣ POWER_OUTAGE
002 ΠΡΟΒΛΗΜΑ ΣΤΑ ΣΥΣΤΗΜΑΤΑ ΤΟΥ ΕΡΓΟΔΟΤΗ EMPLOYER_SYSTEMS_UNAVAILABLE
003 ΠΡΟΒΛΗΜΑ ΣΥΝΔΕΣΗΣ ΜΕ ΤΟ ΠΣ ΕΡΓΑΝΗ ERGANI_SYSTEMS_UNAVAILABLE

Overtime

Original Original help text (in Greek) Translated
f_aa Α/Α Παραρτήματος business_branch_number
f_rel_protocol ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΑΡΙΘ. ΠΡΩΤ. related_protocol_id
f_rel_date ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΗΜΕΡΟΜΗΝΙΑ related_protocol_date
f_ypiresia_sepe ΚΩΔΙΚΟΣ ΥΠΗΡΕΣΙΑΣ ΣΕΠΕ sepe_service_code
f_ergodotikh_organwsh ΕΡΓΟΔΟΤΙΚΗ ΟΡΓΑΝΩΣΗ employer_organization
f_kad_kyria Κ.Α.Δ. - ΚΥΡΙΑ ΔΡΑΣΤΗΡΙΟΤΗΤΑ business_primary_activity_code
f_kad_deyt_1 Κ.Α.Δ. - ΚΥΡΙΑ ΔΡΑΣΤΗΡΙΟΤΗΤΑ 1 business_secondary_activity_code_1
f_kad_deyt_2 Κ.Α.Δ. - ΚΥΡΙΑ ΔΡΑΣΤΗΡΙΟΤΗΤΑ 2 business_secondary_activity_code_2
f_kad_deyt_3 Κ.Α.Δ. - ΚΥΡΙΑ ΔΡΑΣΤΗΡΙΟΤΗΤΑ 3 business_secondary_activity_code_3
f_kad_deyt_4 Κ.Α.Δ. - ΚΥΡΙΑ ΔΡΑΣΤΗΡΙΟΤΗΤΑ 4 business_secondary_activity_code_4
f_kad_pararthmatos Κ.Α.Δ. ΠΑΡΑΡΤΗΜΑΤΟΣ business_brach_activity_code
f_kallikratis_pararthmatos ΔΗΜΟΤΙΚΗ / ΤΟΠΙΚΗ ΚΟΙΝΟΤΗΤΑ kallikratis_municipal_code
f_comments ΠΑΡΑΤΗΡΗΣΕΙΣ comments
f_afm_proswpoy Νόμιμος Εκπρόσωπος(Α.Φ.Μ.) legal_representative_tax_identification_number
f_afm ΑΡΙΘΜΟΣ ΦΟΡΟΛΟΓΙΚΟΥ ΜΗΤΡΩΟΥ (Α.Φ.Μ.) employee_tax_indentification_number
f_amka ΑΡΙΘΜΟΣ ΜΗΤΡΩΟΥ ΚΟΙΝΩΝΙΚΗΣ ΑΣΦΑΛΙΣΗΣ (Α.Μ.Κ.Α.) employee_social_security_number
f_eponymo ΕΠΩΝΥΜΟ employee_last_name
f_onoma ΟΝΟΜΑ employee_first_name
f_date ΗΜΕΡΟΜΗΝΙΑ ΥΠΕΡΩΡΙΑΣ overtime_date
f_from ΩΡΑ ΕΝΑΡΞΗΣ ΥΠΕΡΩΡΙΑΣ (HH24:MM) overtime_start_time
f_to ΩΡΑ ΛΗΞΗΣ ΥΠΕΡΩΡΙΑΣ (HH24:MM) overtime_end_time
f_cancellation ΑΚΥΡΩΣΗ ΥΠΕΡΩΡΙΑΣ overtime_cancellation
f_step ΕΙΔΙΚΟΤΗΤΑ ΚΩΔΙΚΟΣ employee_profession_code
f_reason ΑΙΤΙΟΛΟΓΙΑ ΚΩΔΙΚΟΣ overtime_justification
f_weekdates ΕΒΔΟΜΑΔΙΑΙΑ ΑΠΑΣΧΟΛΗΣΗ (5) ΠΕΝΘΗΜΕΡΟ (6) ΕΞΑΗΜΕΡΟ weekly_workdays_number
f_asee ΕΓΚΡΙΣΗ ΑΣΕΕ asee_approval

Overtime justfications

Original API code Original help text (in Greek) Translation
001 ΠΡΟΛΗΨΗ ΑΤΥΧΗΜΑΤΩΝ Η ΑΠΟΚΑΤΑΣΤΑΣΗ ΖΗΜΙΩΝ ACCIDENT_PREVENTION_OR_DAMAGE_RESTORATION
002 ΕΠΕΙΓΟΥΣΕΣ ΕΡΓΑΣΙΕΣ ΕΠΟΧΙΑΚΟΥ ΧΑΡΑΚΤΗΡΑ URGENT_SEASONAL_TASKS
003 ΕΞΑΙΡΕΤΙΚΗ ΣΩΡΕΥΣΗ ΕΡΓΑΣΙΑΣ – ΦΟΡΤΟΣ ΕΡΓΑΣΙΑΣ EXCEPTIONAL_WORKLOAD
004 ΠΡΟΕΠΙΣΚΕΥΑΣΤΙΚΕΣ Η ΣΥΜΠΛΗΡΩΜΑΤΙΚΕΣ ΕΡΓΑΣΙΕΣ SUPPLEMENTARY_TASKS
005 ΑΝΑΠΛΗΡΩΣΗ ΧΑΜΕΝΩΝ ΩΡΩΝ ΛΟΓΩ ΞΑΦΝΙΚΩΝ ΑΙΤΙΩΝ Η ΑΝΩΤΕΡΑΣ ΒΙΑΣ LOST_HOURS_SUDDEN_CAUSES
006 ΑΝΑΠΛΗΡΩΣΗ ΧΑΜΕΝΩΝ ΩΡΩΝ ΛΟΓΩ ΕΠΙΣΗΜΩΝ ΑΡΓΙΩΝ LOST_HOURS_OFFICIAL_HOLIDAYS
007 ΑΝΑΠΛΗΡΩΣΗ ΧΑΜΕΝΩΝ ΩΡΩΝ ΛΟΓΩ ΚΑΙΡΙΚΩΝ ΣΥΝΘΗΚΩΝ LOST_HOURS_WEATHER_CONDITIONS
008 ΈΚΤΑΚΤΕΣ ΕΡΓΑΣΙΕΣ ΚΛΕΙΣΙΜΑΤΟΣ ΗΜΕΡΑΣ Η ΜΗΝΑ EMERGENCY_CLOSURE_DAY
009 ΛΟΙΠΕΣ ΕΡΓΑΣΙΕΣ ΟΙ ΟΠΟΙΕΣ ΔΕΝ ΜΠΟΡΟΥΝ ΝΑ ΠΡΑΓΜΑΤΟΠΟΙΗΘΟΥΝ ΚΑΤΑ ΤΙΣ ΕΡΓΑΣΙΜΕΣ ΩΡΕΣ NON_WORKDAY_TASKS

Daily schedule

Original Original help text (in Greek) Translated
f_aa_pararthmatos Α/Α ΠΑΡΑΡΤΗΜΑΤΟΣ business_branch_number
f_rel_protocol ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΑΡΙΘ. ΠΡΩΤ. related_protocol_id
f_rel_date ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΗΜΕΡΟΜΗΝΙΑ related_protocol_date
f_comments ΠΑΡΑΤΗΡΗΣΕΙΣ comments
f_from_date ΗΜΕΡΟΜΗΝΙΑ ΑΠΟ start_date
f_to_date ΗΜΕΡΟΜΗΝΙΑ ΕΩΣ end_date
f_afm ΑΡΙΘΜΟΣ ΦΟΡΟΛΟΓΙΚΟΥ ΜΗΤΡΩΟΥ (Α.Φ.Μ.) employee_tax_indentification_number
f_eponymo ΕΠΩΝΥΜΟ employee_last_name
f_onoma ΟΝΟΜΑ employee_first_name
f_day ΗΜΕΡΑ schedule_date
f_type ΤΥΠΟΣ ΑΝΑΛΥΤΙΚΗΣ ΕΓΓΡΑΦΗΣ - ΚΩΔΙΚΟΣ work_type
f_from ΩΡΑ ΑΠΟ (HH24:MM) start_time
f_to ΩΡΑ ΕΩΣ (HH24:MM) end_time

Weekly schedule

Original Original help text (in Greek) Translated
f_aa_pararthmatos Α/Α ΠΑΡΑΡΤΗΜΑΤΟΣ business_brach_number
f_rel_protocol ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΑΡΙΘ. ΠΡΩΤ. related_protocol_id
f_rel_date ΣΧΕΤΙΚΟ ΕΝΤΥΠΟ ΗΜΕΡΟΜΗΝΙΑ related_protocol_date
f_comments ΠΑΡΑΤΗΡΗΣΕΙΣ comments
f_from_date ΗΜΕΡΟΜΗΝΙΑ ΑΠΟ start_date
f_to_date ΗΜΕΡΟΜΗΝΙΑ ΕΩΣ end_date
f_afm ΑΡΙΘΜΟΣ ΦΟΡΟΛΟΓΙΚΟΥ ΜΗΤΡΩΟΥ (Α.Φ.Μ.) employee_tax_indentification_number
f_eponymo ΕΠΩΝΥΜΟ employee_last_name
f_onoma ΟΝΟΜΑ employee_first_name
f_date ΗΜΕΡΟΜΗΝΙΑ schedule_date
f_type ΤΥΠΟΣ ΑΝΑΛΥΤΙΚΗΣ ΕΓΓΡΑΦΗΣ - ΚΩΔΙΚΟΣ work_type
f_from ΩΡΑ ΑΠΟ (HH24:MM) start_time
f_to ΩΡΑ ΕΩΣ (HH24:MM) end_time

Schedule work types

Original API code Original help text (in Greek) Translated
ΜΕ ΜΗ ΕΡΓΑΣΙΑ ABSENT
ΑΝ ΑΝΑΠΑΥΣΗ/ΡΕΠΟ REST_DAY
ΤΗΛ ΤΗΛΕΡΓΑΣΙΑ WORK_FROM_HOME
ΕΡΓ ΕΡΓΑΣΙΑ WORK_FROM_OFFICE

Ports

License

This project is licensed under the MIT License

🦄 Built with LOGIC. 🦄

About

Python SDK for the Greek government Ergani API for employee workflows

ergani.withlogic.dev

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

12 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 2

1.0.1 Latest
Feb 20, 2024
+ 1 release

Contributors 4

  •  
  •  
  •  
  •  

Languages