brynq-sdk-sage-germany 1.0.0__py3-none-any.whl

brynq_sdk_sage_germany/schemas/salaries.py

@@ -0,0 +1,101 @@
+"""
+Schemas for Sage Germany salary payloads.
+"""
+
+from typing import Optional, Union
+
+import pandas as pd
+import pandera as pa
+from pandera.typing import Series
+from pydantic import BaseModel, Field, ConfigDict
+
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+
+class SalaryGet(BrynQPanderaDataFrameModel):
+    """
+    Pandera schema for employee salary records.
+    """
+
+    # Base identifiers
+    key_date: Series[pd.StringDtype] = pa.Field(alias="Key__Date", coerce=True, nullable=False, description="Snapshot timestamp.")
+    company_id: Series[pd.Int64Dtype] = pa.Field(alias="Key__MdNr", coerce=True, nullable=False, description="Company id.")
+    employee_number: Series[pd.Int64Dtype] = pa.Field(alias="Key__AnNr", coerce=True, nullable=False, description="Employee number.")
+    combined_key: Series[pd.StringDtype] = pa.Field(alias="Key__CombinedKey", coerce=True, nullable=False, description="Combined tenant/employee key.")
+    key_is_empty: Optional[Series[bool]] = pa.Field(alias="Key__IsEmpty", coerce=True, nullable=True, description="Indicates empty key payload.")
+
+    # Salary configuration flags
+    transfer_fixed_allowances: Optional[Series[bool]] = pa.Field(alias="FesteBezuegeUebernehmen", coerce=True, nullable=True, description="Transfer fixed allowances flag.")
+    collective_bargain_table: Optional[Series[bool]] = pa.Field(alias="Tariftabelle", coerce=True, nullable=True, description="Collective bargain table flag.")
+
+    # Agreed salary
+    agreed_salary_amount: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Gehalt", coerce=True, nullable=True, description="Agreed salary amount.")
+    allowance_one_is_percentage: Optional[Series[bool]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage1Prozentual", coerce=True, nullable=True, description="Allowance 1 percentage flag.")
+    allowance_two_is_percentage: Optional[Series[bool]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage2Prozentual", coerce=True, nullable=True, description="Allowance 2 percentage flag.")
+    allowance_three_is_percentage: Optional[Series[bool]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage3Prozentual", coerce=True, nullable=True, description="Allowance 3 percentage flag.")
+    allowance_one_amount: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage1Betrag", coerce=True, nullable=True, description="Allowance 1 amount.")
+    allowance_two_amount: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage2Betrag", coerce=True, nullable=True, description="Allowance 2 amount.")
+    allowance_three_amount: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage3Betrag", coerce=True, nullable=True, description="Allowance 3 amount.")
+    allowance_one_percentage: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage1Prozent", coerce=True, nullable=True, description="Allowance 1 percentage.")
+    allowance_two_percentage: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage2Prozent", coerce=True, nullable=True, description="Allowance 2 percentage.")
+    allowance_three_percentage: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbartesEntgelt__Zulagen__Zulage3Prozent", coerce=True, nullable=True, description="Allowance 3 percentage.")
+
+    # Hourly rates
+    hourly_rate_1: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz1", coerce=True, nullable=True, description="Hourly rate 1.")
+    hourly_rate_2: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz2", coerce=True, nullable=True, description="Hourly rate 2.")
+    hourly_rate_3: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz3", coerce=True, nullable=True, description="Hourly rate 3.")
+    hourly_rate_4: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz4", coerce=True, nullable=True, description="Hourly rate 4.")
+    hourly_rate_5: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz5", coerce=True, nullable=True, description="Hourly rate 5.")
+    hourly_rate_6: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz6", coerce=True, nullable=True, description="Hourly rate 6.")
+    hourly_rate_7: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz7", coerce=True, nullable=True, description="Hourly rate 7.")
+    hourly_rate_8: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz8", coerce=True, nullable=True, description="Hourly rate 8.")
+    hourly_rate_9: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz9", coerce=True, nullable=True, description="Hourly rate 9.")
+    hourly_rate_10: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="VereinbarteStundenloehne__Stundensatz10", coerce=True, nullable=True, description="Hourly rate 10.")
+
+    # Night/Sunday/Holiday allowances
+    automatic_base_wage_calculation: Optional[Series[bool]] = pa.Field(alias="SonnFeiertagNachtZuschlaege__AutomatischeGrundlohnermittlung", coerce=True, nullable=True, description="Automatic base wage calculation flag.")
+    base_hourly_wage: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="SonnFeiertagNachtZuschlaege__Grundstundenlohn", coerce=True, nullable=True, description="Base hourly wage.")
+
+    # Advance payments
+    automatic_advance_payment: Optional[Series[bool]] = pa.Field(alias="Abschlagszahlung__AutomatischerAbschlag", coerce=True, nullable=True, description="Automatic advance flag.")
+    advance_payment_amount: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Abschlagszahlung__Abschlag", coerce=True, nullable=True, description="Advance payment amount.")
+
+    # Overtime / absence config
+    overtime_calculation_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="UeberstundenFehlstunden__Berechnungsart__Id", coerce=True, nullable=True, description="Overtime calculation identifier.")
+    overtime_calculation_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__Berechnungsart__Text", coerce=True, nullable=True, description="Overtime calculation text.")
+    overtime_calculation_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__Berechnungsart__IdMitText", coerce=True, nullable=True, description="Overtime calculation id-text.")
+    overtime_payroll_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__LohnartUeberstunden", coerce=True, nullable=True, description="Overtime payroll code.")
+    absence_payroll_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__LohnartFehlstunden", coerce=True, nullable=True, description="Absence payroll code.")
+    employer_prepayment_payroll_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__LohnartFehlstundenArbeitgeberVorausleistung", coerce=True, nullable=True, description="Employer prepayment payroll code.")
+    additional_overtime_threshold: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="UeberstundenFehlstunden__ZusaetzlicheUeberstundenAb", coerce=True, nullable=True, description="Additional overtime threshold.")
+    additional_overtime_payroll_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__LohnartZusaetzlicheUeberstunden", coerce=True, nullable=True, description="Additional overtime payroll code.")
+    unpaid_absence_threshold: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="UeberstundenFehlstunden__UnbezahlteFehlstundenAb", coerce=True, nullable=True, description="Unpaid absence threshold.")
+    unpaid_absence_payroll_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="UeberstundenFehlstunden__LohnartUnbezahlteFehlstunden", coerce=True, nullable=True, description="Unpaid absence payroll code.")
+
+    class _Annotation:
+        primary_key = "combined_key"
+
+    class Config:
+        coerce = True
+        strict = "filter"
+
+
+class SalaryImport(BaseModel):
+    """
+    Pydantic schema for gross salary (Bruttolohn) import payloads.
+    """
+
+    company_id: Union[int, str] = Field(alias="Mdnr", description="Company id (Mandant).", example=1)
+    employee_number: Union[int, str] = Field(alias="Annr", description="Employee number.", example=100)
+    year: Union[int, str] = Field(alias="AbrJahr", description="Payroll year.", example=2024)
+    month: Union[int, str] = Field(alias="AbrMon", description="Payroll month.", example=1)
+    day: Union[int, str] = Field(alias="Tag", description="Day of month.", example=15)
+    wage_type: Union[int, str] = Field(alias="Lanr", description="Wage type number.", example=1000)
+    quantity: Optional[Union[int, float, str]] = Field(default=None, alias="Anzahl", description="Quantity value.", example=8.0)
+    amount: Optional[Union[int, float, str]] = Field(default=None, alias="Betrag", description="Amount value.", example=150.00)
+    cost_center: Optional[Union[int, str]] = Field(default=None, alias="KoSt1", description="Cost center.", example="CC001")
+    cost_unit: Optional[Union[int, str]] = Field(default=None, alias="KoTr1", description="Cost unit.", example="CU001")
+    aa1: Optional[Union[int, str]] = Field(default=None, alias="AA1", description="Additional classification field.", example="A1")
+    surcharge: Optional[Union[int, float, str]] = Field(default=None, alias="Zuschlag", description="Surcharge value.", example=25.00)
+
+    model_config = ConfigDict(populate_by_name=True)

