sicoob-sdk 0.1.0__tar.gz

sicoob_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: sicoob-sdk
+Version: 0.1.0
+Summary: A Python SDK for Sicoob API
+Author: Fábio Thomaz
+Author-email: fabio@ladder.dev.br
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.1
+Requires-Dist: python-dotenv>=0.15.0
+Requires-Dist: pytest>=7.0.0
+Requires-Dist: pytest-mock>=3.6.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: requires-python
+
+# Sicoob SDK Python
+
+SDK Python para integração com a API do Banco Sicoob
+
+## Instalação
+
+```bash
+pip install -r requirements.txt
+# ou
+pip install -e .
+```
+
+## Configuração
+
+Crie um arquivo `.env` na raiz do projeto com as seguintes variáveis:
+
+```ini
+SICOOB_CLIENT_ID=seu_client_id
+SICOOB_CLIENT_SECRET=seu_client_secret
+SICOOB_CERTIFICADO=caminho/para/certificado.pem
+SICOOB_CHAVE_PRIVADA=caminho/para/chave_privada.key
+```
+
+## Uso Básico
+
+```python
+from sicoob import Sicoob
+
+# Inicializa o cliente
+cliente = Sicoob(
+    client_id="seu_client_id",
+    client_secret="seu_client_secret",
+    certificado="caminho/para/certificado.pem",
+    chave_privada="caminho/para/chave_privada.key"
+)
+
+# Exemplo: consulta de extratos
+extrato = cliente.consulta_extrato(conta="12345", data_inicio="2023-01-01", data_fim="2023-01-31")
+```
+
+## API de Boletos
+
+A classe `BoletoAPI` permite emitir e consultar boletos bancários:
+
+```python
+from sicoob.boleto import BoletoAPI
+
+# Obtém instância do BoletoAPI
+boleto_api = cliente.boleto()
+
+# Emitir boleto
+dados_boleto = {
+    "numeroContrato": 123456,
+    "modalidade": 1,
+    "valor": 100.50,
+    "beneficiario": {
+        "nome": "Nome Beneficiário",
+        "documento": "12345678901"
+    }
+}
+boleto = boleto_api.emitir_boleto(dados_boleto)
+
+# Consultar boleto
+nosso_numero = boleto["nossoNumero"]
+boleto_consultado = boleto_api.consultar_boleto(nosso_numero)
+```
+
+### Tratamento de Erros
+
+A API trata os seguintes casos de erro:
+- **404 Not Found**: Retorna `None` quando o boleto não existe
+- **Erros HTTP (400, 500, etc)**: Levanta exceção com código e mensagem
+- **Erros de conexão**: Levanta exceção com detalhes do erro
+
+## Links Úteis
+
+- [Documentação API Sicoob](https://developers.sicoob.com.br)
+- [Portal de Desenvolvedores](https://developers.sicoob.com.br/portal)

sicoob_sdk-0.1.0/README.md

@@ -0,0 +1,78 @@
+# Sicoob SDK Python
+
+SDK Python para integração com a API do Banco Sicoob
+
+## Instalação
+
+```bash
+pip install -r requirements.txt
+# ou
+pip install -e .
+```
+
+## Configuração
+
+Crie um arquivo `.env` na raiz do projeto com as seguintes variáveis:
+
+```ini
+SICOOB_CLIENT_ID=seu_client_id
+SICOOB_CLIENT_SECRET=seu_client_secret
+SICOOB_CERTIFICADO=caminho/para/certificado.pem
+SICOOB_CHAVE_PRIVADA=caminho/para/chave_privada.key
+```
+
+## Uso Básico
+
+```python
+from sicoob import Sicoob
+
+# Inicializa o cliente
+cliente = Sicoob(
+    client_id="seu_client_id",
+    client_secret="seu_client_secret",
+    certificado="caminho/para/certificado.pem",
+    chave_privada="caminho/para/chave_privada.key"
+)
+
+# Exemplo: consulta de extratos
+extrato = cliente.consulta_extrato(conta="12345", data_inicio="2023-01-01", data_fim="2023-01-31")
+```
+
+## API de Boletos
+
+A classe `BoletoAPI` permite emitir e consultar boletos bancários:
+
+```python
+from sicoob.boleto import BoletoAPI
+
+# Obtém instância do BoletoAPI
+boleto_api = cliente.boleto()
+
+# Emitir boleto
+dados_boleto = {
+    "numeroContrato": 123456,
+    "modalidade": 1,
+    "valor": 100.50,
+    "beneficiario": {
+        "nome": "Nome Beneficiário",
+        "documento": "12345678901"
+    }
+}
+boleto = boleto_api.emitir_boleto(dados_boleto)
+
+# Consultar boleto
+nosso_numero = boleto["nossoNumero"]
+boleto_consultado = boleto_api.consultar_boleto(nosso_numero)
+```
+
+### Tratamento de Erros
+
+A API trata os seguintes casos de erro:
+- **404 Not Found**: Retorna `None` quando o boleto não existe
+- **Erros HTTP (400, 500, etc)**: Levanta exceção com código e mensagem
+- **Erros de conexão**: Levanta exceção com detalhes do erro
+
+## Links Úteis
+
+- [Documentação API Sicoob](https://developers.sicoob.com.br)
+- [Portal de Desenvolvedores](https://developers.sicoob.com.br/portal)

sicoob_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "sicoob-sdk"
+version = "0.1.0"
+description = "A Python SDK for Sicoob API"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.25.1",
+    "python-dotenv>=0.15.0",
+    # Testes
+    "pytest>=7.0.0",
+    "pytest-mock>=3.6.1",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2.post1",
+    "twine>=6.1.0",
+]

sicoob_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sicoob_sdk-0.1.0/setup.py

@@ -0,0 +1,23 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="sicoob-sdk",
+    version="0.1.2",
+    description="SDK Python para integração com a API do Banco Sicoob",
+    long_description=open("README.md", encoding='utf-8').read(),
+    long_description_content_type="text/markdown",
+    author="Fábio Thomaz",
+    author_email="fabio@ladder.dev.br",
+    packages=find_packages(),
+    install_requires=[
+        "requests>=2.25.1",
+        "python-dotenv>=0.15.0",
+    ],
+    python_requires=">=3.7",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+    ],
+)

sicoob_sdk-0.1.0/sicoob/__init__.py

@@ -0,0 +1,52 @@
+"""Módulo principal do SDK Sicoob"""
+
+from .client import Sicoob
+from .conta_corrente import ContaCorrenteAPI
+from .pix import PixAPI
+from .boleto import BoletoAPI
+from .exceptions import (
+    SicoobError,
+    BoletoError,
+    BoletoEmissaoError,
+    BoletoConsultaError,
+    BoletoNaoEncontradoError,
+    ContaCorrenteError,
+    PixError,
+    AutenticacaoError,
+    ExtratoError,
+    SaldoError,
+    TransferenciaError,
+    CobrancaPixError,
+    CobrancaPixNaoEncontradaError,
+    CobrancaPixVencimentoError,
+    WebhookPixError,
+    WebhookPixNaoEncontradoError,
+    LoteCobrancaPixError,
+    QrCodePixError
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Sicoob",
+    "ContaCorrenteAPI",
+    "PixAPI",
+    "BoletoAPI",
+    "SicoobError",
+    "BoletoError",
+    "BoletoEmissaoError",
+    "BoletoConsultaError",
+    "BoletoNaoEncontradoError",
+    "ContaCorrenteError",
+    "PixError",
+    "AutenticacaoError",
+    "ExtratoError",
+    "SaldoError",
+    "TransferenciaError",
+    "CobrancaPixError",
+    "CobrancaPixNaoEncontradaError",
+    "CobrancaPixVencimentoError",
+    "WebhookPixError",
+    "WebhookPixNaoEncontradoError",
+    "LoteCobrancaPixError",
+    "QrCodePixError"
+]

sicoob_sdk-0.1.0/sicoob/api_client.py

@@ -0,0 +1,38 @@
+from typing import Dict
+import requests
+from .auth import OAuth2Client
+from .constants import BASE_URL, SANDBOX_URL
+
+
+class APIClientBase:
+    """Classe base para APIs do Sicoob"""
+
+    def __init__(
+        self,
+        oauth_client: OAuth2Client,
+        session: requests.Session,
+        sandbox_mode: bool = False,
+    ):
+        """Inicializa com cliente OAuth e sessão HTTP existente
+
+        Args:
+            oauth_client: Cliente OAuth2 para autenticação
+            session: Sessão HTTP existente
+            sandbox_mode: Se True, usa URL de sandbox (default: False)
+        """
+        self.sandbox_mode = sandbox_mode
+        self.oauth_client = oauth_client
+        self.session = session
+
+    def _get_base_url(self) -> str:
+        """Retorna a URL base conforme modo de operação"""
+        return SANDBOX_URL if self.sandbox_mode else BASE_URL
+
+    def _get_headers(self, scope) -> Dict[str, str]:
+        """Retorna headers padrão com token de acesso"""
+        token = self.oauth_client.get_access_token(scope)
+        return {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }

sicoob_sdk-0.1.0/sicoob/auth/__init__.py

@@ -0,0 +1,5 @@
+"""Módulo de autenticação do SDK Sicoob"""
+
+from .oauth import OAuth2Client
+
+__all__ = ["OAuth2Client"]

sicoob_sdk-0.1.0/sicoob/auth/oauth.py

@@ -0,0 +1,68 @@
+import os
+import time
+from dotenv import load_dotenv
+import requests
+
+
+class OAuth2Client:
+    """Cliente OAuth2 para autenticação com a API Sicoob"""
+
+    def __init__(
+        self, client_id=None, certificado=None, chave_privada=None
+    ):
+        """Inicializa o cliente OAuth2"""
+        load_dotenv()
+
+        self.client_id = client_id or os.getenv("SICOOB_CLIENT_ID")
+        self.certificado = certificado or os.getenv("SICOOB_CERTIFICADO")
+        self.chave_privada = chave_privada or os.getenv("SICOOB_CHAVE_PRIVADA")
+
+        self.token_url = "https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token"
+        self.token_cache = {}  # Cache de tokens por escopo
+        self.session = requests.Session()
+        self.session.cert = (self.certificado, self.chave_privada)
+
+    def get_access_token(self, scope=None):
+        """Obtém ou renova o token de acesso para o escopo especificado
+
+        Args:
+            scope: Escopo(s) necessário(s) para a API. Exemplos:
+                - Cobrança por Boleto: "boletos_inclusao boletos_consulta boletos_alteracao webhooks_alteracao webhooks_consulta webhooks_inclusao"
+                - Conta Corrente: "cco_consulta cco_transferencias openid"
+                - Recebimento no PIX: "cob.write cob.read cobv.write cobv.read lotecobv.write lotecobv.read pix.write pix.read webhook.read webhook.write payloadlocation.write payloadlocation.read"
+
+        Returns:
+            str: Token de acesso válido para o escopo solicitado
+        """
+        # Usa escopo padrão se não especificado (para compatibilidade)
+        if scope is None:
+            scope = "cco_extrato cco_consulta"
+
+        # Verifica se já existe token válido para este escopo
+        if scope in self.token_cache and not self._is_token_expired(scope):
+            return self.token_cache[scope]["access_token"]
+
+        token_data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "scope": scope,
+        }
+
+        response = self.session.post(self.token_url, data=token_data)
+        response.raise_for_status()
+
+        token_info = response.json()
+        token_info["expires_at"] = time.time() + token_info["expires_in"]
+
+        # Armazena o token no cache por escopo
+        self.token_cache[scope] = token_info
+
+        return token_info["access_token"]
+
+    def _is_token_expired(self, scope):
+        """Verifica se o token para o escopo especificado expirou"""
+        if scope not in self.token_cache or "expires_at" not in self.token_cache[scope]:
+            return True
+        return (
+            time.time() >= self.token_cache[scope]["expires_at"] - 60
+        )  # 60s de margem