merit-api 0.4.4__py3-none-any.whl

merit_api/__init__.py

@@ -0,0 +1,4 @@
+from .client import MeritAPI
+from .exceptions import MeritAPIError
+
+__all__ = ["MeritAPI", "MeritAPIError"]

merit_api/client.py

@@ -0,0 +1,410 @@
+import base64
+import hashlib
+import hmac
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+import requests
+
+from .exceptions import MeritAPIError
+from .namespaces import (
+    Assets,
+    Customers,
+    Dimensions,
+    Financial,
+    Inventory,
+    Items,
+    Purchases,
+    Pricing,
+    ReferenceData,
+    Reports,
+    Sales,
+    Taxes,
+    Vendors,
+)
+
+
+JsonDict = Dict[str, Any]
+LoggerCallback = Callable[[JsonDict], None]
+IdempotencyKeyFactory = Callable[[str, Any], Optional[str]]
+
+
+class MeritAPI:
+    """Python client for Merit Aktiva API."""
+
+    BASE_URLS = {
+        "EE": "https://aktiva.merit.ee/api/",
+        "PL": "https://program.360ksiegowosc.pl/api/",
+    }
+    RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+    def __init__(
+        self,
+        api_id: str,
+        api_key: str,
+        country: str = "EE",
+        *,
+        session: Optional[requests.Session] = None,
+        timeout: float = 30.0,
+        max_retries: int = 0,
+        retry_backoff: float = 0.5,
+        idempotency_key_factory: Optional[IdempotencyKeyFactory] = None,
+        request_logger: Optional[LoggerCallback] = None,
+        response_logger: Optional[LoggerCallback] = None,
+    ):
+        self.api_id = api_id
+        self.api_key = api_key
+        self.base_url = self.BASE_URLS.get(country.upper(), self.BASE_URLS["EE"])
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_backoff = retry_backoff
+        self.idempotency_key_factory = idempotency_key_factory
+        self.request_logger = request_logger
+        self.response_logger = response_logger
+
+        self.customers = Customers(self)
+        self.vendors = Vendors(self)
+        self.items = Items(self)
+        self.sales = Sales(self)
+        self.purchases = Purchases(self)
+        self.financial = Financial(self)
+        self.inventory = Inventory(self)
+        self.assets = Assets(self)
+        self.taxes = Taxes(self)
+        self.dimensions = Dimensions(self)
+        self.pricing = Pricing(self)
+        self.reports = Reports(self)
+        self.reference = ReferenceData(self)
+
+    def _serialize_body(self, body: Any) -> str:
+        """Serialize request bodies deterministically for signing and transport."""
+        return json.dumps(body, separators=(",", ":"), sort_keys=True, ensure_ascii=False)
+
+    def _authenticate(self, serialized_body: str) -> Dict[str, str]:
+        """Generate authentication parameters for a request."""
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        data_to_sign = f"{self.api_id}{timestamp}{serialized_body}"
+        signature_bin = hmac.new(
+            self.api_key.encode("utf-8"),
+            data_to_sign.encode("utf-8"),
+            hashlib.sha256,
+        ).digest()
+        signature_b64 = base64.b64encode(signature_bin).decode("utf-8")
+        return {
+            "apiId": self.api_id,
+            "timestamp": timestamp,
+            "signature": signature_b64,
+        }
+
+    def _resolve_idempotency_key(self, endpoint: str, body: Any, idempotency_key: Optional[str]) -> Optional[str]:
+        if idempotency_key is not None:
+            return idempotency_key
+        if self.idempotency_key_factory is None:
+            return None
+        return self.idempotency_key_factory(endpoint, body)
+
+    def _build_headers(self, serialized_body: str, endpoint: str, body: Any, idempotency_key: Optional[str]) -> JsonDict:
+        headers: JsonDict = {"Content-Type": "application/json"}
+        resolved_idempotency_key = self._resolve_idempotency_key(endpoint, body, idempotency_key)
+        if resolved_idempotency_key:
+            headers["Idempotency-Key"] = resolved_idempotency_key
+        headers["Content-Length"] = str(len(serialized_body.encode("utf-8")))
+        return headers
+
+    def _sanitize_for_log(self, value: Any, *, path: str = "") -> Any:
+        secret_keys = {"signature", "idempotency-key", "authorization", "api_key", "api-key"}
+
+        if isinstance(value, dict):
+            sanitized: JsonDict = {}
+            for key, nested_value in value.items():
+                normalized_key = str(key).lower()
+                nested_path = f"{path}.{key}" if path else str(key)
+                if normalized_key in secret_keys:
+                    sanitized[key] = "***"
+                else:
+                    sanitized[key] = self._sanitize_for_log(nested_value, path=nested_path)
+            return sanitized
+
+        if isinstance(value, list):
+            return [self._sanitize_for_log(item, path=path) for item in value]
+
+        return value
+
+    def _log_request(
+        self,
+        *,
+        url: str,
+        endpoint: str,
+        version: str,
+        body: Any,
+        headers: JsonDict,
+        auth_params: JsonDict,
+        attempt: int,
+    ) -> None:
+        if self.request_logger is None:
+            return
+        self.request_logger(
+            {
+                "url": url,
+                "endpoint": endpoint,
+                "version": version,
+                "body": self._sanitize_for_log(body),
+                "headers": self._sanitize_for_log(headers),
+                "auth_params": self._sanitize_for_log(auth_params),
+                "attempt": attempt,
+            }
+        )
+
+    def _log_response(self, *, url: str, endpoint: str, response: requests.Response, payload: Any = None) -> None:
+        if self.response_logger is None:
+            return
+        event: JsonDict = {
+            "url": url,
+            "endpoint": endpoint,
+            "status_code": response.status_code,
+            "text": response.text,
+        }
+        if payload is not None:
+            event["payload"] = self._sanitize_for_log(payload)
+        self.response_logger(event)
+
+    def _raise_for_business_error(self, payload: Any) -> None:
+        if not isinstance(payload, dict):
+            return
+        if payload.get("Success", True) is not False:
+            return
+
+        error_code = payload.get("ErrorCode")
+        message = payload.get("Error") or payload.get("Message") or "Merit API business error"
+        raise MeritAPIError(
+            str(message),
+            status_code=200,
+            error_code=str(error_code) if error_code is not None else None,
+            response_body=payload,
+        )
+
+    def _post(
+        self,
+        endpoint: str,
+        body: Optional[Any] = None,
+        version: str = "v1",
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Make a POST request to the API."""
+        body = body or {}
+        serialized_body = self._serialize_body(body)
+        auth_params = self._authenticate(serialized_body)
+        url = f"{self.base_url}{version}/{endpoint.lstrip('/')}"
+        headers = self._build_headers(serialized_body, endpoint, body, idempotency_key)
+
+        for attempt in range(self.max_retries + 1):
+            self._log_request(
+                url=url,
+                endpoint=endpoint,
+                version=version,
+                body=body,
+                headers=headers,
+                auth_params=auth_params,
+                attempt=attempt + 1,
+            )
+            try:
+                response = self.session.post(
+                    url,
+                    params=auth_params,
+                    data=serialized_body.encode("utf-8"),
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except requests.exceptions.RequestException as exc:
+                if attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(f"Request failed: {exc}") from exc
+
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = None
+
+            self._log_response(url=url, endpoint=endpoint, response=response, payload=payload)
+
+            if response.status_code != 200:
+                if response.status_code in self.RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(
+                    f"API Error ({response.status_code}) at {url}: {response.text}",
+                    status_code=response.status_code,
+                    response_body=payload if payload is not None else response.text,
+                )
+
+            if payload is None:
+                # Handle plain text responses (e.g., "OK" from email/einvoice endpoints)
+                text_response = response.text.strip()
+                if text_response:
+                    # Wrap plain text response in a dict for consistency
+                    return {"Message": text_response, "Success": True}
+                raise MeritAPIError(
+                    f"Invalid JSON response from {url}: {response.text}",
+                    status_code=response.status_code,
+                    response_body=response.text,
+                )
+
+            # Handle JSON-encoded string responses (e.g., API returns "OK" as JSON string)
+            if isinstance(payload, str):
+                return {"Message": payload, "Success": True}
+
+            self._raise_for_business_error(payload)
+            return payload
+
+        raise MeritAPIError(f"Request failed after retries for {url}")
+
+    def _get(
+        self,
+        endpoint: str,
+        query: Optional[dict[str, Any]] = None,
+        version: str = "v1",
+    ) -> Any:
+        """Make a GET request to the API with signed auth params and extra query params."""
+        query = query or {}
+        serialized_body = ""
+        auth_params = self._authenticate(serialized_body)
+        url = f"{self.base_url}{version}/{endpoint.lstrip('/')}"
+        headers: JsonDict = {"Accept": "application/json"}
+        params = {**auth_params, **query}
+
+        for attempt in range(self.max_retries + 1):
+            self._log_request(
+                url=url,
+                endpoint=endpoint,
+                version=version,
+                body=query,
+                headers=headers,
+                auth_params=auth_params,
+                attempt=attempt + 1,
+            )
+            try:
+                response = self.session.get(
+                    url,
+                    params=params,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except requests.exceptions.RequestException as exc:
+                if attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(f"Request failed: {exc}") from exc
+
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = None
+
+            self._log_response(url=url, endpoint=endpoint, response=response, payload=payload)
+
+            if response.status_code != 200:
+                if response.status_code in self.RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(
+                    f"API Error ({response.status_code}) at {url}: {response.text}",
+                    status_code=response.status_code,
+                    response_body=payload if payload is not None else response.text,
+                )
+
+            if payload is not None:
+                self._raise_for_business_error(payload)
+                return payload
+
+            if response.text:
+                return response.text
+
+            return None
+
+        raise MeritAPIError(f"Request failed after retries for {url}")
+
+    def _get_pdf(
+        self,
+        endpoint: str,
+        body: Optional[Any] = None,
+        version: str = "v1",
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> bytes:
+        """Make a POST request to retrieve a PDF file."""
+        body = body or {}
+        serialized_body = self._serialize_body(body)
+        auth_params = self._authenticate(serialized_body)
+        url = f"{self.base_url}{version}/{endpoint.lstrip('/')}"
+        headers = self._build_headers(serialized_body, endpoint, body, idempotency_key)
+
+        for attempt in range(self.max_retries + 1):
+            self._log_request(
+                url=url,
+                endpoint=endpoint,
+                version=version,
+                body=body,
+                headers=headers,
+                auth_params=auth_params,
+                attempt=attempt + 1,
+            )
+            try:
+                response = self.session.post(
+                    url,
+                    params=auth_params,
+                    data=serialized_body.encode("utf-8"),
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except requests.exceptions.RequestException as exc:
+                if attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(f"Request failed: {exc}") from exc
+
+            # Try to parse as JSON first (in case API returns base64-encoded PDF or error)
+            try:
+                payload = response.json()
+                # Check if it's an error response
+                self._raise_for_business_error(payload)
+                # If payload contains PDF data as base64, extract it
+                if isinstance(payload, dict) and "FileContent" in payload:
+                    import base64
+                    return base64.b64decode(payload["FileContent"])
+                if isinstance(payload, dict) and "Content" in payload:
+                    import base64
+                    return base64.b64decode(payload["Content"])
+                if isinstance(payload, dict) and "Pdf" in payload:
+                    import base64
+                    return base64.b64decode(payload["Pdf"])
+            except ValueError:
+                # Not JSON, so assume it's binary PDF
+                payload = None
+
+            self._log_response(url=url, endpoint=endpoint, response=response, payload=payload)
+
+            if response.status_code != 200:
+                if response.status_code in self.RETRYABLE_STATUS_CODES and attempt < self.max_retries:
+                    time.sleep(self.retry_backoff * (attempt + 1))
+                    continue
+                raise MeritAPIError(
+                    f"API Error ({response.status_code}) at {url}: {response.text}",
+                    status_code=response.status_code,
+                    response_body=payload if payload is not None else response.text,
+                )
+
+            # Return binary content (either from JSON or raw binary response)
+            if payload is not None:
+                # JSON response was already processed above; shouldn't reach here
+                raise MeritAPIError(
+                    f"Unexpected response format from {url}: {response.text}",
+                    status_code=response.status_code,
+                )
+            return response.content
+
+        raise MeritAPIError(f"Request failed after retries for {url}")

merit_api/exceptions.py

@@ -0,0 +1,18 @@
+from typing import Any, Optional
+
+
+class MeritAPIError(Exception):
+    """Base exception for Merit API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.response_body = response_body

merit_api/namespaces.py

@@ -0,0 +1,545 @@
+from datetime import datetime, timedelta
+from typing import Any, Dict, List
+import base64
+
+
+def _to_yyyymmdd(date_str: str) -> str:
+    """Normalize Merit date strings to YYYYMMDD for API fields like PaymentDate.
+
+    Merit invoice lists return DueDate as ISO 8601 (2026-05-02T00:00:00),
+    but sendPaymentV expects YYYYMMDD (20260502).
+    Already-correct 8-char strings are returned unchanged.
+    """
+    if len(date_str) == 8 and date_str.isdigit():
+        return date_str
+    return datetime.fromisoformat(date_str).strftime("%Y%m%d")
+
+
+class Namespace:
+    """Base class for API namespaces."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def _apply_default_period(self, kwargs: dict) -> dict:
+        if "PeriodStart" not in kwargs or "PeriodEnd" not in kwargs:
+            today = datetime.now()
+            kwargs.setdefault("PeriodEnd", today.strftime("%Y%m%d"))
+            kwargs.setdefault("PeriodStart", (today - timedelta(days=90)).strftime("%Y%m%d"))
+        return kwargs
+
+
+class Customers(Namespace):
+    def get_list(self, **kwargs) -> List[Dict]:
+        """Get customer list. Optional filters: Name, RegNo."""
+        return self._client._post("getcustomers", kwargs)
+
+    def get_groups(self, **kwargs) -> List[Dict]:
+        """Get customer groups."""
+        return self._client._post("getcustomergroups", kwargs, version="v2")
+
+    def send(self, customer: Dict[str, Any]) -> Dict:
+        """Create or update a customer."""
+        return self._client._post("sendcustomer", customer, version="v2")
+
+
+class Vendors(Namespace):
+    def get_list(self, **kwargs) -> List[Dict]:
+        """Get vendor list. Optional filters: Name, RegNo."""
+        return self._client._post("getvendors", kwargs)
+
+    def get_groups(self, **kwargs) -> List[Dict]:
+        """Get vendor groups."""
+        return self._client._post("getvendorgroups", kwargs, version="v2")
+
+    def send(self, vendor: Dict[str, Any]) -> Dict:
+        """Create or update a vendor."""
+        return self._client._post("sendvendor", vendor)
+
+    def update(self, vendor: Dict[str, Any]) -> Dict:
+        """Update an existing vendor. Only Id is required; all other fields are optional.
+
+        Use this to keep vendor records current when new invoices arrive — especially
+        to sync BankAccount (IBAN) and SWIFT_BIC so future payments can be made without
+        manual IBAN lookup.
+
+        v2 fields: Id (guid, required), Name, CountryCode, Address, City, PostalCode,
+        PhoneNo, PhoneNo2, Email, RegNo, VatRegNo, SalesInvLang, VatAccountable,
+        BankAccount, ReferenceNo, VendGrCode, VendGrId, PayerReceiverName,
+        Dimensions ([{DimId, DimValueId, DimCode}]).
+        """
+        return self._client._post("updatevendor", vendor, version="v2")
+
+
+class Items(Namespace):
+    def get_list(self, **kwargs) -> List[Dict]:
+        """Get items list. Optional filters: Code, Name."""
+        return self._client._post("getitems", kwargs)
+
+    def get_groups(self, **kwargs) -> List[Dict]:
+        """Get item groups."""
+        return self._client._post("getitemgroups", kwargs, version="v2")
+
+    def add(self, items: List[Dict[str, Any]]) -> List[Dict]:
+        """Add new items."""
+        return self._client._post("senditems", items, version="v2")
+
+    def update(self, item: Dict[str, Any]) -> Dict:
+        """Update an item."""
+        return self._client._post("updateitem", item)
+
+
+class Sales(Namespace):
+    def get_invoices(self, **kwargs) -> List[Dict]:
+        """Get list of invoices.
+
+        PeriodStart/PeriodEnd (YYYYMMDD) default to last 3 months if omitted.
+        This is the safest way to find the latest sales InvoiceNo before creating the
+        next invoice; ``send_invoice`` requires an explicit invoice number.
+        """
+        return self._client._post("getinvoices", self._apply_default_period(kwargs), version="v2")
+
+    def get_invoice(self, id: str, add_attachment: bool = False) -> Dict:
+        """Get single invoice details."""
+        return self._client._post("getinvoice", {"Id": id, "AddAttachment": add_attachment})
+
+    def send_invoice(self, invoice: Dict[str, Any]) -> Dict:
+        """Create a sales invoice.
+
+        This posts the payload directly to Merit v1 ``sendinvoice``. The create
+        payload is not the same shape as ``get_invoice`` responses; do not copy a
+        GET response or rename ``Lines`` to ``InvoiceRows``.
+
+        Important requirements:
+        - Use ``InvoiceRow`` (singular), not ``InvoiceRows``.
+        - ``InvoiceNo`` is mandatory; Merit does not auto-assign it. Call
+          ``get_invoices`` first and choose the next sequential number.
+        - ``DocDate``, ``TransactionDate`` and ``DueDate`` are YYYYMMDD strings.
+        - ``Customer`` should contain ``{"Id": guid}`` for an existing customer.
+        - ``InvoiceRow[].Item`` is required; ``Description`` and ``UOMName`` live
+          inside ``Item``.
+        - ``InvoiceRow[].TaxId`` is the tax GUID. Use ``taxes.get_list()`` to find
+          valid IDs; do not send TaxName or TaxPct.
+        - ``InvoiceRow[].Account`` is the account number field; do not use
+          AccountCode for sales invoice rows.
+        - ``TaxAmount`` is required even when the amount is zero.
+        - ``TotalAmount`` is required at top level and should match the row
+          ``Price * Quantity`` total.
+        - ``FComment`` is an optional footer note.
+        - Do not set ``DelivNote``/``delivnote`` true when creating a draft invoice;
+          delivery is a separate manual step in Merit.
+
+        Minimal working example (0 % VAT)::
+
+            result = client.sales.send_invoice({
+                "Customer": {"Id": "<customer-guid>"},
+                "DocDate": "20260415",
+                "TransactionDate": "20260415",
+                "DueDate": "20260429",
+                "InvoiceNo": "21179",
+                "CurrencyCode": "EUR",
+                "PriceInclVat": False,
+                "InvoiceRow": [
+                    {
+                        "Item": {
+                            "Code": "SVC01",
+                            "Description": "Consulting services",
+                            "UOMName": "tk",
+                        },
+                        "Quantity": 1.0,
+                        "Price": 100.00,
+                        "TaxId": "<tax-guid>",
+                        "Account": "30001",
+                    }
+                ],
+                "TaxAmount": [{"TaxId": "<tax-guid>", "Amount": 0.00}],
+                "TotalAmount": 100.00,
+            })
+            # Returns: {"CustomerId": "...", "InvoiceId": "...", "InvoiceNo": "...", "RefNo": "..."}
+        """
+        return self._client._post("sendinvoice", invoice)
+
+    def delete_invoice(self, id: str) -> Dict:
+        """Delete an invoice."""
+        return self._client._post("deleteinvoice", {"Id": id})
+
+    def send_credit_invoice(self, credit_data: Dict[str, Any]) -> Dict:
+        """Create a credit invoice.
+
+        Uses the same ``sendinvoice`` endpoint with negative Quantity / Price / TotalAmount.
+        Provide the original invoice's customer and rows with negated quantities/prices.
+        The same create-payload requirements apply as in ``send_invoice``: singular
+        ``InvoiceRow``, explicit ``InvoiceNo``, YYYYMMDD dates, row-level ``TaxId``,
+        ``Account``, ``TaxAmount`` and top-level ``TotalAmount``.
+
+        Example::
+
+            result = client.sales.send_credit_invoice({
+                "Customer": {"Id": "<customer-guid>"},
+                "DocDate": "20260415",
+                "TransactionDate": "20260415",
+                "DueDate": "20260415",
+                "InvoiceNo": "21180",
+                "CurrencyCode": "EUR",
+                "PriceInclVat": False,
+                "InvoiceRow": [
+                    {
+                        "Item": {"Code": "SVC01", "Description": "Credit: Consulting", "UOMName": "tk"},
+                        "Quantity": -1.0,
+                        "Price": 100.00,
+                        "TaxId": "<tax-guid>",
+                        "Account": "30001",
+                    }
+                ],
+                "TaxAmount": [{"TaxId": "<tax-guid>", "Amount": -20.00}],
+                "TotalAmount": -120.00,
+            })
+        """
+        return self._client._post("sendinvoice", credit_data)
+
+    def send_invoice_by_email(self, id: str, delivnote: bool = False) -> Dict:
+        """Send a sales invoice by email to the customer.
+
+        This delivers the invoice. Do not call it as part of the normal draft
+        creation flow unless the user explicitly wants delivery from the API.
+        Keep ``delivnote`` false unless delivery note mode without prices is
+        explicitly required.
+        
+        Args:
+            id: Sales invoice GUID (SIHId)
+            delivnote: If True, send invoice without prices (delivery note mode)
+        
+        Returns:
+            Status message or error from mail server
+        """
+        return self._client._post(
+            "sendinvoicebyemail",
+            {"Id": id, "DelivNote": delivnote},
+            version="v2"
+        )
+
+    def send_invoice_by_einvoice(self, id: str, delivnote: bool = False) -> Dict:
+        """Send a sales invoice as a structured e-invoice.
+
+        This delivers the invoice. Do not call it as part of the normal draft
+        creation flow unless the user explicitly wants delivery from the API.
+        Keep ``delivnote`` false unless delivery note mode without prices is
+        explicitly required.
+        
+        Args:
+            id: Sales invoice GUID (SIHId)
+            delivnote: If True, send invoice without prices (delivery note mode)
+
+        Returns:
+            "OK" on success, or "api-noeinv" if recipient lacks e-invoice capability
+        """
+        return self._client._post(
+            "sendinvoiceaseinv",
+            {"Id": id, "DelivNote": delivnote},
+            version="v2"
+        )
+
+    def get_invoice_pdf(self, id: str) -> Dict[str, Any]:
+        """Get a sales invoice as a PDF document (returned as base64-encoded data).
+        
+        Args:
+            id: Sales invoice GUID (SIHId)
+        
+        Returns:
+            Dict with 'pdf' containing base64-encoded PDF content that can be decoded:
+            
+            ```python
+            result = client.sales.get_invoice_pdf(invoice_id)
+            pdf_bytes = base64.b64decode(result['pdf'])
+            with open('invoice.pdf', 'wb') as f:
+                f.write(pdf_bytes)
+            ```
+        """
+        pdf_bytes = self._client._get_pdf("getsalesinvpdf", {"Id": id}, version="v2")
+        return {"pdf": base64.b64encode(pdf_bytes).decode("utf-8")}
+
+    def get_offers(self, **kwargs) -> List[Dict]:
+        """Get list of sales offers. Required: PeriodStart, PeriodEnd, DateType, UnPaid."""
+        return self._client._post("getoffers", kwargs, version="v2")
+
+    def get_offer(self, id: str) -> Dict:
+        """Get sales offer details."""
+        return self._client._post("getoffer", {"Id": id}, version="v2")
+
+    def get_recurring_invoices(self, **kwargs) -> List[Dict]:
+        """Get recurring invoices. Required: PeriodStart, PeriodEnd, DateType."""
+        return self._client._post("getperinvoices", kwargs, version="v2")
+
+    def get_recurring_invoice(self, id: str) -> Dict:
+        """Get recurring invoice details."""
+        return self._client._post("getperinvoice", {"Id": id}, version="v2")
+
+    def get_recurring_invoice_addresses(self, **kwargs) -> List[Dict]:
+        """Get recurring invoice client shipping addresses."""
+        return self._client._post("getpershaddress", kwargs, version="v2")
+
+
+class Purchases(Namespace):
+    def get_invoices(self, **kwargs) -> List[Dict]:
+        """Get list of purchase invoices. Required filters: PeriodStart, PeriodEnd (YYYYmmdd). Defaults to last 3 months."""
+        return self._client._post("getpurchorders", self._apply_default_period(kwargs))
+
+    def get_invoice(self, id: str, skip_attachment: bool = True) -> Dict:
+        """Get purchase invoice details."""
+        return self._client._post("getpurchorder", {"Id": id, "SkipAttachment": skip_attachment})
+
+    def get_orders(self, **kwargs) -> List[Dict]:
+        """Get purchase orders waiting approval."""
+        return self._client._post("GetPOrders", kwargs, version="v2")
+
+    def send_invoice(self, invoice: Dict[str, Any]) -> Dict:
+        """Create a purchase invoice.
+
+        Tricky requirements:
+        - Vendor: must include both ``Id`` AND ``Name`` even for an existing vendor.
+        - InvoiceRow.Item: required nested object — Description lives here, not on the row.
+        - InvoiceRow.TaxId: required on the row (use ``taxes.get_list()`` to find valid IDs).
+        - TaxAmount: required array of ``{TaxId, Amount}`` — one entry per distinct tax rate.
+        - Dates (DocDate, DueDate, TransactionDate): YYYYmmdd strings.
+        - Attachment (optional): ``{FileName: str, FileContent: base64-encoded PDF}``.
+
+        Minimal working example (0 % VAT, with PDF attachment)::
+
+            result = client.purchases.send_invoice({
+                "Vendor": {"Id": "<vendor-guid>", "Name": "Vendor Name OÜ"},
+                "DocDate": "20260415",
+                "DueDate": "20260429",
+                "TransactionDate": "20260415",
+                "BillNo": "INV-2026-001",
+                "CurrencyCode": "EUR",
+                "CurrencyRate": 1.0,
+                "InvoiceRow": [
+                    {
+                        "Item": {
+                            "Code": "SVC01",
+                            "Description": "Consulting services",
+                            "UOMName": "tk",
+                            "TaxId": "<tax-guid>",
+                        },
+                        "Quantity": 1.0,
+                        "Price": 100.00,
+                        "TaxId": "<tax-guid>",
+                        "GLAccountCode": "4017",
+                    }
+                ],
+                "TaxAmount": [{"TaxId": "<tax-guid>", "Amount": 0.0}],
+                "TotalAmount": 100.00,
+                "RoundingAmount": 0.0,
+                "Attachment": {
+                    "FileName": "invoice.pdf",
+                    "FileContent": "<base64-encoded PDF>",
+                },
+            })
+            # Returns: {"VendorId": "...", "BillId": "...", "BillNo": "...", "BatchInfo": "..."}
+        """
+        return self._client._post("sendpurchinvoice", invoice)
+
+
+class Financial(Namespace):
+    def get_payments(self, **kwargs) -> List[Dict]:
+        """Get payments. PeriodStart/PeriodEnd (YYYYmmdd) default to last 3 months if omitted."""
+        return self._client._post("getpayments", self._apply_default_period(kwargs))
+
+    def get_payment_types(self, **kwargs) -> List[Dict]:
+        """Get payment types."""
+        return self._client._post("getpaymenttypes", kwargs, version="v2")
+
+    def get_payment_imports(self, **kwargs) -> List[Dict]:
+        """Get payment imports."""
+        return self._client._get("PaymentImports", kwargs, version="v2")
+
+    def get_expense_payments(self, bank_id: str, **kwargs) -> List[Dict]:
+        """Get expense payments for a bank."""
+        return self._client._get(f"Banks/{bank_id}/ExpensePayments", kwargs, version="v2")
+
+    def get_income_payments(self, bank_id: str, **kwargs) -> List[Dict]:
+        """Get income payments for a bank."""
+        return self._client._get(f"Banks/{bank_id}/IncomePayments", kwargs, version="v2")
+
+    def create_payment(self, payment: Dict[str, Any]) -> Dict:
+        """Create a payment for a purchase invoice (sendPaymentV).
+
+        Auto-resolves missing fields before sending:
+        - IBAN: looked up from the vendor's BankAccount by VendorName.
+        - PaymentDate: looked up from the invoice's DueDate by BillNo.
+
+        Raises ValueError if either field cannot be resolved, preventing a silent
+        internal payment without bank transfer details.
+
+        Returns the raw Merit API response (all fields as-is).
+        """
+        if not payment.get("IBAN"):
+            vendor_name = payment.get("VendorName", "")
+            if vendor_name:
+                vendors = self._client.vendors.get_list(Name=vendor_name)
+                vendor = next((v for v in vendors if v.get("Name") == vendor_name), None)
+                if vendor and vendor.get("BankAccount"):
+                    payment = {**payment, "IBAN": vendor["BankAccount"]}
+
+        if not payment.get("IBAN"):
+            vendor_name = payment.get("VendorName", "unknown")
+            raise ValueError(
+                f"IBAN is missing for vendor '{vendor_name}'. "
+                "Add IBAN to the payload or update the vendor's bank account in Merit."
+            )
+
+        if not payment.get("PaymentDate"):
+            bill_no = payment.get("BillNo", "")
+            if bill_no:
+                today = datetime.now()
+                invoices = self._client.purchases.get_invoices(
+                    PeriodStart=(today - timedelta(days=365)).strftime("%Y%m%d"),
+                    PeriodEnd=(today + timedelta(days=730)).strftime("%Y%m%d"),
+                )
+                invoice = next((i for i in invoices if i.get("BillNo") == bill_no), None)
+                if invoice and invoice.get("DueDate"):
+                    payment = {**payment, "PaymentDate": _to_yyyymmdd(invoice["DueDate"])}
+
+        if not payment.get("PaymentDate"):
+            bill_no = payment.get("BillNo", "unknown")
+            raise ValueError(
+                f"PaymentDate is missing for invoice '{bill_no}' and could not be resolved "
+                "from the invoice's DueDate. Provide PaymentDate explicitly (YYYYMMDD)."
+            )
+
+        version = "v2" if payment.get("CurrencyCode") else "v1"
+        return self._client._post("sendPaymentV", payment, version=version)
+
+    def get_gl_batches(self, **kwargs) -> List[Dict]:
+        """Get GL transactions. PeriodStart/PeriodEnd (YYYYmmdd) default to last 3 months if omitted."""
+        return self._client._post("getglbatches", self._apply_default_period(kwargs))
+
+    def get_gl_batch(self, id: str) -> Dict:
+        """Get GL transaction details."""
+        return self._client._post("getglbatch", {"Id": id})
+
+    def get_gl_batches_full(self, **kwargs) -> List[Dict]:
+        """Get GL transactions with full details."""
+        return self._client._post("GetGLBatchesFull", self._apply_default_period(kwargs))
+
+    def get_banks(self) -> List[Dict]:
+        """Get list of banks."""
+        return self._client._post("getbanks")
+
+    def get_accounts(self, **kwargs) -> List[Dict]:
+        """Get chart of accounts."""
+        return self._client._post("getaccounts", kwargs)
+
+    def get_costs(self) -> List[Dict]:
+        """Get cost centers."""
+        return self._client._post("getcostcenters")
+
+    def get_projects(self) -> List[Dict]:
+        """Get projects."""
+        return self._client._post("getprojects")
+
+    def get_departments(self, **kwargs) -> List[Dict]:
+        """Get departments."""
+        return self._client._post("getdepartments", kwargs)
+
+    def get_financial_years(self, **kwargs) -> Dict:
+        """Get financial years."""
+        return self._client._post("getaccperiods", kwargs, version="v2")
+
+
+class Inventory(Namespace):
+    def get_locations(self, **kwargs) -> List[Dict]:
+        """Get inventory locations."""
+        return self._client._post("getlocations", kwargs, version="v2")
+
+    def get_movements(self, **kwargs) -> List[Dict]:
+        """Get inventory movements."""
+        return self._client._post("getinvmovements", kwargs, version="v2")
+
+
+class Assets(Namespace):
+    def get_locations(self, **kwargs) -> List[Dict]:
+        """Get fixed asset locations."""
+        return self._client._post("getfalocations", kwargs, version="v2")
+
+    def get_responsible_persons(self, **kwargs) -> List[Dict]:
+        """Get fixed asset responsible persons."""
+        return self._client._post("getfaresppersons", kwargs, version="v2")
+
+    def get_fixed_assets(self, **kwargs) -> List[Dict]:
+        """Get fixed assets."""
+        return self._client._post("getfixassets", kwargs, version="v2")
+
+
+class Taxes(Namespace):
+    def get_list(self) -> List[Dict]:
+        """Get tax rates list."""
+        return self._client._post("gettaxes")
+
+    def send(self, tax: Dict[str, Any]) -> Dict:
+        """Create or update a tax rate."""
+        return self._client._post("sendtax", tax, version="v2")
+
+
+class Dimensions(Namespace):
+    def get_list(self, all_values: bool = False) -> List[Dict]:
+        """Get dimensions list. all_values=True includes expired dimension values."""
+        return self._client._post("getdimensions", {"AllValues": all_values}, version="v2")
+
+    def add(self, dimensions: List[Dict[str, Any]]) -> List[Dict]:
+        """Add dimensions."""
+        return self._client._post("senddimensions", dimensions, version="v2")
+
+
+class Pricing(Namespace):
+    def get_prices(self, **kwargs) -> List[Dict]:
+        """Get sales prices."""
+        return self._client._post("getprices", kwargs, version="v2")
+
+    def get_discounts(self, **kwargs) -> List[Dict]:
+        """Get sales discounts."""
+        return self._client._post("getdiscounts", kwargs, version="v2")
+
+    def get_price(self, **kwargs) -> Dict:
+        """Get a single effective sales price."""
+        return self._client._post("getprice", kwargs, version="v2")
+
+
+class Reports(Namespace):
+    def get_customer_debts(self, **kwargs) -> List[Dict]:
+        """Get customer debts report."""
+        return self._client._post("getcustdebtrep", kwargs)
+
+    def get_customer_payments(self, **kwargs) -> Dict:
+        """Get customer payment report."""
+        return self._client._post("getcustpaymrep", kwargs, version="v2")
+
+    def get_more_data(self, **kwargs) -> Dict:
+        """Get next page / additional report data for paged report APIs."""
+        return self._client._post("getmoredata", kwargs, version="v2")
+
+    def get_profit(self, **kwargs) -> Dict:
+        """Get statement of profit or loss."""
+        return self._client._post("getprofitrep", kwargs)
+
+    def get_balance(self, **kwargs) -> Dict:
+        """Get statement of financial position."""
+        return self._client._post("getbalancerep", kwargs)
+
+    def get_inventory(self, **kwargs) -> List[Dict]:
+        """Get inventory report."""
+        return self._client._post("getinventoryreport", kwargs, version="v2")
+
+    def get_sales(self, **kwargs) -> List[Dict]:
+        """Get sales report."""
+        return self._client._post("getsalesrep", kwargs, version="v2")
+
+    def get_purchases(self, **kwargs) -> List[Dict]:
+        """Get purchase report."""
+        return self._client._post("getpurchrep", kwargs, version="v2")
+
+
+class ReferenceData(Namespace):
+    def get_units(self, **kwargs) -> List[Dict]:
+        """Get units of measure."""
+        return self._client._post("getunits", kwargs)

merit_api-0.4.4.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: merit-api
+Version: 0.4.4
+Summary: Python client for Merit Aktiva API
+Author-email: Jaak <jaak@example.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# merit-api
+
+Python SDK for the Merit Aktiva API.
+
+## Installation
+
+```bash
+pip install merit-api
+```
+
+## Usage
+
+```python
+from merit_api import MeritAPI
+
+client = MeritAPI(api_id="YOUR_API_ID", api_key="YOUR_API_KEY")
+
+customers = client.customers.get_list()
+invoices = client.sales.get_invoices(
+    PeriodStart="2024-01-01",
+    PeriodEnd="2024-01-31",
+)
+```
+
+## Features
+
+- deterministic request-body serialization for signing
+- configurable timeout and retry handling
+- request and response logging hooks with secret redaction
+- optional idempotency header generation
+- API-level business error parsing from HTTP 200 responses
+
+## Testing and method coverage report
+
+Run tests:
+
+```bash
+pytest -q
+```
+
+Regenerate the method-level read/write coverage report:
+
+```bash
+python scripts_report_method_test_coverage.py
+```
+
+The report is written to `reports/method_test_coverage.md` and CI checks that this file stays up to date.

merit_api-0.4.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+merit_api/__init__.py,sha256=4vzY3VOTPTOBuLhCk0rVbRdn0YFQUvC2xvWjE11GM3U,108
+merit_api/client.py,sha256=p1MxNui5l8xRWAgUuhznbr1UtX_X8-vHlqWS0_kYbd8,15345
+merit_api/exceptions.py,sha256=tRfsZsI3DOmos8fjup-72Of1vpY6yANvQyP9QYucyE0,468
+merit_api/namespaces.py,sha256=Lqxao3UxFkACuiTUA2203KhaM1EgruLaypCLfvxMCrc,22954
+merit_api-0.4.4.dist-info/METADATA,sha256=Uo0I42acKYcJp5Z-aPp36f_fi4-TxlG7CODjC_ewplc,1291
+merit_api-0.4.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+merit_api-0.4.4.dist-info/RECORD,,

merit_api-0.4.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any