brynq_sdk_sage_germany/schemas/start_end_dates.py

@@ -0,0 +1,194 @@
+"""
+Schemas for Sage Germany employment period payloads.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+import pandas as pd
+import pandera as pa
+from pandera.typing import Series
+from pydantic import BaseModel, ConfigDict, Field
+
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+__all__ = [
+    "StartEndDatesGet",
+    "StartEndDatesKey",
+    "StartEndDatesInterval",
+    "StartEndDatesEntryExit",
+    "StartEndDatesCreate",
+]
+
+
+class StartEndDatesKey(BaseModel):
+    """
+    Employee key used by employment period endpoints.
+    """
+
+    company_id: int = Field(alias="MdNr", description="Company id (Mandant).", example=1)
+    employee_number: int = Field(alias="AnNr", description="Employee number.", example=210)
+    combined_key: Optional[str] = Field(
+        default=None,
+        alias="CombinedKey",
+        description="Optional combined key value.",
+        example="1_210",
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class StartEndDatesInterval(BaseModel):
+    """
+    Generic Id/Text object used for probation interval, contract limits, and reasons.
+    """
+
+    id: Optional[int] = Field(default=None, alias="Id", description="Identifier value.", example=1)
+    text: Optional[str] = Field(default=None, alias="Text", description="Display text value.", example="Monthly")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class StartEndDatesEntryExit(BaseModel):
+    """
+    Single entry/exit record within the employment period payload.
+    """
+
+    key: StartEndDatesKey = Field(
+        alias="Key",
+        description="Employee key for the entry/exit item.",
+    )
+    id: Optional[int] = Field(default=None, alias="Id", description="Entry/exit identifier.", example=1)
+    entry: datetime = Field(alias="Eintritt", description="Employment start date.", example="2024-01-01T00:00:00")
+    exit: Optional[datetime] = Field(default=None, alias="Austritt", description="Employment end date.", example="2024-12-31T00:00:00")
+    limited: Optional[StartEndDatesInterval] = Field(
+        default=None,
+        alias="Befristet",
+        description="Limited contract metadata.",
+        json_schema_extra={"prefix": "entry_exit_limited_"},
+    )
+    exit_reason: Optional[StartEndDatesInterval] = Field(
+        default=None,
+        alias="AustrittGrund",
+        description="Exit reason metadata.",
+        json_schema_extra={"prefix": "entry_exit_exit_reason_"},
+    )
+    exit_custom_reason: Optional[StartEndDatesInterval] = Field(
+        default=None,
+        alias="AustrittBenutzerdefinierterGrund",
+        description="Custom exit reason metadata.",
+        json_schema_extra={"prefix": "entry_exit_exit_custom_reason_"},
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class StartEndDatesCreate(BaseModel):
+    """
+    Pydantic schema for POST /employeenew/person/beschaeftigungszeiten.
+    Accepts nested structure; helper converts flat prefixed keys to this shape.
+    """
+
+    key: StartEndDatesKey = Field(
+        alias="Key",
+        description="Employee key for the employment period record.",
+        json_schema_extra={"prefix": "key_"},
+    )
+    corporate_entry: Optional[datetime] = Field(
+        default=None,
+        alias="KonzernEintritt",
+        description="Corporate entry date.",
+        example="2024-01-01T00:00:00",
+    )
+    probation_number: Optional[int] = Field(
+        default=None,
+        alias="ProbezeitZahl",
+        description="Probation duration number.",
+        example=6,
+    )
+    probation_interval: Optional[StartEndDatesInterval] = Field(
+        default=None,
+        alias="ProbezeitIntervall",
+        description="Probation interval metadata.",
+        json_schema_extra={"prefix": "probation_interval_"},
+    )
+    probation_end: Optional[datetime] = Field(
+        default=None,
+        alias="Probezeit",
+        description="Probation end date.",
+        example="2024-07-01T00:00:00",
+    )
+    entry_exit_periods: Optional[List[StartEndDatesEntryExit]] = Field(
+        default=None,
+        alias="EinAustritte",
+        description="List of entry/exit records.",
+        example=[],
+        json_schema_extra={"prefix": "entry_exit_"},
+    )
+    service_time: Optional[datetime] = Field(
+        default=None,
+        alias="Dienstzeit",
+        description="Service time date.",
+        example="2024-01-01T00:00:00",
+    )
+    service_time_duration: Optional[str] = Field(
+        default=None,
+        alias="DienstzeitDauer",
+        description="Service time duration string.",
+        example="1 year",
+    )
+    employment_time: Optional[datetime] = Field(
+        default=None,
+        alias="Beschaeftigungszeit",
+        description="Employment time date.",
+        example="2024-01-01T00:00:00",
+    )
+    employment_time_duration: Optional[str] = Field(
+        default=None,
+        alias="BeschaeftigungszeitDauer",
+        description="Employment time duration string.",
+        example="1 year",
+    )
+    allowance_claim: Optional[StartEndDatesInterval] = Field(
+        default=None,
+        alias="AnspruchZuwendung",
+        description="Allowance claim metadata.",
+        json_schema_extra={"prefix": "allowance_claim_"},
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class StartEndDatesGet(BrynQPanderaDataFrameModel):
+    """
+    Pandera schema for employee start/end date records.
+    """
+
+    # Base identifiers
+    company_id: Series[pd.Int64Dtype] = pa.Field(alias="Key__MdNr", coerce=True, nullable=False, description="Company id.")
+    employee_number: Series[pd.Int64Dtype] = pa.Field(alias="Key__AnNr", coerce=True, nullable=False, description="Employee number.")
+    combined_key: Series[pd.StringDtype] = pa.Field(alias="Key__CombinedKey", coerce=True, nullable=False, description="Combined key.")
+    key_is_empty: Optional[Series[bool]] = pa.Field(alias="Key__IsEmpty", coerce=True, nullable=True, description="Key empty flag.")
+
+    # Employment metadata
+    corporate_entry: Optional[Series[pd.StringDtype]] = pa.Field(alias="KonzernEintritt", coerce=True, nullable=True, description="Corporate entry date.")
+    probation_number: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="ProbezeitZahl", coerce=True, nullable=True, description="Probation duration number.")
+    probation_interval: Optional[Series[pd.StringDtype]] = pa.Field(alias="ProbezeitIntervall", coerce=True, nullable=True, description="Probation interval.")
+    probation_end: Optional[Series[pd.StringDtype]] = pa.Field(alias="Probezeit", coerce=True, nullable=True, description="Probation end date.")
+
+    # Aggregated durations
+    service_time: Optional[Series[pd.StringDtype]] = pa.Field(alias="Dienstzeit", coerce=True, nullable=True, description="Service time string.")
+    service_time_duration: Optional[Series[pd.StringDtype]] = pa.Field(alias="DienstzeitDauer", coerce=True, nullable=True, description="Service time duration.")
+    employment_time: Optional[Series[pd.StringDtype]] = pa.Field(alias="Beschaeftigungszeit", coerce=True, nullable=True, description="Employment time string.")
+    employment_time_duration: Optional[Series[pd.StringDtype]] = pa.Field(alias="BeschaeftigungszeitDauer", coerce=True, nullable=True, description="Employment time duration.")
+    allowance_claim: Optional[Series[pd.StringDtype]] = pa.Field(alias="AnspruchZuwendung", coerce=True, nullable=True, description="Allowance claim info.")
+
+    # Entry/exit payload
+    entry_exit_payload: Optional[Series[pd.StringDtype]] = pa.Field(alias="EinAustritte", coerce=True, nullable=True, description="Entry/exit history payload.")
+
+    class _Annotation:
+        primary_key = "combined_key"
+
+    class Config:
+        coerce = True
+        strict = "filter"

brynq_sdk_sage_germany/schemas/vacation_account.py

@@ -0,0 +1,117 @@
+"""
+Schemas for Sage Germany vacation account (Urlaubskonto) payloads.
+"""
+
+from typing import Optional
+
+import pandas as pd
+import pandera as pa
+from pandera.typing import Series
+
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+
+class VacationAccountGet(BrynQPanderaDataFrameModel):
+    """
+    Pandera schema for employee vacation account balances.
+    """
+
+    # Base identifiers
+    key_date: Series[pd.StringDtype] = pa.Field(alias="Key__Date", coerce=True, nullable=False, description="Snapshot date.")
+    company_id: Series[pd.Int64Dtype] = pa.Field(alias="Key__MdNr", coerce=True, nullable=False, description="Company id.")
+    employee_number: Series[pd.Int64Dtype] = pa.Field(alias="Key__AnNr", coerce=True, nullable=False, description="Employee number.")
+    combined_key: Series[pd.StringDtype] = pa.Field(alias="Key__CombinedKey", coerce=True, nullable=False, description="Combined key.")
+    key_is_empty: Optional[Series[bool]] = pa.Field(alias="Key__IsEmpty", coerce=True, nullable=True, description="Key empty flag.")
+
+    # Vacation table metadata
+    vacation_table_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Urlaubstabelle__Id", coerce=True, nullable=True, description="Vacation table id.")
+    vacation_table_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Urlaubstabelle__Text", coerce=True, nullable=True, description="Vacation table text.")
+    vacation_table_label: Optional[Series[pd.StringDtype]] = pa.Field(alias="Urlaubstabelle__IdMitText", coerce=True, nullable=True, description="Vacation table label.")
+    is_previous_calendar_year: Optional[Series[bool]] = pa.Field(alias="VergangenesKalenderjahr", coerce=True, nullable=True, description="Indicates previous calendar year view.")
+
+    # Employee info
+    data_company_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Daten__EmployeeKey__MdNr", coerce=True, nullable=True, description="Data company id.")
+    data_employee_number: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Daten__EmployeeKey__AnNr", coerce=True, nullable=True, description="Data employee number.")
+    data_combined_key: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__EmployeeKey__CombinedKey", coerce=True, nullable=True, description="Data combined key.")
+    employee_first_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__EmployeeName__Firstname", coerce=True, nullable=True, description="Employee first name.")
+    employee_last_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__EmployeeName__Lastname", coerce=True, nullable=True, description="Employee last name.")
+    employee_full_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__EmployeeName__Fullname", coerce=True, nullable=True, description="Employee full name.")
+    unit: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__Unit", coerce=True, nullable=True, description="Unit label.")
+
+    # Annual entitlements and usage
+    entitlement_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchKJ", coerce=True, nullable=True, description="Current year entitlement.")
+    entitlement_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchVJ", coerce=True, nullable=True, description="Previous year entitlement.")
+    entitlement_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchGesamt", coerce=True, nullable=True, description="Total entitlement.")
+    taken_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenKJ", coerce=True, nullable=True, description="Taken days current year.")
+    taken_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenVJ", coerce=True, nullable=True, description="Taken days previous year.")
+    taken_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenGesamt", coerce=True, nullable=True, description="Taken days total.")
+    rest_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestKJ", coerce=True, nullable=True, description="Remaining current year.")
+    rest_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestVJ", coerce=True, nullable=True, description="Remaining previous year.")
+    rest_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestGesamt", coerce=True, nullable=True, description="Remaining total.")
+    rest_total_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestGesamtVJ", coerce=True, nullable=True, description="Remaining total previous year.")
+    rest_total_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestGesamtKJ", coerce=True, nullable=True, description="Remaining total current year.")
+
+    entitlement_base_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchGrundKJ", coerce=True, nullable=True, description="Base entitlement current year.")
+    entitlement_carried_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchVortragVJ", coerce=True, nullable=True, description="Carried over previous year.")
+    entitlement_carried_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchVortragKJ", coerce=True, nullable=True, description="Carried over current year.")
+
+    # Additional/special leave
+    entitlement_additional_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchZusatzKJ", coerce=True, nullable=True, description="Additional leave current year.")
+    entitlement_additional_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchZusatzVJ", coerce=True, nullable=True, description="Additional leave previous year.")
+    entitlement_additional_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchZusatzGesamt", coerce=True, nullable=True, description="Additional leave total.")
+    entitlement_additional_raw: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchZusatzKJohneKorrektur", coerce=True, nullable=True, description="Additional leave raw current year.")
+    entitlement_special_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AnspruchSonderUrlTgKJ", coerce=True, nullable=True, description="Special leave entitlement current year.")
+
+    taken_additional_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenZusatzKJ", coerce=True, nullable=True, description="Additional leave taken current year.")
+    taken_additional_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenZusatzVJ", coerce=True, nullable=True, description="Additional leave taken previous year.")
+    taken_additional_total_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenZusatzGesamtVJ", coerce=True, nullable=True, description="Additional leave taken total previous year.")
+    taken_additional_total_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenZusatzGesamtKJ", coerce=True, nullable=True, description="Additional leave taken total current year.")
+    taken_without_entitlement: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__GenommenOhneAnspruch", coerce=True, nullable=True, description="Leave taken without entitlement.")
+
+    rest_additional_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestZusatzKJ", coerce=True, nullable=True, description="Additional leave remaining current year.")
+    rest_additional_total_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestZusatzGesamtVJ", coerce=True, nullable=True, description="Additional leave remaining total previous year.")
+    rest_special_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestSonderurlaubKJ", coerce=True, nullable=True, description="Special leave remaining current year.")
+
+    # Expiration / compensation
+    expiration_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallKJ", coerce=True, nullable=True, description="Expiration current year.")
+    expiration_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallVJ", coerce=True, nullable=True, description="Expiration previous year.")
+    expiration_additional_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallZusatzKJ", coerce=True, nullable=True, description="Additional expiration current year.")
+    expiration_additional_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallZusatzVJ", coerce=True, nullable=True, description="Additional expiration previous year.")
+    expiration_disability_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallSchwerbehinderungKJ", coerce=True, nullable=True, description="Disability expiration current year.")
+    compensation_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AbgeltKJ", coerce=True, nullable=True, description="Compensation current year.")
+    compensation_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AbgeltVJ", coerce=True, nullable=True, description="Compensation previous year.")
+    compensation_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AbgeltGesamt", coerce=True, nullable=True, description="Compensation total.")
+    expiration_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__VerfallGesamt", coerce=True, nullable=True, description="Expiration total.")
+    compensation_expiration_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__AbgeltVerfallGesamt", coerce=True, nullable=True, description="Compensation + expiration total.")
+    rest_total_incl_expiration: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestGesamtInklVerfall", coerce=True, nullable=True, description="Remaining total including expiration.")
+    rest_total_incl_planned: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestInklGeplant", coerce=True, nullable=True, description="Remaining including planned.")
+
+    # Planning and info
+    planned_leave_total: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__UrlaubGeplantGesamt", coerce=True, nullable=True, description="Planned leave total.")
+    planned_leave_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__UrlaubBeantragtKJ", coerce=True, nullable=True, description="Planned leave current year.")
+    recorded_leave_current_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__UrlaubErfasstKJ", coerce=True, nullable=True, description="Recorded leave current year.")
+    rest_leave_requested_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestUrlaubBeantragtVJ", coerce=True, nullable=True, description="Remaining leave requested previous year.")
+    rest_leave_recorded_previous_year: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Daten__RestUrlaubErfasstVJ", coerce=True, nullable=True, description="Remaining leave recorded previous year.")
+    expiration_date: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__UrlaubsVerfallsDatum", coerce=True, nullable=True, description="Leave expiration date.")
+    vacation_table_id_value: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Daten__UrlTabId", coerce=True, nullable=True, description="Vacation table id reference.")
+    vacation_table_name_value: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__UrlTabName", coerce=True, nullable=True, description="Vacation table name reference.")
+    keep_rest_current_year: Optional[Series[bool]] = pa.Field(alias="Daten__ResturlaubNichtBehaltenAktuellesJahr", coerce=True, nullable=True, description="Rest leave not retained current year.")
+    keep_rest_next_year: Optional[Series[bool]] = pa.Field(alias="Daten__ResturlaubNichtBehaltenFolgejahr", coerce=True, nullable=True, description="Rest leave not retained next year.")
+    expires_in_previous_year: Optional[Series[bool]] = pa.Field(alias="Daten__VerfaelltImVorjahr", coerce=True, nullable=True, description="Expires in previous year flag.")
+    rest_previous_year_auto: Optional[Series[bool]] = pa.Field(alias="Daten__RestVJAutomatischErmittelt", coerce=True, nullable=True, description="Rest previous year auto calculated.")
+    reference_year: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Daten__Year", coerce=True, nullable=True, description="Reference year.")
+    info_disability: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__InfoSchwerbehinderung", coerce=True, nullable=True, description="Disability info.")
+    info_base_entitlement: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__InfoGrundanspruch", coerce=True, nullable=True, description="Base entitlement info.")
+    info_additional_leave: Optional[Series[pd.StringDtype]] = pa.Field(alias="Daten__InfoZusatzurlaub", coerce=True, nullable=True, description="Additional leave info.")
+    recalculation_status: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Daten__Neuberechnungsstatus", coerce=True, nullable=True, description="Recalculation status.")
+
+    # Flags
+    has_vacation_table: Optional[Series[bool]] = pa.Field(alias="HatUrlaubstabelle", coerce=True, nullable=True, description="Has vacation table flag.")
+    has_disability_additional_leave: Optional[Series[bool]] = pa.Field(alias="HatZusatzurlaubSchwerbehinderung", coerce=True, nullable=True, description="Has disability additional leave.")
+
+    class _Annotation:
+        primary_key = "combined_key"
+
+    class Config:
+        coerce = True
+        strict = "filter"

brynq_sdk_sage_germany/schemas/work_hours.py

@@ -0,0 +1,94 @@
+"""
+Schemas for Sage Germany work hours payloads.
+"""
+
+from typing import Optional
+
+import pandas as pd
+import pandera as pa
+from pandera.typing import Series
+from pydantic import BaseModel, ConfigDict, Field
+
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+__all__ = ["WorkHoursGet", "WorkHoursCreate"]
+
+
+class WorkHoursCreate(BaseModel):
+    """
+    Pydantic schema for POST /employeenew/person/arbeitszeiten.
+    """
+
+    company_id: int = Field(alias="MdNr", description="Company id (Mandant).", example=1)
+    employee_number: int = Field(alias="AnNr", description="Employee number.", example=100)
+    valid_from: str = Field(alias="ValidFrom", description="Validity start date ISO-8601.", example="2024-01-01T00:00:00")
+
+    work_schedule_label: Optional[str] = Field(default=None, alias="AnAzTab", description="Work schedule label.", example="STANDARD")
+    monthly_hours: Optional[float] = Field(default=None, alias="AnAzMon", description="Monthly hours.", example=160.0)
+    weekly_hours_average: Optional[float] = Field(default=None, alias="AnAzWoDuchschnitt", description="Average weekly hours.", example=40.0)
+    has_deviation_from_base: Optional[bool] = Field(
+        default=None, alias="AbweichendeBasisWochenStunden", description="Deviation from base weekly hours flag.", example=False
+    )
+    base_weekly_hours: Optional[float] = Field(default=None, alias="BasisWochenStunden", description="Base weekly hours.", example=40.0)
+    days_per_week: Optional[float] = Field(default=None, alias="TageProWoche", description="Days per week.", example=5.0)
+    is_industrial: Optional[bool] = Field(default=None, alias="IstGewerblich", description="Industrial employee flag.", example=False)
+
+    work_schedule_table_id: Optional[int] = Field(default=None, alias="Arbeitszeittabelle.Id", description="Schedule table id.", example=1)
+    work_schedule_table_text: Optional[str] = Field(default=None, alias="Arbeitszeittabelle.Text", description="Schedule table text.", example="Standard Schedule")
+    work_schedule_table_weeks: Optional[int] = Field(
+        default=None, alias="Arbeitszeittabelle.AnzahlWochen", description="Schedule table week count.", example=1
+    )
+    work_schedule_table_valid_from: Optional[str] = Field(
+        default=None, alias="ArbeitszeittabelleGueltigAb", description="Schedule table valid-from date.", example="2024-01-01"
+    )
+
+    part_time_factor: Optional[float] = Field(default=None, alias="Teilzeitfaktor", description="Part-time factor.", example=1.0)
+    change_reason_id: Optional[int] = Field(default=None, alias="AenderungsGrund.Id", description="Change reason id.", example=1)
+    change_reason_text: Optional[str] = Field(default=None, alias="AenderungsGrund.Text", description="Change reason text.", example="Initial Setup")
+    work_time_changed: Optional[bool] = Field(default=None, alias="ArbeitszeitHatSichGeaendert", description="Work time changed flag.", example=False)
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class WorkHoursGet(BrynQPanderaDataFrameModel):
+    """
+    Pandera schema for employee work hours (Arbeitszeiten) data.
+    """
+
+    company_id: Series[pd.Int64Dtype] = pa.Field(alias="MdNr", coerce=True, nullable=False, description="Company id.")
+    employee_number: Series[pd.Int64Dtype] = pa.Field(alias="AnNr", coerce=True, nullable=False, description="Employee number.")
+    combined_key: Series[pd.StringDtype] = pa.Field(alias="combined_key", coerce=True, nullable=False, description="Synthetic MdNr_AnNr combined key.")
+    valid_from: Optional[Series[pd.StringDtype]] = pa.Field(alias="ValidFrom", coerce=True, nullable=True, description="Validity start date.")
+    work_schedule_label: Optional[Series[pd.StringDtype]] = pa.Field(alias="AnAzTab", coerce=True, nullable=True, description="Work schedule label.")
+    monthly_hours: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="AnAzMon", coerce=True, nullable=True, description="Monthly hours.")
+    weekly_hours_average: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="AnAzWoDuchschnitt", coerce=True, nullable=True, description="Average weekly hours.")
+    has_deviation_from_base: Optional[Series[bool]] = pa.Field(alias="AbweichendeBasisWochenStunden", coerce=True, nullable=True, description="Deviation from base weekly hours flag.")
+    base_weekly_hours: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="BasisWochenStunden", coerce=True, nullable=True, description="Base weekly hours.")
+    days_per_week: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="TageProWoche", coerce=True, nullable=True, description="Days per week.")
+    is_industrial: Optional[Series[bool]] = pa.Field(alias="IstGewerblich", coerce=True, nullable=True, description="Industrial employee flag.")
+
+    work_schedule_table_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Arbeitszeittabelle__Id", coerce=True, nullable=True, description="Work schedule table id.")
+    work_schedule_table_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Arbeitszeittabelle__Text", coerce=True, nullable=True, description="Work schedule table text.")
+    work_schedule_table_weeks: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Arbeitszeittabelle__AnzahlWochen", coerce=True, nullable=True, description="Work schedule table week count.")
+    work_schedule_table_valid_from: Optional[Series[pd.StringDtype]] = pa.Field(alias="ArbeitszeittabelleGueltigAb", coerce=True, nullable=True, description="Work schedule table valid-from date.")
+
+    part_time_factor: Optional[Series[pd.Float64Dtype]] = pa.Field(alias="Teilzeitfaktor", coerce=True, nullable=True, description="Part-time factor.")
+    change_reason_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="AenderungsGrund__Id", coerce=True, nullable=True, description="Change reason id.")
+    change_reason_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="AenderungsGrund__Text", coerce=True, nullable=True, description="Change reason text.")
+    change_reason_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="AenderungsGrund__IdMitText", coerce=True, nullable=True, description="Change reason id-text.")
+    work_time_changed: Optional[Series[bool]] = pa.Field(alias="ArbeitszeitHatSichGeaendert", coerce=True, nullable=True, description="Work time changed flag.")
+
+    calendar_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Kalender__Id", coerce=True, nullable=True, description="Calendar id.")
+    calendar_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Kalender__Text", coerce=True, nullable=True, description="Calendar text.")
+    calendar_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Kalender__IdMitText", coerce=True, nullable=True, description="Calendar id-text.")
+    tenant_calendar_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Mandantenkalender__Id", coerce=True, nullable=True, description="Tenant calendar id.")
+    tenant_calendar_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Mandantenkalender__Text", coerce=True, nullable=True, description="Tenant calendar text.")
+    tenant_calendar_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Mandantenkalender__IdMitText", coerce=True, nullable=True, description="Tenant calendar id-text.")
+    calendar_source: Optional[Series[pd.StringDtype]] = pa.Field(alias="KalenderQuelle", coerce=True, nullable=True, description="Calendar source.")
+
+    class _Annotation:
+        primary_key = "combined_key"
+
+    class Config:
+        coerce = True
+        strict = "filter"

brynq_sdk_sage_germany/start_end_dates.py

@@ -0,0 +1,123 @@
+"""
+Start/end date endpoint implementations for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+from pydantic import BaseModel
+
+from .helpers import start_end_flat_to_nested
+from .schemas.start_end_dates import StartEndDatesCreate, StartEndDatesGet
+
+if TYPE_CHECKING:
+    from .employees import Employees
+
+
+class StartEndDates:
+    """
+    Handles employment period operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/employeenew/person/beschaeftigungszeiten"
+
+    def get(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve employment period data for one or many employees.
+        """
+        try:
+            if company_id is not None and employee_number is not None:
+                employee_keys = [{"MdNr": company_id, "AnNr": employee_number}]
+            else:
+                employee_keys = self.sage._employee_search()
+
+            if not employee_keys:
+                return pd.DataFrame(), pd.DataFrame()
+
+            period_records = []
+            effective_date = date or datetime.now(timezone.utc).strftime("%Y-%m-%dT00:00:00")
+
+            for key in employee_keys:
+                response = self.sage.get(
+                    path=self.base_url,
+                    params={"MdNr": key["MdNr"], "AnNr": key["AnNr"], "date": effective_date},
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if isinstance(payload, dict):
+                    period_records.append(payload)
+
+            if not period_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            dataframe = pd.json_normalize(period_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=dataframe,
+                schema=StartEndDatesGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve employment period data.") from exc
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create or update employment period (Beschaeftigungszeiten) for an employee.
+
+        Accepts flat snake_case keys; converts to nested Sage payload using schema prefixes.
+        """
+        try:
+            nested_payload = start_end_flat_to_nested(data, StartEndDatesCreate)
+            validated = StartEndDatesCreate(**nested_payload)
+            payload = validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+            response = self.sage.post(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create Sage Germany employment period.") from exc
+
+    def delete(
+        self,
+        company_id: int,
+        employee_number: int,
+        entry_date: str,
+        combined_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Delete an employment period by MdNr/AnNr/Eintritt (query params).
+        """
+        params: Dict[str, Any] = {
+            "MdNr": company_id,
+            "AnNr": employee_number,
+            "Eintritt": entry_date,
+        }
+        if combined_key is not None:
+            params["CombinedKey"] = combined_key
+
+        try:
+            response = self.sage.delete(
+                path=self.base_url,
+                params=params,
+            )
+            response.raise_for_status()
+            try:
+                return response.json()
+            except Exception:
+                return {"raw_response": response.text}
+        except Exception as exc:
+            raise RuntimeError("Failed to delete Sage Germany employment period.") from exc