brynq-sdk-acerta 1.0.0__tar.gz

brynq_sdk_acerta-1.0.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 1.0
+Name: brynq_sdk_acerta
+Version: 1.0.0
+Summary: Acerta wrapper from BrynQ
+Home-page: UNKNOWN
+Author: BrynQ
+Author-email: support@brynq.com
+License: BrynQ License
+Description: Acerta wrapper from BrynQ
+Platform: UNKNOWN

brynq_sdk_acerta-1.0.0/README.md

@@ -0,0 +1,137 @@
+# BrynQ SDK - Acerta
+
+Python SDK for interacting with the Acerta HR & Payroll API.
+
+## Overview
+
+The Acerta SDK provides a clean and intuitive interface to interact with Acerta's HR and payroll management system. Built on top of the BrynQ platform, it offers seamless integration with validated data handling using Pandera and Pydantic.
+
+## Features
+
+- 🔐 **Secure Authentication**: Bearer token-based authentication with automatic credential management
+- 🌍 **Multi-Environment Support**: Easily switch between test and production environments
+- ✅ **Data Validation**: Built-in validation using Pandera (GET) and Pydantic (POST/PUT/PATCH)
+- 📊 **Pandas Integration**: GET operations return validated DataFrames for easy data manipulation
+- 🔄 **Complete CRUD Operations**: Full support for Create, Read, Update, and Delete operations
+
+## Installation
+
+```bash
+pip install brynq-sdk-acerta
+```
+
+## Quick Start
+
+```python
+from brynq_sdk_acerta import Acerta
+
+# Initialize client (debug=True for test environment)
+client = Acerta(system_type="source", debug=False)
+
+# Get employees
+employees_df, invalid_df = client.employees.get()
+
+# Get planning data
+planning_df, invalid_df = client.planning.get()
+
+# Create new employee
+employee_data = {
+    "firstName": "John",
+    "lastName": "Doe",
+    "email": "john.doe@example.com"
+}
+response = client.employees.create(employee_data)
+```
+
+## Available Resources
+
+### Core Resources
+- **`employees`** - Employee management (includes addresses, contact information, family, bank accounts)
+- **`employment`** - Employment contracts and relationships
+- **`employer`** - Employer information and cost centers
+- **`agreements`** - Employment agreements and contracts
+- **`planning`** - Workforce planning and scheduling
+
+### Nested Resources
+Access nested resources through their parent:
+```python
+# Employee sub-resources
+client.employees.addresses
+client.employees.contact_information
+client.employees.family
+client.employees.bank_accounts
+
+# Employer sub-resources
+client.employer.cost_centers
+```
+
+## Environment Configuration
+
+The SDK supports two environments:
+
+- **Production**: `https://api.acerta.be`
+- **Test**: `https://a-api.acerta.be` (enabled with `debug=True`)
+
+```python
+# Production environment
+client = Acerta(system_type="source", debug=False)
+
+# Test environment
+client = Acerta(system_type="source", debug=True)
+```
+
+## Data Validation
+
+### GET Operations
+Returns a tuple of two DataFrames:
+- **Valid data**: Successfully validated records
+- **Invalid data**: Records that failed validation with error details
+
+```python
+valid_df, invalid_df = client.employees.get()
+print(f"Valid records: {len(valid_df)}")
+print(f"Invalid records: {len(invalid_df)}")
+```
+
+### POST/PUT/PATCH Operations
+Data is automatically validated against Pydantic schemas before sending:
+
+```python
+# Data is validated before the request
+response = client.employees.create({
+    "firstName": "Jane",
+    "lastName": "Smith",
+    "dateOfBirth": "1990-01-15"
+})
+```
+
+## Error Handling
+
+The SDK includes comprehensive error handling with descriptive messages:
+
+```python
+try:
+    response = client.employees.create(employee_data)
+    if response.status_code == 201:
+        print("Employee created successfully")
+except Exception as e:
+    print(f"Error: {str(e)}")
+```
+
+## Requirements
+
+- Python 3.8+
+- pandas >= 2.2.0
+- pydantic >= 2.5.0
+- pandera >= 0.16.0
+- requests >= 2.25.1
+- brynq-sdk-functions >= 2.0.5
+- brynq-sdk-brynq >= 3
+
+## Support
+
+For issues, questions, or contributions, please contact BrynQ support at support@brynq.com
+
+## License
+
+BrynQ License - © BrynQ

