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

brynq_sdk_sage_germany/organization.py

@@ -0,0 +1,90 @@
+"""
+Organization endpoint implementations for Sage Germany.
+"""
+
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .helpers import organization_flat_to_nested
+from .schemas.organization import OrganizationCreate, OrganizationGet
+
+
+class Organization:
+    """
+    Handles organization structure and cost allocation operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/employeenew/person/Organisation"
+
+    def _collect_employee_keys(self) -> List[Dict[str, int]]:
+        """
+        Retrieve distinct MdNr/AnNr pairs using the employee search endpoint.
+        """
+        return self.sage._employee_search()
+
+    def get(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve organization data (cost centers, cost units, org structures) for 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._collect_employee_keys()
+
+            if not employee_keys:
+                return pd.DataFrame(), pd.DataFrame()
+
+            organization_records: List[Dict[str, Any]] = []
+            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):
+                    organization_records.append(payload)
+
+            if not organization_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            dataframe = pd.json_normalize(organization_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=dataframe,
+                schema=OrganizationGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve organization data.") from exc
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create or update organization allocation data for an employee.
+        """
+        try:
+            nested_payload = organization_flat_to_nested(data)
+            payload = OrganizationCreate(**nested_payload).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 organization allocation.") from exc

brynq_sdk_sage_germany/payroll.py

