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

brynq_sdk_sage_germany/schemas/employees.py

@@ -0,0 +1,487 @@
+"""
+Schemas for Sage Germany employee payloads.
+"""
+
+from datetime import datetime
+from typing import Optional
+
+import pandas as pd
+import pandera as pa
+from pydantic import BaseModel, Field, ConfigDict
+from pandera.typing import Series
+
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+
+class SageIdText(BaseModel):
+    """
+    Generic Id/Text container used throughout Sage payloads.
+    """
+
+    # Optional fields
+    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="Sample text")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class SageCountry(BaseModel):
+    """
+    Country representation used inside address/identity structures.
+    """
+
+    # Optional fields
+    id: Optional[int] = Field(default=None, alias="Id", description="Country identifier.", example=276)
+    nationality: Optional[str] = Field(default=None, alias="Nationality", description="Nationality label.", example="deutsch")
+    name: Optional[str] = Field(default=None, alias="Name", description="Country name.", example="Deutschland")
+    iso_code: Optional[str] = Field(default=None, alias="IsoCode", description="ISO code.", example="DE")
+    combined_key: Optional[str] = Field(default=None, alias="CombinedKey", description="Combined key string.", example="DE-276")
+    is_eu_member: Optional[bool] = Field(default=None, alias="EULand", description="EU membership flag.", example=True)
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeKey(BaseModel):
+    """
+    Snapshot key metadata for a single employee object.
+    """
+
+    # Required fields
+    date: datetime = Field(alias="Date", description="Snapshot date.", example="2025-01-01T00:00:00Z")
+    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: str = Field(alias="CombinedKey", description="Combined key string.", example="1_210")
+    is_empty: bool = Field(alias="IsEmpty", description="Marks an empty key payload.", example=False)
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeePersonTitle(BaseModel):
+    """
+    Title payload for person metadata.
+    """
+
+    # Optional fields
+    id: Optional[int] = Field(default=None, alias="Id", description="Title identifier.", example=1)
+    title: Optional[str] = Field(default=None, alias="Title", description="Title text.", example="Dr.")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeePerson(BaseModel):
+    """
+    Person block containing the required identity properties.
+    """
+
+    # Required fields
+    first_name: str = Field(alias="Vorname", description="Employee first name.", example="Yakup")
+    last_name: str = Field(alias="Nachname", description="Employee last name.", example="Keskin")
+    birth_date: datetime = Field(alias="Geburtsdatum", description="Birth date in ISO-8601 format.", example="1990-01-15T00:00:00Z")
+
+    # Optional fields
+    title: Optional[EmployeePersonTitle] = Field(default=None, alias="Titel", description="Optional title information.", example={"Title": "Dr."}, json_schema_extra={"prefix": "person_title_"})
+    birth_name: Optional[str] = Field(default=None, alias="Geburtsname", description="Birth name if different.", example="Keskinkor")
+    gender: Optional[str] = Field(default=None, alias="Geschlecht", description="Gender value accepted by Sage.", example="Male")
+    family_status: Optional[SageIdText] = Field(default=None, alias="Familienstand", description="Family status reference.", example={"Id": 1, "Text": "verheiratet"}, json_schema_extra={"prefix": "person_family_status_"})
+    prefix_words: Optional[SageIdText] = Field(default=None, alias="Vorsatzworte", description="Name prefix reference.", example={"Text": "von"}, json_schema_extra={"prefix": "person_prefix_words_"})
+    suffix_words: Optional[SageIdText] = Field(default=None, alias="Namenszusatz", description="Name suffix reference.", example={"Text": "III"}, json_schema_extra={"prefix": "person_suffix_words_"})
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeAddress(BaseModel):
+    """
+    Postal address payload for the employee.
+    """
+
+    # Optional fields
+    street: Optional[str] = Field(default=None, alias="Strasse", description="Street line 1.", example="Bremer Straße 24")
+    address_addition: Optional[str] = Field(default=None, alias="Adresszusatz", description="Additional address line.", example="c/o HQ")
+    postal_code: Optional[str] = Field(default=None, alias="Postleitzahl", description="Zip/postal code.", example="44536")
+    foreign_postal_code: Optional[str] = Field(default=None, alias="PostleitzahlAusland", description="Foreign postal code.", example="")
+    city: Optional[str] = Field(default=None, alias="Ort", description="City of residence.", example="Lünen")
+    foreign_city: Optional[str] = Field(default=None, alias="OrtAusland", description="Foreign city value.", example="")
+    country: Optional[SageCountry] = Field(
+        default=None,
+        alias="Land",
+        description="Nested country metadata.",
+        example={"Name": "Deutschland", "IsoCode": "DE"},
+        json_schema_extra={"prefix": "address_country_"},
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeContact(BaseModel):
+    """
+    Contact details for the employee.
+    """
+
+    # Optional fields
+    phone: Optional[str] = Field(default=None, alias="Telefon", description="Personal phone number.", example="+49-30-123456")
+    mobile: Optional[str] = Field(default=None, alias="Mobil", description="Personal mobile number.", example="+49-171-555555")
+    email: Optional[str] = Field(default=None, alias="EMail", description="Personal email address.", example="user@example.com")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeBusinessContact(BaseModel):
+    """
+    Work contact details (KontaktDienstlich block).
+    """
+
+    # Optional fields
+    phone: Optional[str] = Field(default=None, alias="Telefon", description="Business phone number.", example="+49-30-999999")
+    mobile: Optional[str] = Field(default=None, alias="Mobil", description="Business mobile number.", example="+49-171-999999")
+    email: Optional[str] = Field(default=None, alias="EMail", description="Business email address.", example="user@company.com")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeIdentity(BaseModel):
+    """
+    National identity metadata.
+    """
+
+    # Optional fields
+    tax_id: Optional[str] = Field(default=None, alias="SteuerID", description="German tax identification number.", example="97196340258")
+    insurance_number_known: Optional[bool] = Field(default=None, alias="VersicherungsnummerBekannt", description="Whether the social insurance number is known.", example=True)
+    insurance_number: Optional[str] = Field(default=None, alias="Versicherungsnummer", description="Social insurance number.", example="19281058G990")
+    insurance_card_present: Optional[bool] = Field(default=None, alias="VersicherungsAusweisLiegtVor", description="Whether an insurance card is present.", example=True)
+    nationality: Optional[SageCountry] = Field(default=None, alias="Nationalitaet", description="Nationality reference object.", example={"Name": "Deutschland"}, json_schema_extra={"prefix": "identity_nationality_"})
+    birth_country: Optional[SageCountry] = Field(default=None, alias="GeburtsLand", description="Birth country reference.", example={"IsoCode": "DE"}, json_schema_extra={"prefix": "identity_birth_country_"})
+    birth_city: Optional[str] = Field(default=None, alias="GeburtsOrt", description="Birth city.", example="Berlin")
+    residence_permit_until: Optional[datetime] = Field(default=None, alias="Aufenthaltserlaubnis", description="Residence permit expiration date.", example="2030-12-31T00:00:00Z")
+    passport_valid_until: Optional[datetime] = Field(default=None, alias="Passgueltigkeit", description="Passport validity date.", example="2030-12-31T00:00:00Z")
+    work_permit_until: Optional[datetime] = Field(default=None, alias="Arbeitserlaubnis", description="Work permit expiration date.", example="2030-12-31T00:00:00Z")
+    eu_insurance_number: Optional[str] = Field(default=None, alias="EUVersicherungsnummer", description="EU insurance number.", example="EU-987654321")
+    first_employment: Optional[bool] = Field(default=None, alias="ErstmaligeAufnahmeBesch", description="Indicates if this is the first employment.", example=False)
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class BankAccountReference(BaseModel):
+    """
+    Reference to an existing company bank account.
+    """
+
+    # Optional fields
+    id: Optional[int] = Field(default=None, alias="Id", description="Bank account identifier.", example=201)
+    company_id: Optional[int] = Field(default=None, alias="MdNr", description="Company identifier for the bank account.", example=1)
+    account_number: Optional[str] = Field(default=None, alias="AccountNr", description="Bank account number.", example="1234567890")
+    bank_code: Optional[int] = Field(default=None, alias="BankCode", description="Bank code (BLZ).", example=44070050)
+    bank_name: Optional[str] = Field(default=None, alias="BankName", description="Name of the bank.", example="Deutsche Bank")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeBankDetails(BaseModel):
+    """
+    Bank information used for payouts.
+    """
+
+    # Optional fields
+    key_type: Optional[SageIdText] = Field(default=None, alias="Schluesselart", description="Bank key type reference.", example={"Id": 0, "Text": "Standardüberweisung"}, json_schema_extra={"prefix": "bank_key_type_"})
+    purpose: Optional[str] = Field(default=None, alias="Verwendungszweck", description="Transaction purpose text.", example="Lohn- und Gehalt")
+    iban: Optional[str] = Field(default=None, alias="IBAN", description="IBAN number.", example="DE89440700500897858865")
+    bic: Optional[str] = Field(default=None, alias="BIC", description="BIC/SWIFT code.", example="DEUTDEDE440")
+    bank_reference: Optional[SageIdText] = Field(default=None, alias="Bank", description="Bank reference object.", example={"Id": 205, "Text": "Deutsche Bank Dortmund"}, json_schema_extra={"prefix": "bank_reference_"})
+    account_number: Optional[str] = Field(default=None, alias="Kontonummer", description="Domestic account number.", example="0897858865")
+    bank_code: Optional[int] = Field(default=None, alias="Bankleitzahl", description="Bank code (BLZ).", example=44070050)
+    recipient: Optional[str] = Field(default=None, alias="Empfaenger", description="Recipient name.", example="Gehalt, Manuela")
+    validation_amount: Optional[float] = Field(default=None, alias="PruefBetrag", description="Validation amount used by Sage.", example=0.0)
+    settlement_account: Optional[BankAccountReference] = Field(default=None, alias="VerrechnungUeber", description="Settlement account reference.", example={"Id": 201, "MdNr": 1}, json_schema_extra={"prefix": "bank_settlement_"})
+    payment_type: Optional[str] = Field(default=None, alias="Zahlungsart", description="Payment method type.", example="Inland")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class DisabilityEmployeeKey(BaseModel):
+    """
+    Employee key inside disability structure.
+    """
+
+    # Optional fields
+    company_id: Optional[int] = Field(default=None, alias="MdNr", description="Company identifier.", example=1)
+    employee_number: Optional[int] = Field(default=None, alias="AnNr", description="Employee number.", example=9999)
+    combined_key: Optional[str] = Field(default=None, alias="CombinedKey", description="Composite key for the employee.", example="1-9999")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeDisabilityData(BaseModel):
+    """
+    Schwerbehindertendaten block.
+    """
+
+    # Optional fields
+    employee_key: Optional[DisabilityEmployeeKey] = Field(
+        default=None,
+        alias="EmployeeKey",
+        description="Employee key reference for disability record.",
+        example={"MdNr": 1, "AnNr": 9999},
+        json_schema_extra={"prefix": "disability_employee_key_"},
+    )
+    identifier: Optional[int] = Field(default=None, alias="Id", description="Disability record identifier.", example=1)
+    marker: Optional[SageIdText] = Field(
+        default=None,
+        alias="Kennzeichnung",
+        description="Disability marker classification.",
+        example={"Id": 1, "Text": "Schwerbehinderung"},
+        json_schema_extra={"prefix": "disability_marker_"},
+    )
+    degree: Optional[SageIdText] = Field(
+        default=None,
+        alias="GradDerBehinderung",
+        description="Degree of disability (GdB).",
+        example={"Id": 50, "Text": "50%"},
+        json_schema_extra={"prefix": "disability_degree_"},
+    )
+    valid_from: Optional[datetime] = Field(default=None, alias="GueltigAb", description="Start date of disability recognition.", example="2020-01-01T00:00:00Z")
+    valid_to: Optional[datetime] = Field(default=None, alias="GueltigBis", description="End date of disability recognition.", example="2025-12-31T00:00:00Z")
+    unlimited: Optional[bool] = Field(default=None, alias="Unbefristet", description="Indicates if disability recognition is unlimited.", example=False)
+    special_leave: Optional[int] = Field(default=None, alias="AbweichenderSonderurlaub", description="Special leave days granted for disability.", example=5)
+    responsible_office: Optional[SageIdText] = Field(
+        default=None,
+        alias="ZustaendigesAmt",
+        description="Responsible authority office for disability matters.",
+        example={"Id": 1, "Text": "Versorgungsamt Berlin"},
+        json_schema_extra={"prefix": "disability_responsible_office_"},
+    )
+    location: Optional[str] = Field(default=None, alias="Standort", description="Location reference for disability record.", example="Berlin")
+    file_reference: Optional[str] = Field(default=None, alias="Aktenzeichen", description="File reference number for disability case.", example="AZ-2020-12345")
+    obligation_positions: Optional[float] = Field(default=None, alias="Pflichtplaetze", description="Obligation positions count.", example=1.0)
+    disability_start: Optional[datetime] = Field(default=None, alias="BeginnBehinderung", description="Start date of the disability condition.", example="2019-06-15T00:00:00Z")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeeCreateForm(BaseModel):
+    """
+    Minimal payload for EmployeeNew Neuanlage endpoint.
+    """
+
+    # Required fields
+    company_id: int = Field(
+        alias="Key.MdNr",
+        description="Company (Mandant) identifier.",
+        example=1,
+    )
+    employee_number: int = Field(
+        alias="Key.AnNr",
+        description="Employee number (AnNr) to assign.",
+        example=210,
+    )
+    first_name: str = Field(
+        alias="Vorname",
+        description="Employee first name.",
+        example="Sinan",
+    )
+    last_name: str = Field(
+        alias="Nachname",
+        description="Employee last name.",
+        example="Resicowicz",
+    )
+
+    # Optional fields
+    combined_key: Optional[str] = Field(
+        default=None,
+        alias="Key.CombinedKey",
+        description="Optional combined key string for the employee.",
+        example="1_210",
+    )
+    birth_date: Optional[datetime] = Field(
+        default=None,
+        alias="Geburtsdatum",
+        description="Birth date in ISO-8601 format.",
+        example="1974-01-02T00:00:00",
+    )
+    entry_date: Optional[datetime] = Field(
+        default=None,
+        alias="Eintritt",
+        description="Employment start date in ISO-8601 format.",
+        example="2025-01-02T00:00:00",
+    )
+    gender: Optional[str] = Field(
+        default=None,
+        alias="Geschlecht",
+        description="Gender value expected by Sage (e.g., Male, Female).",
+        example="Male",
+    )
+    template_id: Optional[int] = Field(
+        default=None,
+        alias="TemplateId",
+        description="Optional template identifier used by Sage.",
+        example=5,
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+class EmployeeUpdateRequest(BaseModel):
+    """
+    Pydantic schema describing the POST payload for employee updates.
+    """
+
+    # Required fields
+    person: EmployeePerson = Field(
+        alias="Person",
+        description="Person block containing identification details.",
+        example={"Vorname": "Max", "Nachname": "Mustermann"},
+        json_schema_extra={"prefix": "person_"},
+    )
+    key: EmployeeKey = Field(
+        alias="Key",
+        description="Snapshot key metadata identifying the employee record.",
+        example={"MdNr": 1, "AnNr": 1001},
+        json_schema_extra={"prefix": "key_"},
+    )
+
+    # Optional fields
+
+    address: Optional[EmployeeAddress] = Field(
+        default=None,
+        alias="Adresse",
+        description="Employee address information.",
+        example={"Strasse": "Sample Street 1"},
+        json_schema_extra={"prefix": "address_"},
+    )
+    contact: Optional[EmployeeContact] = Field(
+        default=None,
+        alias="Kontakt",
+        description="Personal contact details.",
+        example={"EMail": "user@example.com"},
+        json_schema_extra={"prefix": "contact_"},
+    )
+    business_contact: Optional[EmployeeBusinessContact] = Field(
+        default=None,
+        alias="KontaktDienstlich",
+        description="Business contact details.",
+        example={"EMail": "user@company.com"},
+        json_schema_extra={"prefix": "contact_business_"},
+    )
+    identity: Optional[EmployeeIdentity] = Field(
+        default=None,
+        alias="Identitaet",
+        description="Identity information such as tax and insurance data.",
+        json_schema_extra={"prefix": "identity_"},
+    )
+    bank_details: Optional[EmployeeBankDetails] = Field(
+        default=None,
+        alias="Bankverbindung",
+        description="Bank payout configuration.",
+        json_schema_extra={"prefix": "bank_"},
+    )
+    disability_data: Optional[EmployeeDisabilityData] = Field(
+        default=None,
+        alias="Schwerbehindertendaten",
+        description="Disability data block.",
+        json_schema_extra={"prefix": "disability_"},
+    )
+    is_sage_hr_integration: Optional[bool] = Field(
+        default=None,
+        alias="IsSageHrIntegration",
+        description="Indicates if the record originates from Sage HR integration.",
+        example=False,
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class EmployeesGet(BrynQPanderaDataFrameModel):
+    """
+    Pandera schema for flattened employee records coming from Sage Germany.
+    """
+
+    is_sage_hr_integration: Series[bool] = pa.Field(alias="IsSageHrIntegration", coerce=True, nullable=True, description="Indicates whether record was created via Sage HR integration.")
+    record_timestamp: Series[pd.StringDtype] = pa.Field(alias="Key__Date", coerce=True, nullable=False, description="Snapshot timestamp as string.")
+    company_id: Series[pd.Int64Dtype] = pa.Field(alias="Key__MdNr", coerce=True, nullable=False, description="Company (Mandant) id.")
+    employee_number: Series[pd.Int64Dtype] = pa.Field(alias="Key__AnNr", coerce=True, nullable=False, description="Employee number.")
+    employee_reference_key: Series[pd.StringDtype] = pa.Field(alias="Key__CombinedKey", coerce=True, nullable=False, description="Combined identifier for the snapshot.")
+    key_is_empty: Optional[Series[bool]] = pa.Field(alias="Key__IsEmpty", coerce=True, nullable=True, description="Indicates whether the key payload is empty.")
+
+    person_title: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Titel", coerce=True, nullable=True, description="Title object payload.")
+    person_title_id: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Titel__Id", coerce=True, nullable=True, description="Title identifier.")
+    person_title_title: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Titel__Title", coerce=True, nullable=True, description="Title text field.")
+    first_name: Series[pd.StringDtype] = pa.Field(alias="Person__Vorname", coerce=True, nullable=False, description="First name.")
+    last_name: Series[pd.StringDtype] = pa.Field(alias="Person__Nachname", coerce=True, nullable=False, description="Last name.")
+    birth_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Geburtsname", coerce=True, nullable=True, description="Birth name.")
+    gender: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Geschlecht", coerce=True, nullable=True, description="Gender.")
+    birth_date: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Geburtsdatum", coerce=True, nullable=True, description="Birth date.")
+    family_status_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Person__Familienstand__Id", coerce=True, nullable=True, description="Family status identifier.")
+    family_status_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Familienstand__Text", coerce=True, nullable=True, description="Family status text.")
+    family_status_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Familienstand__IdMitText", coerce=True, nullable=True, description="Family status id-text.")
+    name_special: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Namensbesonderheiten", coerce=True, nullable=True, description="Special name notes.")
+    prefix: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Vorsatzworte", coerce=True, nullable=True, description="Prefix words.")
+    suffix: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__Namenszusatz", coerce=True, nullable=True, description="Suffix words.")
+    birth_prefix: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__GebVorsatzworte", coerce=True, nullable=True, description="Birth prefix words.")
+    birth_suffix: Optional[Series[pd.StringDtype]] = pa.Field(alias="Person__GebNamenszusatz", coerce=True, nullable=True, description="Birth suffix words.")
+
+    street: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Strasse", coerce=True, nullable=True, description="Street address.")
+    street_addition: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Adresszusatz", coerce=True, nullable=True, description="Address addition.")
+    postal_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Postleitzahl", coerce=True, nullable=True, description="Postal code.")
+    postal_code_foreign: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__PostleitzahlAusland", coerce=True, nullable=True, description="Foreign postal code.")
+    city: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Ort", coerce=True, nullable=True, description="City.")
+    city_foreign: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__OrtAusland", coerce=True, nullable=True, description="Foreign city.")
+    country_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Adresse__Land__Id", coerce=True, nullable=True, description="Country identifier.")
+    country_nationality: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Land__Nationality", coerce=True, nullable=True, description="Country nationality label.")
+    country_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Land__Name", coerce=True, nullable=True, description="Country name.")
+    country_iso: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Land__IsoCode", coerce=True, nullable=True, description="Country ISO code.")
+    country_combined_key: Optional[Series[pd.StringDtype]] = pa.Field(alias="Adresse__Land__CombinedKey", coerce=True, nullable=True, description="Country combined key.")
+    country_is_eu: Optional[Series[bool]] = pa.Field(alias="Adresse__Land__EULand", coerce=True, nullable=True, description="EU membership flag.")
+
+    phone: Optional[Series[pd.StringDtype]] = pa.Field(alias="Kontakt__Telefon", coerce=True, nullable=True, description="Phone number.")
+    mobile: Optional[Series[pd.StringDtype]] = pa.Field(alias="Kontakt__Mobil", coerce=True, nullable=True, description="Mobile number.")
+    contact_email: Optional[Series[pd.StringDtype]] = pa.Field(alias="Kontakt__EMail", coerce=True, nullable=True, description="Email address.")
+    work_phone: Optional[Series[pd.StringDtype]] = pa.Field(alias="KontaktDienstlich__Telefon", coerce=True, nullable=True, description="Work phone.")
+    work_mobile: Optional[Series[pd.StringDtype]] = pa.Field(alias="KontaktDienstlich__Mobil", coerce=True, nullable=True, description="Work mobile.")
+    work_email: Optional[Series[pd.StringDtype]] = pa.Field(alias="KontaktDienstlich__EMail", coerce=True, nullable=True, description="Work email.")
+    contact_business_raw: Optional[Series[pd.StringDtype]] = pa.Field(alias="KontaktDienstlich", coerce=True, nullable=True, description="Raw business contact payload.")
+
+    tax_id: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__SteuerID", coerce=True, nullable=True, description="Tax identification number.")
+    insurance_known: Optional[Series[bool]] = pa.Field(alias="Identitaet__VersicherungsnummerBekannt", coerce=True, nullable=True, description="Insurance number known flag.")
+    insurance_number: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Versicherungsnummer", coerce=True, nullable=True, description="Insurance number.")
+    insurance_card_present: Optional[Series[bool]] = pa.Field(alias="Identitaet__VersicherungsAusweisLiegtVor", coerce=True, nullable=True, description="Insurance card present flag.")
+    nationality_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Identitaet__Nationalitaet__Id", coerce=True, nullable=True, description="Nationality identifier.")
+    nationality_label: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Nationalitaet__Nationality", coerce=True, nullable=True, description="Nationality label.")
+    nationality_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Nationalitaet__Name", coerce=True, nullable=True, description="Nationality name.")
+    nationality_iso: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Nationalitaet__IsoCode", coerce=True, nullable=True, description="Nationality ISO.")
+    nationality_combined_key: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Nationalitaet__CombinedKey", coerce=True, nullable=True, description="Nationality combined key.")
+    nationality_is_eu: Optional[Series[bool]] = pa.Field(alias="Identitaet__Nationalitaet__EULand", coerce=True, nullable=True, description="Nationality EU flag.")
+    nationality_raw: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Nationalitaet", coerce=True, nullable=True, description="Original nationality payload.")
+    birth_country_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Identitaet__GeburtsLand__Id", coerce=True, nullable=True, description="Birth country id.")
+    birth_country_nationality: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsLand__Nationality", coerce=True, nullable=True, description="Birth country nationality.")
+    birth_country_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsLand__Name", coerce=True, nullable=True, description="Birth country name.")
+    birth_country_iso: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsLand__IsoCode", coerce=True, nullable=True, description="Birth country ISO.")
+    birth_country_combined_key: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsLand__CombinedKey", coerce=True, nullable=True, description="Birth country combined key.")
+    birth_country_is_eu: Optional[Series[bool]] = pa.Field(alias="Identitaet__GeburtsLand__EULand", coerce=True, nullable=True, description="Birth country EU flag.")
+    birth_country_raw: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsLand", coerce=True, nullable=True, description="Original birth country payload.")
+    birth_city: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__GeburtsOrt", coerce=True, nullable=True, description="Birth city.")
+    residence_permit: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Aufenthaltserlaubnis", coerce=True, nullable=True, description="Residence permit date string.")
+    passport_valid_until: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Passgueltigkeit", coerce=True, nullable=True, description="Passport validity date string.")
+    work_permit: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__Arbeitserlaubnis", coerce=True, nullable=True, description="Work permit date string.")
+    eu_insurance_number: Optional[Series[pd.StringDtype]] = pa.Field(alias="Identitaet__EUVersicherungsnummer", coerce=True, nullable=True, description="EU insurance number.")
+    first_employment: Optional[Series[bool]] = pa.Field(alias="Identitaet__ErstmaligeAufnahmeBesch", coerce=True, nullable=True, description="First employment flag.")
+
+    bank_key_type_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Bankverbindung__Schluesselart__Id", coerce=True, nullable=True, description="Bank key type id.")
+    bank_key_type_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Schluesselart__Text", coerce=True, nullable=True, description="Bank key type text.")
+    bank_key_type_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Schluesselart__IdMitText", coerce=True, nullable=True, description="Bank key type id-text.")
+    payment_purpose: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Verwendungszweck", coerce=True, nullable=True, description="Payment purpose.")
+    iban: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__IBAN", coerce=True, nullable=True, description="IBAN.")
+    bic: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__BIC", coerce=True, nullable=True, description="BIC.")
+    bank_reference_object: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Bank", coerce=True, nullable=True, description="Raw bank reference payload.")
+    bank_reference_id: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Bank__Id", coerce=True, nullable=True, description="Bank reference id.")
+    bank_reference_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Bank__Text", coerce=True, nullable=True, description="Bank reference text.")
+    bank_reference_id_text: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Bank__IdMitText", coerce=True, nullable=True, description="Bank reference id-text.")
+    bank_account_number: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Kontonummer", coerce=True, nullable=True, description="Account number.")
+    bank_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Bankleitzahl", coerce=True, nullable=True, description="Bank code.")
+    bank_recipient: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Empfaenger", coerce=True, nullable=True, description="Payment recipient.")
+    bank_validation_amount: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__PruefBetrag", coerce=True, nullable=True, description="Validation amount.")
+    settlement_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Bankverbindung__VerrechnungUeber__Id", coerce=True, nullable=True, description="Settlement record id.")
+    settlement_company_id: Optional[Series[pd.Int64Dtype]] = pa.Field(alias="Bankverbindung__VerrechnungUeber__MdNr", coerce=True, nullable=True, description="Settlement company identifier.")
+    settlement_account: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__VerrechnungUeber__AccountNr", coerce=True, nullable=True, description="Settlement account number.")
+    settlement_bank_code: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__VerrechnungUeber__BankCode", coerce=True, nullable=True, description="Settlement bank code.")
+    settlement_bank_name: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__VerrechnungUeber__BankName", coerce=True, nullable=True, description="Settlement bank name.")
+    payment_type: Optional[Series[pd.StringDtype]] = pa.Field(alias="Bankverbindung__Zahlungsart", coerce=True, nullable=True, description="Payment type.")
+    class Config:
+        coerce = True
+        strict = False