brynq_sdk_acerta-1.0.0/brynq_sdk_acerta/__init__.py

@@ -0,0 +1,13 @@
+"""
+Brynq SDK for Acerta API integration
+"""
+
+from .acerta import Acerta
+from .agreements import Agreements
+from .employees import Employees
+from .code_lists import CodeLists
+from .employer import Employer
+from .employees_additional_information import EmployeesAdditionalInformation
+from .inservice import InService
+
+__all__ = ['Acerta', 'CodeLists', 'Agreements', 'Employees', 'Employer', 'InService', 'EmployeesAdditionalInformation']

brynq_sdk_acerta-1.0.0/brynq_sdk_acerta/acerta.py

@@ -0,0 +1,116 @@
+from typing_extensions import List
+from typing import Literal, Optional, Union
+import time
+
+from .salaries import Salaries
+from .cost_centers import CostCenters
+from brynq_sdk_brynq import BrynQ
+from .code_lists import CodeLists
+from .agreements import Agreements
+from .inservice import InService
+from .employees import Employees
+from .employer import Employer
+from requests_oauthlib import OAuth2Session
+from oauthlib.oauth2 import BackendApplicationClient
+
+
+class Acerta(BrynQ):
+    """
+    Base class for interacting with the Acerta API.
+    """
+
+    # Default timeout in seconds for all requests
+    TIMEOUT = 30
+
+    def __init__(self, employers: Union[str, List], system_type: Optional[Literal['source', 'target']] = None, test_environment: bool = True, debug: bool = False):
+        """
+        Initialize the Acerta API client.
+
+        Args:
+            system_type (str): System type ('source' or 'target')
+            debug (bool): Debug flag - if True uses test environment, if False uses production
+        """
+        super().__init__()
+
+        # Compute environment-specific prefix once and reuse
+        env_prefix = "a-" if test_environment else ""
+        self.base_url = f"https://{env_prefix}api.acerta.be"
+
+        # Extract credentials and configure OAuth2 session with automatic token renewal
+        credentials = self.interfaces.credentials.get(
+            system="acerta-acceptance",
+            system_type=system_type,
+        )
+        data = credentials.get("data", {})
+        client_id = data.get("client_id")
+        client_secret = data.get("client_secret")
+
+        # Token endpoint (match test/prod like base_url)
+        token_url = f"https://{env_prefix}signin.acerta.be/am/oauth2/access_token"
+
+        # Store client credentials for reuse
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._token_url = token_url
+
+        # Create OAuth2 session using client credentials (Backend Application flow)
+        client = BackendApplicationClient(client_id=self._client_id)
+        oauth_session = OAuth2Session(client=client)
+
+        # Fetch initial token
+        token = oauth_session.fetch_token(
+            token_url=self._token_url,
+            client_id=self._client_id,
+            client_secret=self._client_secret,
+            include_client_id=True,
+        )
+
+        # Keep access_token attribute for backward compatibility
+        self.access_token = token.get("access_token")
+
+        # Attach default headers; Authorization is managed by OAuth2Session
+        oauth_session.headers.update({
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        })
+
+        # Ensure token is valid before each request (client_credentials has no refresh_token)
+        self._orig_request = oauth_session.request
+        oauth_session.request = self._request_with_pre_expiry  # type: ignore[assignment]
+
+        # Use the OAuth2 session for all requests
+        self.session = oauth_session
+        self.session.timeout = self.TIMEOUT  # type: ignore[attr-defined]
+        self._employer_ids = employers if isinstance(employers, List) else [employers]
+        self._employee_ids = set()
+        self._agreement_ids = set()
+
+        # Set debug mode
+        self.debug = debug
+
+        # Initialize resource classes
+        self.agreements = Agreements(self)
+        self.inservice = InService(self)
+        self.cost_centers = CostCenters(self)
+        self.code_lists = CodeLists(self)
+        self.employees = Employees(self)
+        self.employers = Employer(self)
+        self.salaries = Salaries(self)
+
+    def _ensure_valid_token(self):
+        """Ensure the OAuth token exists and is not about to expire."""
+        tok = getattr(self.session, "token", {}) or {}
+        expires_at = tok.get("expires_at")
+        # Refresh if missing or expiring within 30 seconds
+        if not expires_at or (expires_at - time.time()) < 30:
+            new_token = self.session.fetch_token(
+                token_url=self._token_url,
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+                include_client_id=True,
+            )
+            self.access_token = new_token.get("access_token")
+
+    def _request_with_pre_expiry(self, method, url, **kwargs):
+        self._ensure_valid_token()
+        return self._orig_request(method, url, **kwargs)