@@ -0,0 +1,167 @@
+"""
+Payroll endpoint implementations for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .helpers import sage_flat_to_nested_with_prefix
+from .schemas import PayrollGet, PayrollMasterDataCreate, PayrollMasterDataGet
+
+if TYPE_CHECKING:
+    from .employees import Employees
+
+
+class Payroll:
+    """
+    Handles payroll-related operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.master_data_url = "/employeenew/abrechnungsdaten/grunddaten"
+        self.master_data_create_url = "/employeenew/abrechnungsdaten/grunddaten"
+        self.payroll_url = "/pay/abrechnung/abrechnungsdaten"
+
+    def get_master_data(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve payroll master data for a specific employee or all 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()
+
+            master_records: List[Dict[str, Any]] = []
+            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.master_data_url,
+                    params={"MdNr": key["MdNr"], "AnNr": key["AnNr"], "date": effective_date},
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if isinstance(payload, dict):
+                    master_records.append(payload)
+
+            if not master_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            dataframe = pd.json_normalize(master_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=dataframe,
+                schema=PayrollMasterDataGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve payroll master data.") from exc
+
+    def get(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve payroll run results (Brutto/Netto, tax, and insurance breakdowns).
+        """
+        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()
+
+            payroll_records: List[Dict[str, Any]] = []
+            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.payroll_url,
+                    params={"MdNr": key["MdNr"], "AnNr": key["AnNr"], "date": effective_date},
+                )
+                response.raise_for_status()
+                payload = response.json()
+
+                if isinstance(payload, dict):
+                    payload_items = [payload]
+                elif isinstance(payload, list):
+                    payload_items = payload
+                else:
+                    continue
+
+                for entry in payload_items:
+                    if not isinstance(entry, dict):
+                        continue
+                    enriched_entry = entry.copy()
+                    enriched_entry["company_id"] = key["MdNr"]
+                    enriched_entry["employee_number"] = enriched_entry.get("Personalnummer", key["AnNr"])
+                    enriched_entry["source_date"] = effective_date
+                    payroll_records.append(enriched_entry)
+
+            if not payroll_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            dataframe = pd.json_normalize(payroll_records, sep="__").copy()
+
+            dataframe["company_id"] = (
+                pd.to_numeric(dataframe["company_id"], errors="coerce").astype("Int64")
+            )
+            dataframe["employee_number"] = (
+                pd.to_numeric(dataframe["employee_number"], errors="coerce").astype("Int64")
+            )
+
+            source_dates = pd.to_datetime(
+                dataframe["source_date"], errors="coerce"
+            ).dt.strftime("%Y-%m-%d")
+
+            dataframe["combined_key"] = (
+                dataframe["company_id"].astype("string")
+                + "_"
+                + dataframe["employee_number"].astype("string")
+                + "_"
+                + source_dates.fillna("")
+            )
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=dataframe,
+                schema=PayrollGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve payroll data.") from exc
+
+    def create_master_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create or update payroll master data (abrechnungsdaten/grunddaten).
+        """
+        try:
+            nested_payload = sage_flat_to_nested_with_prefix(data, PayrollMasterDataCreate)
+            payload = PayrollMasterDataCreate(**nested_payload).model_dump(by_alias=True, exclude_none=True, mode="json")
+
+            response = self.sage.post(
+                path=self.master_data_create_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create Sage Germany payroll master data.") from exc

brynq_sdk_sage_germany/payslips.py

@@ -0,0 +1,106 @@
+"""
+Payroll document endpoints (payslip metadata + download) for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas import PayslipsGet
+
+
+
+
+class Payslips:
+    """
+    Retrieves and downloads payslip-style payroll documents (Verdienstbescheinigung §108 GewO).
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/Employee/Pay/Documents"
+
+    def _fetch_payload(self, request_params: Dict[str, Any]) -> List[Dict[str, Any]]:
+        response = self.sage.get(
+            path=self.base_url,
+            params=request_params,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        return payload if isinstance(payload, list) else []
+
+    def _fetch_all_employee_payslips(self) -> List[Dict[str, Any]]:
+        employee_keys = self.sage._employee_search()  # noqa: SLF001
+        if not employee_keys:
+            return []
+
+        records: List[Dict[str, Any]] = []
+        for key in employee_keys:
+            key_params: Dict[str, Any] = {
+                "MdNr": key["MdNr"],
+                "AnNr": key["AnNr"],
+                "sbc": "false",
+            }
+            records.extend(self._fetch_payload(key_params))
+        return records
+
+    def get(
+        self,
+        period: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+        date: Optional[str] = None,
+        employee_shipping_type: Optional[int] = None,
+        sbc: Optional[bool] = False,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        List payslips for the provided filters.
+        """
+        try:
+            params: Dict[str, Any] = {}
+            if period:
+                params["periode"] = period
+            if company_id is not None:
+                params["MdNr"] = company_id
+            if employee_number is not None:
+                params["AnNr"] = employee_number
+            if date:
+                params["Date"] = date
+            if employee_shipping_type is not None:
+                params["employeeshippingtype"] = employee_shipping_type
+
+            params["sbc"] = str(sbc).lower()
+
+            if params:
+                records = self._fetch_payload(params)
+            else:
+                records = self._fetch_all_employee_payslips()
+
+            if not records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(records, sep="__")
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=PayslipsGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve payslips.") from exc
+
+    def download(self, document_id: int, inline: bool = False) -> bytes:
+        """
+        Download a single payslip (PDF binary).
+        """
+        try:
+            response = self.sage.get(
+                path=self.base_url,
+                params={"Id": document_id, "Inline": str(inline).lower()},
+            )
+            response.raise_for_status()
+            return response.content
+        except Exception as exc:
+            raise RuntimeError(f"Failed to download payslip {document_id}.") from exc

brynq_sdk_sage_germany/salaries.py

@@ -0,0 +1,95 @@
+"""
+Salary endpoint implementations for Sage Germany.
+"""
+
+from typing import  Any, Dict, List, Optional, Tuple, Union
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas.salaries import SalaryGet, SalaryImport
+
+
+class Salary:
+    """
+    Handles salary-related operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/employeenew/entgelte/lohngehalt"
+
+    def get(
+        self,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve salary records for a single employee or all 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()
+
+            salary_records: List[Dict[str, Any]] = []
+            for key in employee_keys:
+                response = self.sage.get(
+                    path=self.base_url,
+                    params={"MdNr": key["MdNr"], "AnNr": key["AnNr"]},
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if isinstance(payload, dict):
+                    salary_records.append(payload)
+
+            if not salary_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(salary_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=SalaryGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve salary data.") from exc
+
+    def update(self, data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Dict[str, Any]:
+        """
+        Import or update gross salary (Bruttolohn) records.
+
+        Accepts a single dict or a list of dicts with Sage field names such as
+        Mdnr, Annr, AbrJahr, AbrMon, Tag, Lanr, Anzahl, Betrag, KoSt1, KoTr1, AA1, Zuschlag.
+        """
+        try:
+            if isinstance(data, dict):
+                items = [data]
+            elif isinstance(data, list):
+                if not data:
+                    raise ValueError("Salary update payload list must not be empty.")
+                if not all(isinstance(item, dict) for item in data):
+                    raise ValueError("Salary update payload list must contain only dictionaries.")
+                items = data
+            else:
+                raise ValueError("Salary update payload must be a dictionary or list of dictionaries.")
+
+            # API requires a list payload even for single salary import items.
+            payload = [
+                SalaryImport(**item).model_dump(by_alias=True, exclude_none=True, mode="json")
+                for item in items
+            ]
+
+            response = self.sage.post(
+                path="/Pay/Import/Bruttolohn",
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to update Sage Germany salary records.") from exc

brynq_sdk_sage_germany/schemas/__init__.py

@@ -0,0 +1,44 @@
+"""
+Schema namespace for Sage Germany endpoints.
+"""
+
+from .employees import EmployeeUpdateRequest, EmployeeCreateForm, EmployeesGet
+from .absences import AbsenceTypesGet, AbsencesGet, AbsenceCreate, AbsenceDelete
+
+from .salaries import SalaryGet, SalaryImport
+
+
+from .allowances import AllowancesGet, AllowanceCreateRequest
+from .start_end_dates import StartEndDatesGet
+from .work_hours import WorkHoursGet, WorkHoursCreate
+from .payroll import PayrollGet, PayrollMasterDataGet, PayrollMasterDataCreate
+from .payslips import PayslipsGet
+from .vacation_account import VacationAccountGet
+from .cost_centers import CostCentersGet, CostCenterCreate
+from .organization import OrganizationGet, OrganizationCreate
+
+__all__ = [
+    "EmployeesGet",
+    "EmployeeUpdateRequest",
+    "EmployeeCreateForm",
+    "AbsencesGet",
+    "AbsenceTypesGet",
+    "AbsenceCreate",
+    "AbsenceDelete",
+    "SalaryGet",
+    "SalaryImport",
+    "AllowancesGet",
+    "AllowanceCreateRequest",
+    "StartEndDatesGet",
+    "WorkHoursGet",
+    "WorkHoursCreate",
+    "PayrollGet",
+    "PayrollMasterDataGet",
+    "PayrollMasterDataCreate",
+    "PayslipsGet",
+    "VacationAccountGet",
+    "CostCentersGet",
+    "CostCenterCreate",
+    "OrganizationGet",
+    "OrganizationCreate",
+]