Ergani Python SDK

ergani.client

class ergani.client.ErganiClient(username: str, password: str, base_url: str | None = 'https://trialeservices.yeka.gr/WebServicesAPI/api')[source]

Bases: object

A client for interacting with the Ergani API

Parameters:
get_employer_details() → EmployerDetails[source]

Fetches employer details from the Ergani API.

Returns:

Employer details parsed from the EX_BASE_01 response.

Return type:

EmployerDetails

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

  • ValueError – Raised if the query payload cannot be parsed into an employer details object

get_services_list() → Response | None[source]

Fetches the available services list from the Ergani API.

Returns:

The raw response returned by the services list endpoint.

Return type:

Optional[Response]

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

submit_daily_schedule(company_daily_schedules: List[CompanyDailySchedule]) → List[SubmissionResponse][source]

Submits schedule records that are updated on a daily basis for employees to the Ergani API

Parameters:

List[CompanyDailySchedule] (company_daily_schedules) – A list of CompanyDailySchedule instances to be submitted

Returns:

A list of SumbmissionResponse that were parsed from the API response

Return type:

List[SubmissionResponse]

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

submit_overtime(company_overtimes: List[CompanyOvertime]) → List[SubmissionResponse][source]

Submits overtime records for employees to the Ergani API

Parameters:

List[CompanyOvertime] (company_overtimes) – A list of CompanyOvertime instances to be submitted

Returns:

A list of SumbmissionResponse that were parsed from the API response

Return type:

List[SubmissionResponse]

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

submit_weekly_schedule(company_weekly_schedules: List[CompanyWeeklySchedule]) → List[SubmissionResponse][source]

Submits weekly schedule records for employees to the Ergani API

Parameters:

List[CompanyWeeklySchedule] (company_weekly_schedules) – A list of CompanyWeeklySchedule instances to be submitted

Returns:

A list of SumbmissionResponse that were parsed from the API response

Return type:

List[SubmissionResponse]

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

submit_work_card(company_work_cards: List[CompanyWorkCard]) → List[SubmissionResponse][source]

Submits work card records (check-in, check-out) for employees to the Ergani API

Parameters:

List[CompanyWorkCard] (company_work_cards) – A list of CompanyWorkCard instances to be submitted

Returns:

A list of SumbmissionResponse that were parsed from the API response

Return type:

List[SubmissionResponse]

Raises:

  • APIError – An error occurred while communicating with the Ergani API

  • AuthenticationError – Raised if there is an authentication error with the Ergani API

ergani.exceptions

exception ergani.exceptions.APIError(message: str | None = None, response: Response | None = None, payload: Dict[str, Any] | None = None)[source]

Bases: Error

Raised when an API request fails due to an unknown error

exception ergani.exceptions.AuthenticationError(message: str | None = None, response: Response | None = None, payload: Dict[str, Any] | None = None)[source]

Bases: Error

Raised when an API request fails due to an authentication error

exception ergani.exceptions.Error(message: str | None = None, response: Response | None = None, payload: Dict[str, Any] | None = None)[source]

Bases: Exception

Base class for all API errors

ergani.models

class ergani.models.CompanyDailySchedule(business_branch_number: int, start_date: ~datetime.date | None = None, end_date: ~datetime.date | None = None, employee_schedules: ~typing.List[~ergani.models.EmployeeDailySchedule] = <factory>, related_protocol_id: str | None = '', related_protocol_date: ~datetime.date | None = None, comments: str | None = '')[source]

Bases: object

Represents daily schedule entries that are issued on a single business branch

business_branch_number

The number identifying the business branch

Type:

int

start_date

The start date of the schedule

Type:

Optional[date]

end_date

The end date of the schedule period

Type:

Optional[date]

employee_schedules

A list of daily schedules for employees

Type:

List[EmployeeDailySchedule]

related_protocol_id

The ID of the related protocol

Type:

Optional[str]

related_protocol_date

The date of the related protocol

Type:

Optional[date]

comments

Additional comments regarding the daily schedule entries

Type:

Optional[str]

