sienge-python 0.1.0__py3-none-any.whl

sienge/__init__.py

@@ -0,0 +1,52 @@
+"""
+sienge — Cliente Python para a API REST do Sienge (ERP de construcao civil).
+
+Primeiro wrapper Python do mundo para o Sienge.
+
+Uso:
+    from sienge import SiengeClient
+
+    client = SiengeClient("conin", "usuario", "senha")
+
+    # Engenharia
+    obras = client.engenharia.list_obras()
+    progresso = client.engenharia.get_progresso(123)
+
+    # Financeiro
+    titulos = client.financeiro.list_titulos()
+    centros = client.financeiro.list_centros_custo()
+
+    # Suprimentos
+    pedidos = client.suprimentos.list_pedidos(building_id=123)
+
+    # Credores
+    fornecedores = client.credores.list_credores()
+
+    # Contabilidade
+    lancamentos = client.contabilidade.list_lancamentos(company_id=1)
+
+    # Bulk (plano Ultimate)
+    dados = client.bulk.export_income("2026-01-01")
+"""
+
+__version__ = "0.1.0"
+
+from .client import SiengeClient
+from .exceptions import (
+    SiengeError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    MaintenanceError,
+    ValidationError,
+)
+
+__all__ = [
+    "SiengeClient",
+    "SiengeError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "MaintenanceError",
+    "ValidationError",
+]

sienge/auth.py

@@ -0,0 +1,23 @@
+"""
+sienge.auth — Autenticacao HTTP Basic Auth para a API Sienge.
+"""
+
+from requests.auth import HTTPBasicAuth
+
+
+class SiengeAuth:
+    """Gerencia credenciais e autenticacao para a API Sienge."""
+
+    def __init__(self, username: str, password: str):
+        if not username or not password:
+            raise ValueError("Username e password sao obrigatorios para autenticacao no Sienge.")
+        self._username = username
+        self._password = password
+
+    def get_auth(self) -> HTTPBasicAuth:
+        """Retorna objeto HTTPBasicAuth para uso com requests."""
+        return HTTPBasicAuth(self._username, self._password)
+
+    @property
+    def username(self) -> str:
+        return self._username

sienge/client.py

