brynq-sdk-acerta 1.1.1__py3-none-any.whl

brynq_sdk_acerta/__init__.py

@@ -0,0 +1,14 @@
+"""
+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
+from .company_cars import CompanyCars
+
+__all__ = ['Acerta', 'CodeLists', 'Agreements', 'Employees', 'Employer', 'InService', 'EmployeesAdditionalInformation', 'CompanyCars']

brynq_sdk_acerta/acerta.py

@@ -0,0 +1,118 @@
+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 .company_cars import CompanyCars
+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)
+        self.company_cars = CompanyCars(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/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

brynq_sdk_acerta/agreements.py

@@ -0,0 +1,426 @@
+from typing import Dict, Any, Optional, Tuple
+import requests
+import pandas as pd
+from .schemas.agreement import (
+    AgreementGet,
+    PatchAgreementRequest,
+    AgreementBasicInformationGet,
+    AgreementEmploymentsGet,
+    AgreementWorkingTimeGet,
+    AgreementCommutingGet,
+    AgreementCustomFieldsGet,
+    AgreementCostCenterAllocationGet,
+)
+from .schemas.in_service_config import JointCommitteeGet, FunctionGet
+from brynq_sdk_functions import Functions
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+	from .acerta import Acerta
+
+class Agreements:
+	"""Resource class for Agreement endpoints"""
+
+	def __init__(self, acerta):
+		self.acerta: Acerta = acerta
+		self.base_uri = "agreement-data-management/v3/agreements"
+		# We cache agreements to avoid duplicate requests. Agreements always need to be fetched in order to get employee_ids.
+		# For ease of use, we do that in the background, so you can retrieve employees without having to fetch agreements first.
+		# To avoid retrieving agreements twice, we cache them so we can return them if they are already cached.
+		self._cached_agreements = None
+
+	def get_joint_committees(self, employer_id: Optional[str] = None, in_service_type: Optional[str] = None, accept_language: str = "en") -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""
+		GET /employee-in-service-request/v1/employers/{employerId}/joint-committees
+		"""
+		employers = [employer_id] if employer_id else self.acerta._employer_ids
+		all_rows = []
+		for emp_id in employers:
+			params = {"Accept-Language": accept_language}
+			if in_service_type:
+				params["inServiceType"] = in_service_type
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/employee-in-service-request/v1/employers/{emp_id}/joint-committees",
+				params=params,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			items = raw.get("_embedded", {}).get("jointCommittees", [])
+			if items:
+				df = pd.json_normalize(items)
+				df["employer_id"] = emp_id
+				all_rows.append(df)
+		combined = pd.concat(all_rows, ignore_index=True) if all_rows else pd.DataFrame()
+		return Functions.validate_data(combined, JointCommitteeGet)
+
+	def get_functions(self, employer_id: Optional[str] = None, accept_language: str = "en") -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""
+		GET /employee-in-service-request/v1/employers/{employerId}/functions
+		"""
+		employers = [employer_id] if employer_id else self.acerta._employer_ids
+		all_rows = []
+		for emp_id in employers:
+			params = {"Accept-Language": accept_language}
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/employee-in-service-request/v1/employers/{emp_id}/functions",
+				params=params,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			items = raw.get("_embedded", {}).get("functions", [])
+			if items:
+				df = pd.json_normalize(items)
+				df["employer_id"] = emp_id
+				all_rows.append(df)
+		combined = pd.concat(all_rows, ignore_index=True) if all_rows else pd.DataFrame()
+		return Functions.validate_data(combined, FunctionGet)
+
+
+	def get(self) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""
+		GET /v3/agreements - Agreements
+
+		Retrieve agreements for all configured employer IDs. Returns agreement details including
+		agreement ID, employer information, legal entity, and agreement type.
+
+		Behavior:
+			- Aggregates results across `self.acerta._employer_ids`
+			- Validates and splits into valid/invalid DataFrames
+			- Updates `self.acerta._employee_ids` and `_agreement_ids`
+			- Caches results on first call within this instance
+
+		Returns:
+			Tuple[pd.DataFrame, pd.DataFrame]: (valid_df, invalid_df)
+
+		Raises:
+			Exception: If retrieval or validation fails
+		"""
+		if self._cached_agreements is None:
+			self._cached_agreements = self._get_agreements()
+		return self._cached_agreements
+
+	def _get_agreements(self):
+		all_dfs = []
+		for employer in self.acerta._employer_ids:
+			page = 0
+			total_pages = 1
+
+			while page < total_pages:
+				params = {k: v for k, v in {
+					"employerId": employer,
+					"page": page,
+					"size": 200,
+				}.items() if v is not None}
+
+				response = self.acerta.session.get(
+					url=f"{self.acerta.base_url}/{self.base_uri}",
+					params=params,
+					timeout=self.acerta.TIMEOUT,
+				)
+				response.raise_for_status()
+
+				agreements_data = response.json().get("_embedded", {}).get("agreements", [])
+				if agreements_data:
+					df = pd.json_normalize(agreements_data, sep=".")
+					all_dfs.append(df)
+
+				page_info = response.json().get("page") or {}
+				total_pages = max(total_pages, page_info.get("totalPages", total_pages))
+				page += 1
+
+		agreements = pd.concat(all_dfs, ignore_index=True) if all_dfs else pd.DataFrame()
+		valid_agreements, invalid_agreements = Functions.validate_data(agreements, AgreementGet, debug=self.acerta.debug)
+
+		if not valid_agreements.empty:
+			self.acerta._employee_ids.update(valid_agreements["employee_id"].dropna().unique())
+			self.acerta._agreement_ids.update(valid_agreements["agreement_id"].dropna().unique())
+
+		return valid_agreements, invalid_agreements
+
+	def get_by_id(self, agreement_id: str, accept_language: str = "en") -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}"""
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		request_headers = self.acerta.session.headers.copy()
+		if headers:
+			request_headers.update(headers)
+		response = self.acerta.session.get(
+			url=f"{self.acerta.base_url}/{self.base_uri}/{agreement_id}",
+			headers=request_headers,
+			timeout=self.acerta.TIMEOUT,
+		)
+		response.raise_for_status()
+		raw = response.json()
+		if isinstance(raw, dict):
+			df = pd.json_normalize(raw, sep=".")
+		else:
+			df = pd.json_normalize([raw], sep=".")
+		return df, pd.DataFrame()
+
+	def update(self, agreement_id: str, data: Dict[str, Any], accept_language: str = "en") -> requests.Response:
+		"""PATCH /v3/agreements/{agreementId}"""
+		nested_data = Functions.flat_to_nested_with_prefix(data, PatchAgreementRequest)
+		validated = PatchAgreementRequest(**nested_data)
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		request_headers = self.acerta.session.headers.copy()
+		if headers:
+			request_headers.update(headers)
+		response = self.acerta.session.patch(
+			url=f"{self.acerta.base_url}/{self.base_uri}/{agreement_id}",
+			json=validated.model_dump(by_alias=True, exclude_none=True),
+			headers=request_headers,
+			timeout=self.acerta.TIMEOUT,
+		)
+		response.raise_for_status()
+		return response
+
+	def get_basic_information(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		full_segments_only: Optional[bool] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/basic-information"""
+		params = {k: v for k, v in {
+			"fromDate": from_date,
+			"untilDate": until_date,
+			"fullSegmentsOnly": str(full_segments_only).lower() if isinstance(full_segments_only, bool) else full_segments_only,
+		}.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/basic-information",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["basicInformationSegments"],
+				meta=["agreementId", ["agreementType", "code"], ["agreementType", "description"]],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementBasicInformationGet, debug=self.acerta.debug)
+
+	def get_employments(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/employments"""
+		params = {k: v for k, v in {
+			"fromDate": from_date,
+			"untilDate": until_date,
+		}.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/employments",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["employments"],
+				meta=["agreementId"],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementEmploymentsGet, debug=self.acerta.debug)
+
+	def get_working_time(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		full_segments_only: Optional[bool] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/working-time"""
+		params = {k: v for k, v in {
+			"fromDate": from_date,
+			"untilDate": until_date,
+			"fullSegmentsOnly": str(full_segments_only).lower() if isinstance(full_segments_only, bool) else full_segments_only,
+		}.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/working-time",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["workingTimeSegments"],
+				meta=["agreementId"],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementWorkingTimeGet, debug=self.acerta.debug)
+
+
+	def get_commuting(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		full_segments_only: Optional[bool] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/commuting"""
+		params = {k: v for k, v in {
+			"fromDate": from_date,
+			"untilDate": until_date,
+			"fullSegmentsOnly": str(full_segments_only).lower() if isinstance(full_segments_only, bool) else full_segments_only,
+		}.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/commuting",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["commutingSegments"],
+				meta=["agreementId"],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementCommutingGet, debug=self.acerta.debug)
+
+	def get_custom_fields(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		custom_field_names: Optional[list] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/custom-fields"""
+		params_dict: Dict[str, Any] = {
+			"fromDate": from_date,
+			"untilDate": until_date,
+		}
+		if custom_field_names:
+			params_dict["customFieldNames"] = ",".join(str(x) for x in custom_field_names)
+		params = {k: v for k, v in params_dict.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/custom-fields",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["customFieldsSegments"],
+				meta=["agreementId"],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementCustomFieldsGet, debug=self.acerta.debug)
+
+	def get_cost_center_allocation(
+		self,
+		agreement_id: Optional[str] = None,
+		from_date: Optional[str] = None,
+		until_date: Optional[str] = None,
+		accept_language: str = "en",
+	) -> Tuple[pd.DataFrame, pd.DataFrame]:
+		"""GET /v3/agreements/{agreementId}/cost-center-allocation"""
+		params = {k: v for k, v in {
+			"fromDate": from_date,
+			"untilDate": until_date,
+		}.items() if v is not None}
+		if not agreement_id and not self.acerta._agreement_ids:
+			self.get()
+		ids = [agreement_id] if agreement_id else self.acerta._agreement_ids
+		frames = []
+		headers = {"Accept-Language": accept_language} if accept_language else None
+		for agr_id in ids:
+			request_headers = self.acerta.session.headers.copy()
+			if headers:
+				request_headers.update(headers)
+			response = self.acerta.session.get(
+				url=f"{self.acerta.base_url}/{self.base_uri}/{agr_id}/cost-center-allocation",
+				params=params,
+				headers=request_headers,
+				timeout=self.acerta.TIMEOUT,
+			)
+			response.raise_for_status()
+			raw = response.json()
+			df = pd.json_normalize(
+				raw,
+				record_path=["costCenterAllocation"],
+				meta=["agreementId"],
+				errors="ignore",
+				sep=".",
+			)
+			frames.append(df)
+		combined = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame()
+		return Functions.validate_data(combined, AgreementCostCenterAllocationGet, debug=self.acerta.debug)