brynq-sdk-nmbrs 2.3.1__py3-none-any.whl

brynq_sdk_nmbrs/__init__.py

@@ -0,0 +1,226 @@
+import warnings
+from typing import Union, List, Literal, Optional, get_args, get_origin
+import re
+import pandas as pd
+from pydantic import BaseModel
+import requests
+from brynq_sdk_brynq import BrynQ
+from .absence import Absence
+from .wage_tax import WageTax
+from .address import Address
+from .bank import Bank
+from zeep import Client, Settings
+from .children import Children
+from .companies import Companies
+from .debtors import Debtors
+from .contract import Contract
+from .costcenter import EmployeeCostcenter, Costcenter
+from .costunit import Costunit
+from .department import EmployeeDepartment
+from .document import Payslip
+from .employees import Employees
+from .salary_tables import SalaryTables, SalaryScales, SalarySteps
+from .employment import Employment
+from .function import EmployeeFunction
+from .hours import VariableHours, FixedHours
+from .days import VariableDays, FixedDays
+from .manager import EmployeeManager, Manager
+from .salaries import Salaries
+from .schedules import Schedule
+from .wagecomponents import EmployeeFixedWageComponents, EmployeeVariableWageComponents
+import os
+
+
+class Nmbrs(BrynQ):
+    def __init__(self, system_type: Optional[Literal['source', 'target']] = None, debug: bool = False, mock_mode: bool = True):
+        """
+        Initialize the Nmbrs class.
+
+        Args:
+            label: The label of the system in BrynQ. legacy
+            debug: Whether to print debug information
+11            mock_mode: If true, data will NOT be sent to Nmbrs but only be tested for validity against Pydantic schemas
+        """
+        self.mock_mode = mock_mode
+        self.debug = debug
+        self.timeout = 3600
+        self.system_type = system_type
+        if mock_mode is False:
+            super().__init__()
+            self.data_interface_id = os.getenv("DATA_INTERFACE_ID")
+            headers = self._get_request_headers()
+            self.base_url = "https://api.nmbrsapp.com/api/"
+            self.session = requests.Session()
+            self.session.headers.update(headers)
+
+            # Initialize SOAP client
+            self.soap_settings = Settings(
+                strict=False,
+                xml_huge_tree=True,
+                force_https=True
+            )
+            self.soap_client_companies = Client(
+                'https://api.nmbrs.nl/soap/v3/CompanyService.asmx?wsdl',
+                settings=self.soap_settings
+            )
+            self.soap_client_employees = Client(
+                'https://api.nmbrs.nl/soap/v3/EmployeeService.asmx?wsdl',
+                settings=self.soap_settings
+            )
+            self.soap_auth_header = self._get_soap_auth_header()
+            # Following methods can only be used if the SOAP authentication header is set (optional, this is not always in scope for all integrations)
+            if self.soap_auth_header is not None:
+                self.soap_company_ids = self.companies.get_soap_ids()
+                self.salary_tables = SalaryTables(self)
+                self.salary_scales = SalaryScales(self)
+                self.salary_steps = SalarySteps(self)
+                self.wage_tax = WageTax(self)
+                self.absence = Absence(self)
+                self.children = Children(self)
+
+        self.address = Address(self)
+        self.bank = Bank(self)
+        self.children = Children(self)
+        self.debtor = Debtors(self)
+        self.companies = Companies(self)
+        self.contract = Contract(self)
+        self.department = EmployeeDepartment(self)
+        debtors, _ = self.debtor.get()
+        self.debtor_ids = debtors['debtor_id'].to_list()
+        self.company_ids = self.companies.get()['companyId'].to_list()
+        self.employees = Employees(self)
+        self.employment = Employment(self)
+        self.function = EmployeeFunction(self)
+        self.fixed_hours = FixedHours(self)
+        self.fixed_days = FixedDays(self)
+        self.variable_hours = VariableHours(self)
+        self.variable_days = VariableDays(self)
+        self.manager = Manager(self)
+        self.employee_manager = EmployeeManager(self)
+        self.salaries = Salaries(self)
+        self.schedule = Schedule(self)
+        self.fixed_wagecomponents = EmployeeFixedWageComponents(self)
+        self.variable_wagecomponents = EmployeeVariableWageComponents(self)
+        self.current_period = self.companies.get_current_period()
+
+    def _get_request_headers(self):
+        credentials = self.interfaces.credentials.get(system='nmbrs', system_type=self.system_type)
+        headers = {
+            "accept": "application/json",
+            "Authorization": f"Bearer {credentials.get('data').get('access_token')}",
+            # partner identifier
+            "X-Subscription-Key": credentials.get("custom_data").get("subscription_key")
+        }
+
+        return headers
+
+    def _get_soap_auth_header(self):
+        """
+        Creates the SOAP authentication header using credentials from initial_credentials.
+
+        Returns:
+            AuthHeaderWithDomainType: The authentication header for SOAP requests
+        """
+        initial_credentials = self.interfaces.credentials.get(system='nmbrs', system_type=self.system_type)
+        config = initial_credentials.get("custom_data", {})
+
+        if 'soap_api_token' not in config.keys():
+            return None
+        else:
+            # Get the AuthHeaderWithDomain type from the WSDL
+            AuthHeaderWithDomainType = self.soap_client_companies.get_element('ns0:AuthHeaderWithDomain')
+
+            # Create the auth header using credentials from config
+            auth_header = AuthHeaderWithDomainType(
+                Username=config.get("soap_api_username"),
+                Token=config.get("soap_api_token"),
+                Domain=config.get("soap_api_domain")
+            )
+
+            return auth_header
+
+    def _get_soap_auth_header_employees(self):
+        """
+        Creates the SOAP authentication header using credentials from initial_credentials.
+
+        Returns:
+            AuthHeaderWithDomainType: The authentication header for SOAP requests
+        """
+        initial_credentials = self.get_system_credential(system='nmbrs', label='bob')
+        config = initial_credentials.get("config", {})
+
+        # Get the AuthHeaderWithDomain type from the WSDL
+        AuthHeaderWithDomainType = self.soap_client_employees.get_element('ns0:AuthHeaderWithDomain')
+
+        # Create the auth header using credentials from config
+        auth_header = AuthHeaderWithDomainType(
+            Username=config.get("soap_api_username"),
+            Token=config.get("soap_api_token"),
+            Domain=config.get("soap_api_domain")
+        )
+
+        return auth_header
+
+    def get_paginated_result(self, request: requests.Request) -> List:
+        has_next_page = True
+        result_data = []
+        while has_next_page:
+            prepped = request.prepare()
+            prepped.headers.update(self.session.headers)
+            resp = self.session.send(prepped, timeout=self.timeout)
+            resp.raise_for_status()
+            response_data = resp.json()
+            result_data += response_data['data']
+            next_page_url = response_data.get('pagination').get('nextPage')
+            has_next_page = next_page_url is not None
+            request.url = next_page_url
+
+        return result_data
+
+    def check_fields(self, data: Union[dict, List], required_fields: List, allowed_fields: List):
+        if isinstance(data, dict):
+            data = data.keys()
+
+        if self.debug:
+            print(f"Required fields: {required_fields}")
+            print(f"Allowed fields: {allowed_fields}")
+            print(f"Data: {data}")
+
+        for field in data:
+            if field not in allowed_fields and field not in required_fields:
+                warnings.warn('Field {field} is not implemented. Optional fields are: {allowed_fields}'.format(field=field, allowed_fields=tuple(allowed_fields)))
+
+        for field in required_fields:
+            if field not in data:
+                raise ValueError('Field {field} is required. Required fields are: {required_fields}'.format(field=field, required_fields=tuple(required_fields)))
+
+    def _rename_camel_columns_to_snake_case(self, df: pd.DataFrame) -> pd.DataFrame:
+        def camel_to_snake_case(column):
+            # Replace periods with underscores
+            column = column.replace('.', '_')
+            # Insert underscores before capital letters and convert to lowercase
+            return re.sub(r'(?<!^)(?=[A-Z])', '_', column).lower()
+
+        df.columns = map(camel_to_snake_case, df.columns)
+
+        return df
+
+    def flat_dict_to_nested_dict(self, flat_dict: dict, model: BaseModel) -> dict:
+        nested = {}
+        for name, field in model.model_fields.items():
+            key_in_input = name  # Original model field name as key in flat_dict
+            alias = field.alias or name
+            if isinstance(field.annotation, type) and issubclass(field.annotation, BaseModel):
+                nested[alias] = self.flat_dict_to_nested_dict(flat_dict, field.annotation)
+            elif any(isinstance(item, type) and issubclass(item, BaseModel) for item in get_args(field.annotation)):
+                # get the basemodel class from the list
+                nested_model_name = [item for item in get_args(field.annotation) if isinstance(item, type) and issubclass(item, BaseModel)][0]
+                origin = get_origin(field.annotation)
+                if origin in (list, List):
+                    nested[alias] = [self.flat_dict_to_nested_dict(flat_dict, nested_model_name)]
+                else:
+                    nested[alias] = self.flat_dict_to_nested_dict(flat_dict, nested_model_name)
+            else:
+                if key_in_input in flat_dict:
+                    nested[alias] = flat_dict[key_in_input]
+        return nested