brynq_sdk_acerta-1.0.0/brynq_sdk_acerta/addresses.py

@@ -0,0 +1,99 @@
+from typing import Tuple, Dict, Any
+import pandas as pd
+import requests
+from brynq_sdk_functions import Functions
+from .schemas.address import AddressGet, AddressUpdate
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+	from .acerta import Acerta
+
+class Addresses:
+	"""Resource class for Employee Address endpoints"""
+
+	def __init__(self, acerta):
+		self.acerta: Acerta = acerta
+		self.base_uri = "v3/employee-data-management/v3/employees"
+
+	def get(self, from_date: str = "1900-01-01", until_date: str = "9999-12-31") -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""
+		GET /employee-data-management/v3/employees/{employeeId}/addresses - Employee Addresses
+
+		Retrieve employee address history within a specified time window for all cached employees.
+		Returns both official and correspondence addresses with their validity periods.
+
+		Args:
+			from_date: Start date of the time window (default: "1900-01-01")
+			until_date: End date of the time window (default: "9999-12-31")
+
+		Returns:
+			Tuple[pd.DataFrame, pd.DataFrame]: (valid_df, invalid_df) after validation
+
+		Raises:
+			RuntimeError: If the retrieval fails
+		"""
+		params = {
+			"fromDate": from_date,
+			"untilDate": until_date
+		}
+
+		if not self.acerta._employee_ids:
+			# Auto-warm cache by fetching agreements (populates employee IDs)
+			self.acerta.agreements.get()
+
+		all_frames = []
+		for employee_id in self.acerta._employee_ids:
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{employee_id}/addresses",
+				params=params,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			content = response.json()
+			df = pd.json_normalize(
+				content,
+				record_path=['addressSegments'],
+				meta=['employeeId'],
+				sep='.'
+			)
+			if 'externalReferences' in df.columns:
+				df = df.drop(columns=['externalReferences'])
+			all_frames.append(df)
+
+		combined = pd.concat(all_frames, ignore_index=True) if all_frames else pd.DataFrame()
+
+		valid_data, invalid_data = Functions.validate_data(combined, AddressGet)
+
+		return valid_data, invalid_data
+
+	def update(self, employee_id: str, data: Dict[str, Any]) -> requests.Response:
+		"""
+		PATCH /employee-data-management/v3/employees/{employeeId}/addresses - Employee Address
+
+		Update employee address information including official address and optional
+		correspondence address. Addresses are historical data with validity dates.
+
+		Args:
+			employee_id: Unique identifier of an employee
+			data: Flat dictionary with address data
+
+		Returns:
+			requests.Response: Raw response object
+
+		Raises:
+			RuntimeError: If the address update fails
+		"""
+		# Convert flat data to nested using Functions.flat_to_nested_with_prefix
+		nested_data = Functions.flat_to_nested_with_prefix(data, AddressUpdate)
+
+		# Validate the nested data
+		validated_data = AddressUpdate(**nested_data)
+
+		# Make API request
+		response = self.acerta.session.patch(
+			url=f"{self.acerta.base_url}/{self.base_uri}/{employee_id}/addresses",
+			json=validated_data.model_dump(by_alias=True, exclude_none=True),
+			timeout=self.acerta.TIMEOUT,
+		)
+		response.raise_for_status()
+
+		return response