class ergani.models.CompanyOvertime(business_branch_number: int, sepe_service_code: str, business_primary_activity_code: str, business_branch_activity_code: str, kallikratis_municipal_code: str, legal_representative_tax_identification_number: str, employee_overtimes: ~typing.List[~ergani.models.Overtime] = <factory>, related_protocol_id: str | None = '', related_protocol_date: ~datetime.date | None = None, employer_organization: str | None = '', business_secondary_activity_code_1: str | None = '', business_secondary_activity_code_2: str | None = '', business_secondary_activity_code_3: str | None = '', business_secondary_activity_code_4: str | None = '', comments: str | None = '')[source]

Bases: object

Represents overtime entries that are issued on a single business branch

business_branch_number

The number identifying the specific business branch

Type:

int

sepe_service_code

The SEPE service code

Type:

str

business_primary_activity_code

The primary activity code of the business

Type:

str

business_branch_activity_code

The activity code for the specific branch

Type:

str

kallikratis_municipal_code

The kallikratis municipal code

Type:

str

legal_representative_tax_identification_number

Tax identification number of the legal representative

Type:

str

employee_overtimes

A list of Overtime entries for employees

Type:

List[Overtime]

related_protocol_id

Related protocol ID

Type:

Optional[str]

related_protocol_date

The date of the related protocol

Type:

Optional[date]

employer_organization

The employer’s organization name

Type:

Optional[str]

business_secondary_activity_code_1

Secondary activity code 1

Type:

Optional[str]

business_secondary_activity_code_2

Secondary activity code 2

Type:

Optional[str]

business_secondary_activity_code_3

Secondary activity code 3

Type:

Optional[str]

business_secondary_activity_code_4

Secondary activity code 4

Type:

Optional[str]

comments

Additional comments related to the overtime entries

Type:

Optional[str]

class ergani.models.CompanyWeeklySchedule(business_branch_number: int, start_date: ~datetime.date, end_date: ~datetime.date, employee_schedules: ~typing.List[~ergani.models.EmployeeWeeklySchedule] = <factory>, related_protocol_id: str | None = '', related_protocol_date: ~datetime.date | None = None, comments: str | None = '')[source]

Bases: object

Represents weekly schedule entries that are issued on a single business branch

business_branch_number

The number identifying the business branch

Type:

int

start_date

The start date of the weekly schedule

Type:

date

end_date

The end date of the weekly schedule

Type:

date

employee_schedules

A list of weekly schedules for employees

Type:

List[EmployeeWeeklySchedule]

related_protocol_id

The ID of the related protocol

Type:

Optional[str]

related_protocol_date

The date of the related protocol

Type:

Optional[date]

comments

Additional comments regarding the weekly schedule entries

Type:

Optional[str]

class ergani.models.CompanyWorkCard(employer_tax_identification_number: str, business_branch_number: int, comments: str | None = '', card_details: ~typing.List[~ergani.models.WorkCard] = <factory>)[source]

Bases: object

Represents work card entries that are issued on a single business branch

employer_tax_identification_number

The employer’s tax identification number

Type:

str

business_branch_number

The number identifying the specific business branch

Type:

int

comments

Additional comments related to the work cards

Type:

Optional[str]

card_details

A list of WorkCard entries for the business branch

Type:

List[WorkCard]

class ergani.models.EmployeeDailySchedule(employee_tax_identification_number: str, employee_last_name: str, employee_first_name: str, schedule_date: ~datetime.date, workday_details: ~typing.List[~ergani.models.WorkdayDetails] = <factory>)[source]

Bases: object

Represents a daily schedule entry for an employee

employee_tax_identification_number

The employee’s tax identification number

Type:

str

employee_last_name

The employee’s last name

Type:

str

employee_first_name

The employee’s first name

Type:

str

schedule_date

The date of the schedule

Type:

date

workday_details

A list of workday detail entries for the employee

Type:

List[WorkdayDetails]

class ergani.models.EmployeeWeeklySchedule(employee_tax_identification_number: str, employee_last_name: str, employee_first_name: str, schedule_date: ~datetime.date, workday_details: ~typing.List[~ergani.models.WorkdayDetails] = <factory>)[source]

Bases: object

Represents a weekly schedule entry for an employee

employee_tax_identification_number