brynq_sdk_nmbrs/absence.py

@@ -0,0 +1,124 @@
+from typing import Any, Dict, List, Union, Tuple
+import pandas as pd
+from .schemas.absence import AbsenceCreate, AbsenceGet
+from zeep.exceptions import Fault
+from zeep.ns import WSDL, SOAP_ENV_11
+from zeep.xsd import ComplexType, Element, String
+from zeep.helpers import serialize_object
+# import logging
+from brynq_sdk_functions import Functions
+
+
+class Absence:
+    def __init__(self, nmbrs):
+        self.nmbrs = nmbrs
+        self.soap_client_companies = nmbrs.soap_client_companies
+        self.soap_client_employees = nmbrs.soap_client_employees
+
+    def get(self, employee_id: int = None) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Get salary tables for all companies for a specific period and year.
+
+        Args:
+            period (int): The period number
+            year (int): The year
+
+        Returns:
+            pd.DataFrame: DataFrame containing the salary tables
+        """
+        absences = pd.DataFrame()
+        for company in self.nmbrs.soap_company_ids.to_dict(orient='records'):
+            absences_temp = self._get(company['i_d'], employee_id=employee_id)
+            if not absences_temp.empty:
+                absences_temp['companyId'] = company['number']
+                absences = pd.concat([absences, absences_temp])
+
+        valid_absences, invalid_absences = Functions.validate_data(df=absences, schema=AbsenceGet, debug=True)
+
+        # No validation schema for now, but could be added later
+        return valid_absences, invalid_absences
+
+    def _get(self, company_id: int, employee_id: int = None) -> pd.DataFrame:
+        """
+        Get all absences for a specific company, period and year.
+
+        Args:
+            company_id (int): The ID of the company
+            period (int): The period number
+            year (int): The year
+
+        Returns:
+            pd.DataFrame: DataFrame containing the salary tables
+        """
+        try:
+            if employee_id is None:
+                response = self.soap_client_employees.service.Absence_GetAll_AllEmployeesByCompany(
+                    CompanyId=company_id,
+                    _soapheaders=[self.nmbrs.soap_auth_header]
+                )
+            else:
+                # Make SOAP request with the proper header structure
+                response = self.soap_client_employees.service.Absence_GetList(
+                    EmployeeId=employee_id,
+                    _soapheaders=[self.nmbrs.soap_auth_header]
+                )
+
+            # Convert response to DataFrame
+            if response:
+                # Convert Zeep objects to Python dictionaries
+                serialized_response = serialize_object(response)
+
+                # Convert to list if it's not already
+                if not isinstance(serialized_response, list):
+                    serialized_response = [serialized_response]
+
+                # Convert to DataFrame
+                df = pd.DataFrame(serialized_response)
+
+                return df
+            else:
+                return pd.DataFrame()
+
+        except Fault as e:
+            raise Exception(f"SOAP request failed: {str(e)}")
+        except Exception as e:
+            raise Exception(f"Failed to get salary tables: {str(e)}")
+
+    def create(self, data: Dict[str, Any]) -> pd.DataFrame:
+        try:
+            absence_model = AbsenceCreate(**data)
+
+            if self.nmbrs.mock_mode:
+                return absence_model
+
+            # Use the model's built-in SOAP conversion method
+            absence_settings = absence_model.to_soap_settings(self.nmbrs.soap_client_employees)
+
+            # Make SOAP request with clean, simple call
+            response = self.nmbrs.soap_client_employees.service.Absence_Create(
+                EmployeeId=absence_model.employee_id,
+                Dossier=absence_model.new_dossier,
+                Absence=absence_settings,
+                _soapheaders=[self.nmbrs.soap_auth_header]
+            )
+
+            # Convert response to DataFrame
+            if response:
+                # Convert Zeep objects to Python dictionaries
+                serialized_response = serialize_object(response)
+
+                # Convert to list if it's not already
+                if not isinstance(serialized_response, list):
+                    serialized_response = [serialized_response]
+
+                # Convert to DataFrame
+                df = pd.DataFrame(serialized_response)
+
+                return df
+            else:
+                return pd.DataFrame()
+
+        except Fault as e:
+            raise Exception(f"SOAP request failed: {str(e)}")
+        except Exception as e:
+            raise Exception(f"Failed to update WageTax: {str(e)}")

brynq_sdk_nmbrs/address.py

@@ -0,0 +1,66 @@
+import pandas as pd
+import requests
+from typing import Dict, Any
+from .schemas.address import AddressCreate, AddressGet, Period
+from brynq_sdk_functions import Functions
+
+class Address:
+    def __init__(self, nmbrs):
+        self.nmbrs = nmbrs
+
+    def get(self,
+            created_from: str = None) -> pd.DataFrame:
+        addresses = pd.DataFrame()
+        for company in self.nmbrs.company_ids:
+            addresses = pd.concat([addresses, self._get(company, created_from)])
+
+        valid_addresses, invalid_addresses = Functions.validate_data(df=addresses, schema=AddressGet, debug=True)
+
+        return valid_addresses, invalid_addresses
+
+    def _get(self,
+            company_id: str,
+            created_from: str = None) -> pd.DataFrame:
+        params = {} if created_from is None else {'createdFrom': created_from}
+        request = requests.Request(method='GET',
+                                   url=f"{self.nmbrs.base_url}companies/{company_id}/employees/addresses",
+                                   params=params)
+
+        data = self.nmbrs.get_paginated_result(request)
+        df = pd.json_normalize(
+            data,
+            record_path='addresses',
+            meta=['employeeId']
+        )
+
+        return df
+
+    def create(self, employee_id: str, data: Dict[str, Any]):
+        """
+        Create a new address for an employee using Pydantic validation.
+
+        Args:
+            employee_id: The ID of the employee
+            data: Dictionary containing address data with fields matching
+                 the AddressCreate schema (using camelCase field names)
+
+        Returns:
+            Response from the API
+        """
+        # Validate with Pydantic model - this will raise an error if required fields are missing
+        nested_data = self.nmbrs.flat_dict_to_nested_dict(data, AddressCreate)
+        address_model = AddressCreate(**nested_data)
+
+        if self.nmbrs.mock_mode:
+            return address_model
+
+        # Convert validated model to dict for API payload
+        payload = address_model.model_dump(exclude_none=True, by_alias=True)
+
+        # Send request
+        resp = self.nmbrs.session.post(
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/address",
+            json=payload,
+            timeout=self.nmbrs.timeout
+        )
+        return resp

brynq_sdk_nmbrs/bank.py

@@ -0,0 +1,125 @@
+import math
+import pandas as pd
+import requests
+from brynq_sdk_functions import Functions
+from typing import Dict, Any
+from .schemas.bank import BankGet, BankCreate, BankUpdate, BankDelete
+
+
+class Bank:
+    def __init__(self, nmbrs):
+        self.nmbrs = nmbrs
+
+    def get(self,
+            created_from: str = None) -> tuple[pd.DataFrame, pd.DataFrame]:
+        banks = pd.DataFrame()
+        for company in self.nmbrs.company_ids:
+            banks = pd.concat([banks, self._get(company, created_from)])
+
+        valid_banks, invalid_banks = Functions.validate_data(df=banks, schema=BankGet, debug=True)
+
+        return valid_banks, invalid_banks
+
+    def _get(self,
+            company_id: str,
+            created_from: str = None) -> pd.DataFrame:
+        params = {}
+        if created_from:
+            params['createdFrom'] = created_from
+        try:
+            request = requests.Request(method='GET',
+                                       url=f"{self.nmbrs.base_url}companies/{company_id}/employees/bankaccounts",
+                                       params=params)
+
+            data = self.nmbrs.get_paginated_result(request)
+            df = pd.json_normalize(
+                data,
+                record_path='bankAccounts',
+                meta=['employeeId']
+            )
+        except requests.HTTPError as e:
+            df = pd.DataFrame()
+
+        return df
+
+    def create(self, employee_id: str, data: Dict[str, Any]):
+        """
+        Create a new bank account for an employee using Pydantic validation.
+
+        Args:
+            employee_id: The ID of the employee
+            data: Dictionary containing bank account data in the format matching BankCreate schema
+
+        Returns:
+            Response from the API
+        """
+        # Validate with Pydantic model - this will raise an error if required fields are missing
+        nested_data = self.nmbrs.flat_dict_to_nested_dict(data, BankCreate)
+        bank_model = BankCreate(**nested_data)
+
+        if self.nmbrs.mock_mode:
+            return bank_model
+
+        # Convert validated model to dict for API payload
+        payload = bank_model.model_dump(exclude_none=True, by_alias=True)
+
+        # Send request
+        resp = self.nmbrs.session.post(
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/bankaccount",
+            json=payload,
+            timeout=self.nmbrs.timeout
+        )
+        return resp
+
+    def update(self, employee_id: str, data: Dict[str, Any]):
+        """
+        Update a bank account for an employee using Pydantic validation.
+
+        Args:
+            employee_id: The ID of the employee
+            data: Dictionary containing bank account data in the format matching BankUpdate schema
+
+        Returns:
+            Response from the API
+        """
+        # Validate with Pydantic model - this will raise an error if required fields are missing
+        nested_data = self.nmbrs.flat_dict_to_nested_dict(data, BankUpdate)
+        bank_model = BankUpdate(**nested_data)
+
+        if self.nmbrs.mock_mode:
+            return bank_model
+
+        # Convert validated model to dict for API payload
+        payload = bank_model.model_dump(exclude_none=True, by_alias=True)
+
+        # Send request
+        resp = self.nmbrs.session.put(
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/bankaccount",
+            json=payload,
+            timeout=self.nmbrs.timeout
+        )
+        return resp
+
+    def delete(self, employee_id: str, bank_account_id: str):
+        """
+        Delete a bank account for an employee.
+
+        Args:
+            employee_id: The ID of the employee
+            bank_account_id: The ID of the bank account to delete
+
+        Returns:
+            Response from the API
+        """
+        # Create and validate a BankDelete model
+        bank_model = BankDelete(bankAccountId=bank_account_id)
+
+        if self.nmbrs.mock_mode:
+            return bank_model
+
+        # Send request
+        resp = self.nmbrs.session.delete(
+            url=f"{self.nmbrs.base_url}employees/{employee_id}/bankaccounts/{bank_account_id}",
+            timeout=self.nmbrs.timeout
+        )
+        return resp

brynq_sdk_nmbrs/children.py

@@ -0,0 +1,100 @@
+from datetime import datetime
+
+from zeep import Client
+from zeep.transports import Transport
+import requests
+import pandas as pd
+
+
+class Children:
+    def __init__(self, nmbrs):
+        self.nmbrs = nmbrs
+        self.client = Client(wsdl='https://api.nmbrs.nl/soap/v3/EmployeeService.asmx?wsdl') #, transport=Transport(session=self.nmbrs.session))
+        # self.client.set_default_soapheaders([auth_header])
+        AuthHeaderWithDomainType = self.client.get_element('ns0:AuthHeaderWithDomain')
+
+        auth_header = AuthHeaderWithDomainType(
+            Username="erwin.vink@brynq.com",
+            Token="cc358715f5c14cda8add964deef99ba3",
+            Domain="extdev-brynq"
+        )
+        self.client.set_default_soapheaders([auth_header])
+
+    def get(self,
+            company_id: str,
+            created_from: str = None) -> pd.DataFrame:
+        params = {}
+        if created_from:
+            params['createdFrom'] = created_from
+        try:
+            request = requests.Request(method='GET',
+                                       url=f"{self.nmbrs.base_url}companies/{company_id}/employees/functions",
+                                       params=params)
+
+            data = self.nmbrs.get_paginated_result(request)
+            df = pd.json_normalize(
+                data,
+                record_path='functions',
+                meta=['employeeId']
+            )
+        except requests.HTTPError as e:
+            df = pd.DataFrame()
+
+        return df
+
+
+    def create(self,
+               employee_id: str,
+               data: dict):
+
+        required_fields = ["first_name", "period", "function_id"]
+        allowed_fields = {}
+        # self.nmbrs.check_fields(data=data, required_fields=required_fields, allowed_fields=list(allowed_fields.keys()))
+
+        ChildType = self.client.get_type('ns0:Child')
+        child = ChildType(
+            Id=1,  # Use 0 or omit if adding a new child
+            Name='Doe',
+            FirstName='John',
+            Initials='J.D.',
+            Gender='male',  # Options: 'male', 'female', 'unknown', 'undefined'
+            Birthday=datetime(2020, 1, 1)  # Using a datetime object
+        )
+
+        # Make the API call
+        result = self.client.service.Children_Insert(
+            EmployeeId=employee_id,
+            child=child
+        )
+        print("Child inserted successfully. Result:", result)
+
+
+# <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:emp="https://api.nmbrs.nl/soap/v3/EmployeeService">
+#    <soap:Header>
+#       <emp:AuthHeaderWithDomain>
+#          <!--Optional:-->
+#          <emp:Username>erwin.vink@brynq.com</emp:Username>
+#          <!--Optional:-->
+#          <emp:Token>cc358715f5c14cda8add964deef99ba3</emp:Token>
+#          <!--Optional:-->
+#          <emp:Domain>extdev-brynq</emp:Domain>
+#       </emp:AuthHeaderWithDomain>
+#    </soap:Header>
+#    <soap:Body>
+#       <emp:Children_Insert>
+#          <emp:EmployeeId>11</emp:EmployeeId>
+#          <!--Optional:-->
+#          <emp:child>
+#             <emp:Id>1</emp:Id>
+#             <!--Optional:-->
+#             <emp:Name>Doe</emp:Name>
+#             <!--Optional:-->
+#             <emp:FirstName>John</emp:FirstName>
+#             <!--Optional:-->
+#             <emp:Initials>J.</emp:Initials>
+#             <emp:Gender>male</emp:Gender>
+#             <emp:Birthday>2020-01-01T00:00:00</emp:Birthday>
+#          </emp:child>
+#       </emp:Children_Insert>
+#    </soap:Body>
+# </soap:Envelope>