@@ -0,0 +1,146 @@
+"""
+sienge.client — Cliente principal para a API REST do Sienge.
+
+Uso:
+    from sienge import SiengeClient
+
+    client = SiengeClient("conin", "usuario", "senha")
+    obras = client.engenharia.list_obras()
+    titulos = client.financeiro.list_titulos()
+"""
+
+import logging
+import os
+
+import requests
+
+from .auth import SiengeAuth
+from .rate_limiter import get_rest_limiter, get_bulk_limiter, RateLimiter
+from .endpoints.engenharia import EngenhariaEndpoints
+from .endpoints.financeiro import FinanceiroEndpoints
+from .endpoints.suprimentos import SuprimentosEndpoints
+from .endpoints.comercial import ComercialEndpoints
+from .endpoints.contabilidade import ContabilidadeEndpoints
+from .endpoints.credores import CredoresEndpoints
+from .endpoints.bulk import BulkEndpoints
+from .endpoints.patrimonio import PatrimonioEndpoints
+from .endpoints.webhooks import WebhooksEndpoints
+from .endpoints.tabelas import TabelasEndpoints
+
+logger = logging.getLogger("sienge")
+
+DEFAULT_TIMEOUT = 30
+DEFAULT_MAX_RETRIES = 3
+
+
+class SiengeClient:
+    """Cliente para a API REST do Sienge.
+
+    Uso basico:
+        client = SiengeClient("conin", "usuario", "senha")
+        obras = client.engenharia.list_obras()
+
+    Ou via variaveis de ambiente:
+        # Defina SIENGE_SUBDOMAIN, SIENGE_USERNAME, SIENGE_PASSWORD
+        client = SiengeClient.from_env()
+
+    Args:
+        subdomain: Subdominio da empresa no Sienge (ex: "conin").
+        username: Usuario de API (criado no painel Sienge).
+        password: Senha do usuario de API.
+        timeout: Timeout em segundos para cada requisicao.
+        max_retries: Numero maximo de retentativas em erro transiente.
+    """
+
+    def __init__(
+        self,
+        subdomain: str,
+        username: str,
+        password: str,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        self._subdomain = subdomain
+        self._auth = SiengeAuth(username, password)
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        # URLs
+        self._base_url = f"https://api.sienge.com.br/{subdomain}/public/api/v1"
+        self._bulk_url = f"https://api.sienge.com.br/{subdomain}/public/api/bulk-data/v1"
+
+        # Session com auth persistente
+        self._session = requests.Session()
+        self._session.auth = self._auth.get_auth()
+        self._session.headers.update({"Accept": "application/json"})
+
+        # Rate limiters
+        self._rest_limiter: RateLimiter = get_rest_limiter()
+        self._bulk_limiter: RateLimiter = get_bulk_limiter()
+
+        # Endpoint groups
+        self.engenharia = EngenhariaEndpoints(self)
+        self.financeiro = FinanceiroEndpoints(self)
+        self.suprimentos = SuprimentosEndpoints(self)
+        self.comercial = ComercialEndpoints(self)
+        self.contabilidade = ContabilidadeEndpoints(self)
+        self.credores = CredoresEndpoints(self)
+        self.bulk = BulkEndpoints(self)
+        self.patrimonio = PatrimonioEndpoints(self)
+        self.webhooks = WebhooksEndpoints(self)
+        self.tabelas = TabelasEndpoints(self)
+
+        logger.info("SiengeClient inicializado para '%s' (user: %s)", subdomain, username)
+
+    @classmethod
+    def from_env(
+        cls,
+        subdomain_var: str = "SIENGE_SUBDOMAIN",
+        username_var: str = "SIENGE_USERNAME",
+        password_var: str = "SIENGE_PASSWORD",
+        **kwargs,
+    ) -> "SiengeClient":
+        """Cria cliente a partir de variaveis de ambiente.
+
+        Args:
+            subdomain_var: Nome da env var para subdominio.
+            username_var: Nome da env var para usuario.
+            password_var: Nome da env var para senha.
+            **kwargs: Argumentos extras passados ao construtor.
+
+        Returns:
+            SiengeClient configurado.
+
+        Raises:
+            ValueError: Se variaveis de ambiente estao faltando.
+        """
+        subdomain = os.getenv(subdomain_var, "")
+        username = os.getenv(username_var, "")
+        password = os.getenv(password_var, "")
+
+        if not subdomain:
+            raise ValueError(f"Variavel de ambiente '{subdomain_var}' nao definida.")
+        if not username:
+            raise ValueError(f"Variavel de ambiente '{username_var}' nao definida.")
+        if not password:
+            raise ValueError(f"Variavel de ambiente '{password_var}' nao definida.")
+
+        return cls(subdomain, username, password, **kwargs)
+
+    @property
+    def subdomain(self) -> str:
+        """Subdominio da empresa no Sienge."""
+        return self._subdomain
+
+    @property
+    def base_url(self) -> str:
+        """URL base da API REST."""
+        return self._base_url
+
+    @property
+    def bulk_url(self) -> str:
+        """URL base da API Bulk."""
+        return self._bulk_url
+
+    def __repr__(self) -> str:
+        return f"SiengeClient(subdomain='{self._subdomain}', user='{self._auth.username}')"

sienge/endpoints/__init__.py

@@ -0,0 +1,27 @@
+"""
+sienge.endpoints — Modulos de endpoints agrupados por area funcional.
+"""
+
+from .engenharia import EngenhariaEndpoints
+from .financeiro import FinanceiroEndpoints
+from .suprimentos import SuprimentosEndpoints
+from .comercial import ComercialEndpoints
+from .contabilidade import ContabilidadeEndpoints
+from .credores import CredoresEndpoints
+from .bulk import BulkEndpoints
+from .patrimonio import PatrimonioEndpoints
+from .webhooks import WebhooksEndpoints
+from .tabelas import TabelasEndpoints
+
+__all__ = [
+    "EngenhariaEndpoints",
+    "FinanceiroEndpoints",
+    "SuprimentosEndpoints",
+    "ComercialEndpoints",
+    "ContabilidadeEndpoints",
+    "CredoresEndpoints",
+    "BulkEndpoints",
+    "PatrimonioEndpoints",
+    "WebhooksEndpoints",
+    "TabelasEndpoints",
+]

sienge/endpoints/base.py

@@ -0,0 +1,187 @@
+"""
+sienge.endpoints.base — Classe base para grupos de endpoints.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+import requests
+
+from ..exceptions import (
+    AuthError,
+    MaintenanceError,
+    NotFoundError,
+    RateLimitError,
+    SiengeError,
+    ValidationError,
+)
+from ..rate_limiter import RateLimiter
+from ..utils import retry_with_backoff
+
+if TYPE_CHECKING:
+    from ..client import SiengeClient
+
+logger = logging.getLogger("sienge")
+
+
+class BaseEndpoints:
+    """Classe base que fornece metodos HTTP autenticados e com rate limiting."""
+
+    def __init__(self, client: "SiengeClient"):
+        self._client = client
+
+    @property
+    def _base_url(self) -> str:
+        return self._client._base_url
+
+    @property
+    def _bulk_url(self) -> str:
+        return self._client._bulk_url
+
+    @property
+    def _session(self) -> requests.Session:
+        return self._client._session
+
+    @property
+    def _rest_limiter(self) -> RateLimiter:
+        return self._client._rest_limiter
+
+    @property
+    def _bulk_limiter(self) -> RateLimiter:
+        return self._client._bulk_limiter
+
+    @property
+    def _timeout(self) -> int:
+        return self._client._timeout
+
+    @property
+    def _max_retries(self) -> int:
+        return self._client._max_retries
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        is_bulk: bool = False,
+    ) -> dict:
+        """Faz requisicao autenticada com rate limiting e retry.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: Path relativo (ex: "/bills").
+            params: Query parameters.
+            json_body: Body JSON para POST/PUT.
+            is_bulk: Se True, usa bulk URL e bulk rate limiter.
+
+        Returns:
+            Resposta JSON como dict.
+
+        Raises:
+            SiengeError: Em caso de erro.
+        """
+        base = self._bulk_url if is_bulk else self._base_url
+        url = f"{base}{path}"
+        limiter = self._bulk_limiter if is_bulk else self._rest_limiter
+
+        def _do_request() -> dict:
+            limiter.acquire()
+            resp = self._session.request(
+                method=method,
+                url=url,
+                params=params,
+                json=json_body,
+                timeout=self._timeout,
+            )
+            return self._handle_response(resp, method, url)
+
+        return retry_with_backoff(
+            _do_request,
+            max_retries=self._max_retries,
+            retryable_exceptions=(
+                RateLimitError, MaintenanceError,
+                requests.exceptions.ConnectionError,
+                requests.exceptions.Timeout,
+            ),
+        )
+
+    def _handle_response(self, resp: requests.Response, method: str, url: str) -> dict:
+        """Trata status codes da resposta."""
+        if resp.status_code == 200:
+            if not resp.content:
+                return {}
+            try:
+                return resp.json()
+            except ValueError:
+                return {"_raw": resp.text}
+
+        if resp.status_code == 201:
+            try:
+                return resp.json()
+            except ValueError:
+                return {"_created": True}
+
+        if resp.status_code == 204:
+            return {"_no_content": True}
+
+        body = resp.text[:500] if resp.text else ""
+
+        if resp.status_code == 400:
+            raise ValidationError(
+                f"Parametros invalidos: {body}",
+                status_code=400,
+                response_body=body,
+            )
+
+        if resp.status_code == 401:
+            raise AuthError(
+                f"Nao autorizado. Verifique credenciais ou libere o recurso no painel Sienge. "
+                f"URL: {url}",
+                status_code=401,
+                response_body=body,
+            )
+
+        if resp.status_code == 404:
+            raise NotFoundError(
+                f"Recurso nao encontrado: {url}",
+                status_code=404,
+                response_body=body,
+            )
+
+        if resp.status_code == 429:
+            raise RateLimitError(
+                f"Rate limit atingido para {url}",
+                retry_after=60,
+                response_body=body,
+            )
+
+        if resp.status_code == 503:
+            raise MaintenanceError(
+                f"Sienge em manutencao (00:00-06:30 UTC). URL: {url}",
+                status_code=503,
+                response_body=body,
+            )
+
+        raise SiengeError(
+            f"Erro HTTP {resp.status_code} em {method} {url}: {body}",
+            status_code=resp.status_code,
+            response_body=body,
+        )
+
+    def _get(self, path: str, params: dict[str, Any] | None = None, is_bulk: bool = False) -> dict:
+        return self._request("GET", path, params=params, is_bulk=is_bulk)
+
+    def _post(self, path: str, json_body: dict[str, Any] | None = None, params: dict[str, Any] | None = None) -> dict:
+        return self._request("POST", path, params=params, json_body=json_body)
+
+    def _put(self, path: str, json_body: dict[str, Any] | None = None) -> dict:
+        return self._request("PUT", path, json_body=json_body)
+
+    def _patch(self, path: str, json_body: dict[str, Any] | None = None) -> dict:
+        return self._request("PATCH", path, json_body=json_body)
+
+    def _delete(self, path: str) -> dict:
+        return self._request("DELETE", path)

sienge/endpoints/bulk.py

@@ -0,0 +1,264 @@
+"""
+sienge.endpoints.bulk — Endpoints de Bulk Data (exportacao em massa).
+
+ENDPOINTS BULK CONFIRMADOS (auditoria 2026-03-14):
+  ✅ /income — parcelas a receber (startDate, endDate, selectionType=D)
+  ✅ /outcome — parcelas a pagar (startDate, endDate, selectionType=D, correctionIndexerId, correctionDate)
+  ✅ /bank-movement — movimentos caixa/banco (startDate, endDate) — 784 registros
+  ✅ /purchase-quotations — cotacoes (startDate, endDate) — 75 itens
+  ✅ /customer-extract-history — extrato cliente
+  ✅ /customer-debt-balance — saldo devedor
+  ✅ /defaulters-receivable-bills — inadimplentes
+  ✅ /building/resources — insumos da obra
+  ✅ /business-budget — orcamento empresarial
+  ✅ /accountancy/accountBalance — saldos contabeis empresa
+  ✅ /accountancy/accountCostCenterBalance — saldos contabeis CC
+  ✅ /invoice-itens — itens notas fiscais
+  ❌ /payable-bills — 404
+  ❌ /building-cost-estimations — 404
+  ❌ /cash-bank-movements — 404 (path correto: /bank-movement)
+  ❌ /invoices — 404 (path correto: /invoice-itens)
+"""
+
+from __future__ import annotations
+
+from .base import BaseEndpoints
+
+
+class BulkEndpoints(BaseEndpoints):
+    """Endpoints de Bulk Data para exportacao em massa."""
+
+    def export_income(self, start_date: str, end_date: str, selection_type: str = "D") -> list[dict]:
+        """Exporta parcelas a receber.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+            selection_type: Tipo selecao — I(ssue), P(ay), D(ue), B(ill), C.
+
+        Returns:
+            Lista de dicts com dados.
+        """
+        data = self._get("/income", params={
+            "startDate": start_date,
+            "endDate": end_date,
+            "selectionType": selection_type,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_outcome(self, start_date: str, end_date: str, selection_type: str = "D",
+                       correction_indexer_id: int = 1, correction_date: str = "") -> list[dict]:
+        """Exporta parcelas a pagar.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+            selection_type: Tipo selecao — I(ssue), P(ay), D(ue).
+            correction_indexer_id: ID do indexador de correcao.
+            correction_date: Data de correcao (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        if not correction_date:
+            correction_date = end_date
+        data = self._get("/outcome", params={
+            "startDate": start_date,
+            "endDate": end_date,
+            "selectionType": selection_type,
+            "correctionIndexerId": correction_indexer_id,
+            "correctionDate": correction_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_bank_movements(self, start_date: str, end_date: str) -> list[dict]:
+        """Exporta movimentos de caixa e bancos.
+
+        NOTA: Path correto e /bank-movement (NAO /cash-bank-movements).
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts com movimentos (784 na CONIN em 7 dias).
+        """
+        data = self._get("/bank-movement", params={
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_purchase_quotations(self, start_date: str, end_date: str) -> list[dict]:
+        """Exporta cotacoes de precos em massa.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts (75 na CONIN).
+        """
+        data = self._get("/purchase-quotations", params={
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_customer_extract(self, start_due_date: str, end_due_date: str) -> list[dict]:
+        """Exporta historico de extrato de clientes.
+
+        Args:
+            start_due_date: Data inicio vencimento (YYYY-MM-DD).
+            end_due_date: Data fim vencimento (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/customer-extract-history", params={
+            "startDueDate": start_due_date,
+            "endDueDate": end_due_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_customer_debt(self, start_due_date: str, end_due_date: str) -> list[dict]:
+        """Exporta saldo devedor de clientes.
+
+        Args:
+            start_due_date: Data inicio vencimento (YYYY-MM-DD).
+            end_due_date: Data fim vencimento (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/customer-debt-balance", params={
+            "startDueDate": start_due_date,
+            "endDueDate": end_due_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_defaulters(self, company_id: int) -> list[dict]:
+        """Exporta titulos de inadimplentes.
+
+        Args:
+            company_id: ID da empresa (OBRIGATORIO).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/defaulters-receivable-bills", params={
+            "companyId": company_id,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_building_resources(self, building_id: int, start_date: str, end_date: str) -> list[dict]:
+        """Exporta insumos de uma obra.
+
+        Args:
+            building_id: ID do empreendimento (OBRIGATORIO).
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/building/resources", params={
+            "buildingId": building_id,
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_business_budget(self, start_date: str, end_date: str) -> list[dict]:
+        """Exporta orcamento empresarial.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/business-budget", params={
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_account_balance(self, start_date: str, end_date: str) -> list[dict]:
+        """Exporta saldos contabeis por empresa.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/accountancy/accountBalance", params={
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_account_cc_balance(self, start_date: str, end_date: str) -> list[dict]:
+        """Exporta saldos contabeis por centro de custo.
+
+        Args:
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/accountancy/accountCostCenterBalance", params={
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export_invoice_items(self, company_id: int, start_date: str, end_date: str) -> list[dict]:
+        """Exporta itens de notas fiscais.
+
+        NOTA: Path correto e /invoice-itens (NAO /invoices).
+
+        Args:
+            company_id: ID da empresa (OBRIGATORIO).
+            start_date: Data inicio (YYYY-MM-DD).
+            end_date: Data fim (YYYY-MM-DD).
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get("/invoice-itens", params={
+            "companyId": company_id,
+            "startDate": start_date,
+            "endDate": end_date,
+        }, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []
+
+    def export(self, resource: str, params: dict | None = None) -> list[dict]:
+        """Exporta qualquer recurso bulk generico.
+
+        Args:
+            resource: Nome do recurso (ex: "income", "bank-movement").
+            params: Query params.
+
+        Returns:
+            Lista de dicts.
+        """
+        data = self._get(f"/{resource}", params=params, is_bulk=True)
+        result = data.get("data", data.get("results", data if isinstance(data, list) else []))
+        return result if isinstance(result, list) else []