The employee’s tax identification number

Type:

str

employee_last_name

The employee’s last name

Type:

str

employee_first_name

The employee’s first name

Type:

str

schedule_date

The date of the schedule

Type:

date

workday_details

A list of workday detail entries for the week

Type:

List[WorkdayDetails]

class ergani.models.EmployerDetails(employer_id: 'int | None' = None, employer_tax_identification_number: 'str | None' = None, name: 'str | None' = None, distinctive_title: 'str | None' = None, employer_registry_number: 'str | None' = None, is_in_card_sector: 'bool | None' = None, raw_payload: 'Dict[str, Any]' = <factory>)[source]

Bases: object

class ergani.models.Overtime(employee_tax_identification_number: str, employee_social_security_number: str, employee_last_name: str, employee_first_name: str, overtime_date: date, overtime_start_time: time, overtime_end_time: time, overtime_cancellation: bool, employee_profession_code: str, overtime_justification: Literal['ACCIDENT_PREVENTION_OR_DAMAGE_RESTORATION', 'URGENT_SEASONAL_TASKS', 'EXCEPTIONAL_WORKLOAD', 'SUPPLEMENTARY_TASKS', 'LOST_HOURS_SUDDEN_CAUSES', 'LOST_HOURS_OFFICIAL_HOLIDAYS', 'LOST_HOURS_WEATHER_CONDITIONS', 'EMERGENCY_CLOSURE_DAY', 'NON_WORKDAY_TASKS'], weekly_workdays_number: Literal[5, 6], asee_approval: str | None = '')[source]

Bases: object

Represents an overtime entry for an employee

employee_tax_identification_number

The employee’s tax identification number

Type:

str

employee_social_security_number

The employee’s social security number

Type:

str

employee_last_name

The last name of the employee

Type:

str

employee_first_name

The first name of the employee

Type:

str

overtime_date

The date of the overtime

Type:

date

overtime_start_time

The start time of the overtime period

Type:

time

overtime_end_time

The end time of the overtime period

Type:

time

overtime_cancellation

Indicates if the overtime was cancelled or not

Type:

bool

employee_profession_code

The profession code of the employee

Type:

str

overtime_justification

The justification for the overtime

Type:

OvertimeJustificationType

weekly_workdays_number

The number of the employee’s working days in a week

Type:

Literal[5, 6]

asee_approval

The ASEE aproval

Type:

Optional[str]

class ergani.models.SubmissionResponse[source]

Bases: TypedDict

Represents a submission response from the Ergani API

submission_id

The unique identifier of the submission

Type:

str

protocol

The protocol associated with the submission

Type:

str

submission_date

The datetime of the submission

Type:

datetime

class ergani.models.WorkCard(employee_tax_identification_number: str, employee_last_name: str, employee_first_name: str, work_card_movement_type: Literal['ARRIVAL', 'DEPARTURE'], work_card_submission_date: date, work_card_movement_datetime: datetime, late_declaration_justification: Literal['POWER_OUTAGE', 'EMPLOYER_SYSTEMS_UNAVAILABLE', 'ERGANI_SYSTEMS_UNAVAILABLE'] | None = None)[source]

Bases: object

Represents a work card entry for an employee

employee_tax_identification_number

The employee’s tax identification number

Type:

str

employee_last_name

The last name of the employee

Type:

str

employee_first_name

The first name of the employee

Type:

str

work_card_movement_type

The type of work card movement

Type:

WorkCardMovementType

work_card_submission_date

The date the work card was submitted

Type:

date

work_card_movement_datetime

The exact date and time of the work card movement

Type:

datetime

late_declaration_justification

The justification for the late declaration of the work card movement

Type:

Optional[LateDeclarationJustificationType]

class ergani.models.WorkdayDetails(work_type: Literal['WORK_FROM_OFFICE', 'WORK_FROM_HOME', 'REST_DAY', 'ABSENT'], start_time: time, end_time: time)[source]

Bases: object

Represents details of an employee’s workday

work_type

The type of an employee’s work schedule

Type:

ScheduleWorkType

start_time

The start time of the workday

Type:

time

end_time

The end time of the workday

Type:

time

Indices and tables