pypix-api 0.0.3__tar.gz

pypix_api-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Seu Nome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypix_api-0.0.3/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: pypix-api
+Version: 0.0.3
+Summary: Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX
+Author-email: Fábio Thomaz <fabio@ladder.dev.br>
+License: MIT License
+        
+        Copyright (c) 2025 Seu Nome
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/laddertech/pypix-api
+Project-URL: Repository, https://github.com/laddertech/pypix-api
+Keywords: pix,api,banco,pagamento,brasil
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.1
+Requires-Dist: python-dotenv>=0.15.0
+Requires-Dist: requests-pkcs12>=1.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.6.1; extra == "dev"
+Requires-Dist: build>=1.2.2.post1; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+Requires-Dist: ruff>=0.4.2; extra == "dev"
+Dynamic: license-file
+
+# pypix-api
+
+Biblioteca em Python para comunicação com APIs bancárias, focada na integração com o PIX.
+
+## Sumário
+
+- [pypix-api](#pypix-api)
+  - [Sumário](#sumário)
+  - [Visão Geral](#visão-geral)
+  - [Instalação](#instalação)
+  - [Exemplo de Uso](#exemplo-de-uso)
+  - [Estrutura do Projeto](#estrutura-do-projeto)
+  - [Configuração](#configuração)
+  - [Testes](#testes)
+  - [Contribuição](#contribuição)
+  - [Licença](#licença)
+
+## Visão Geral
+
+O `pypix-api` facilita a integração de sistemas Python com APIs bancárias brasileiras, com ênfase no ecossistema do PIX. A biblioteca abstrai autenticação, comunicação segura (MTLS/OAuth2), e operações comuns de bancos como Banco do Brasil e Sicoob.
+
+## Instalação
+
+Recomenda-se o uso de ambiente virtual.
+
+```bash
+pip install .
+```
+
+Ou, para desenvolvimento:
+
+```bash
+git clone https://github.com/seu-usuario/pypix-api.git
+cd pypix-api
+pip install -e .
+```
+
+## Exemplo de Uso
+
+```python
+from pypix_api.banks.bb import BancoDoBrasil
+
+# Instanciação do banco (OAuth2 é inicializado internamente)
+bb = BancoDoBrasil(
+    client_id="SEU_CLIENT_ID",
+    client_secret="SEU_CLIENT_SECRET",
+    cert_path="caminho/do/certificado.pem",
+    key_path="caminho/da/chave.key"
+)
+
+# Exemplo: Cobrança com Vencimento
+payload = {
+    "calendario": {
+        "dataDeVencimento": "2025-12-31",
+        "validadeAposVencimento": 30
+    },
+    "loc": {
+        "id": 789
+    },
+    "devedor": {
+        "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
+        "cidade": "Recife",
+        "uf": "PE",
+        "cep": "70011750",
+        "cpf": "12345678909",
+        "nome": "Francisco da Silva"
+    },
+    "valor": {
+        "original": "123.45",
+        "multa": {
+        "modalidade": "2",
+        "valorPerc": "15.00"
+        },
+        "juros": {
+        "modalidade": "2",
+        "valorPerc": "2.00"
+        },
+        "desconto": {
+        "modalidade": "1",
+        "descontoDataFixa": [
+            {
+            "data": "2025-11-30",
+            "valorPerc": "30.00"
+            }
+        ]
+        }
+    },
+    "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
+    "solicitacaoPagador": "Cobrança dos serviços prestados."
+    }
+cobv = bb.criar_cobv(txid="uuid-unico", body=payload)
+print(cobv)
+```
+
+## Estrutura do Projeto
+
+```
+pypix_api/
+├── auth/           # Autenticação (MTLS, OAuth2)
+├── banks/          # Integrações com bancos (BB, Sicoob, métodos PIX)
+├── models/         # Modelos de dados do PIX
+├── utils/          # Utilitários (HTTP client, helpers)
+tests/              # Testes automatizados
+openapi.yaml        # Especificação OpenAPI (se aplicável)
+pyproject.toml      # Configuração do projeto Python
+Makefile            # Comandos úteis para desenvolvimento
+.env.exemplo        # Exemplo de variáveis de ambiente
+```
+
+## Configuração
+
+Crie um arquivo `.env` baseado em `.env.exemplo` com as credenciais e configurações necessárias para autenticação e acesso às APIs bancárias.
+
+## Testes
+
+Para rodar os testes automatizados:
+
+```bash
+make test
+```
+ou diretamente com pytest:
+```bash
+pytest
+```
+
+## Contribuição
+
+Contribuições são bem-vindas! Siga os passos:
+
+1. Fork este repositório
+2. Crie uma branch (`git checkout -b feature/nova-funcionalidade`)
+3. Commit suas alterações (`git commit -am 'Adiciona nova funcionalidade'`)
+4. Push para a branch (`git push origin feature/nova-funcionalidade`)
+5. Abra um Pull Request
+
+## Licença
+
+Este projeto está licenciado sob os termos da licença MIT.

pypix_api-0.0.3/README.md

@@ -0,0 +1,138 @@
+# pypix-api
+
+Biblioteca em Python para comunicação com APIs bancárias, focada na integração com o PIX.
+
+## Sumário
+
+- [pypix-api](#pypix-api)
+  - [Sumário](#sumário)
+  - [Visão Geral](#visão-geral)
+  - [Instalação](#instalação)
+  - [Exemplo de Uso](#exemplo-de-uso)
+  - [Estrutura do Projeto](#estrutura-do-projeto)
+  - [Configuração](#configuração)
+  - [Testes](#testes)
+  - [Contribuição](#contribuição)
+  - [Licença](#licença)
+
+## Visão Geral
+
+O `pypix-api` facilita a integração de sistemas Python com APIs bancárias brasileiras, com ênfase no ecossistema do PIX. A biblioteca abstrai autenticação, comunicação segura (MTLS/OAuth2), e operações comuns de bancos como Banco do Brasil e Sicoob.
+
+## Instalação
+
+Recomenda-se o uso de ambiente virtual.
+
+```bash
+pip install .
+```
+
+Ou, para desenvolvimento:
+
+```bash
+git clone https://github.com/seu-usuario/pypix-api.git
+cd pypix-api
+pip install -e .
+```
+
+## Exemplo de Uso
+
+```python
+from pypix_api.banks.bb import BancoDoBrasil
+
+# Instanciação do banco (OAuth2 é inicializado internamente)
+bb = BancoDoBrasil(
+    client_id="SEU_CLIENT_ID",
+    client_secret="SEU_CLIENT_SECRET",
+    cert_path="caminho/do/certificado.pem",
+    key_path="caminho/da/chave.key"
+)
+
+# Exemplo: Cobrança com Vencimento
+payload = {
+    "calendario": {
+        "dataDeVencimento": "2025-12-31",
+        "validadeAposVencimento": 30
+    },
+    "loc": {
+        "id": 789
+    },
+    "devedor": {
+        "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
+        "cidade": "Recife",
+        "uf": "PE",
+        "cep": "70011750",
+        "cpf": "12345678909",
+        "nome": "Francisco da Silva"
+    },
+    "valor": {
+        "original": "123.45",
+        "multa": {
+        "modalidade": "2",
+        "valorPerc": "15.00"
+        },
+        "juros": {
+        "modalidade": "2",
+        "valorPerc": "2.00"
+        },
+        "desconto": {
+        "modalidade": "1",
+        "descontoDataFixa": [
+            {
+            "data": "2025-11-30",
+            "valorPerc": "30.00"
+            }
+        ]
+        }
+    },
+    "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
+    "solicitacaoPagador": "Cobrança dos serviços prestados."
+    }
+cobv = bb.criar_cobv(txid="uuid-unico", body=payload)
+print(cobv)
+```
+
+## Estrutura do Projeto
+
+```
+pypix_api/
+├── auth/           # Autenticação (MTLS, OAuth2)
+├── banks/          # Integrações com bancos (BB, Sicoob, métodos PIX)
+├── models/         # Modelos de dados do PIX
+├── utils/          # Utilitários (HTTP client, helpers)
+tests/              # Testes automatizados
+openapi.yaml        # Especificação OpenAPI (se aplicável)
+pyproject.toml      # Configuração do projeto Python
+Makefile            # Comandos úteis para desenvolvimento
+.env.exemplo        # Exemplo de variáveis de ambiente
+```
+
+## Configuração
+
+Crie um arquivo `.env` baseado em `.env.exemplo` com as credenciais e configurações necessárias para autenticação e acesso às APIs bancárias.
+
+## Testes
+
+Para rodar os testes automatizados:
+
+```bash
+make test
+```
+ou diretamente com pytest:
+```bash
+pytest
+```
+
+## Contribuição
+
+Contribuições são bem-vindas! Siga os passos:
+
+1. Fork este repositório
+2. Crie uma branch (`git checkout -b feature/nova-funcionalidade`)
+3. Commit suas alterações (`git commit -am 'Adiciona nova funcionalidade'`)
+4. Push para a branch (`git push origin feature/nova-funcionalidade`)
+5. Abra um Pull Request
+
+## Licença
+
+Este projeto está licenciado sob os termos da licença MIT.

pypix_api-0.0.3/pypix_api/auth/mtls.py

@@ -0,0 +1,34 @@
+from typing import BinaryIO
+
+import requests
+import requests_pkcs12
+
+
+def get_session_with_mtls(
+    cert: str | None = None,
+    pvk: str | None = None,
+    cert_pfx: str | bytes | BinaryIO | None = None,
+    pwd_pfx: str | None = None,
+    sandbox_mode: bool = False,
+) -> requests.Session:
+    session = requests.Session()
+
+    if not sandbox_mode:
+        if cert_pfx and pwd_pfx:
+            # Configura autenticação com PFX
+            pkcs12_adapter = requests_pkcs12.Pkcs12Adapter(
+                pkcs12_data=cert_pfx if isinstance(cert_pfx, bytes) else None,
+                pkcs12_filename=cert_pfx if isinstance(cert_pfx, str) else None,
+                pkcs12_password=pwd_pfx,
+            )
+            session.mount('https://', pkcs12_adapter)
+        elif cert and pvk:
+            # Configura autenticação com PEM (manter compatibilidade)
+            session.cert = (cert, pvk)
+        else:
+            raise ValueError(
+                'É necessário fornecer certificado e chave privada (PEM) '
+                'ou certificado PFX e senha'
+            )
+
+    return session

pypix_api-0.0.3/pypix_api/auth/oauth2.py

@@ -0,0 +1,99 @@
+import os
+import time
+import requests
+from typing import BinaryIO
+from dotenv import load_dotenv
+
+from pypix_api.auth.mtls import get_session_with_mtls
+
+
+class OAuth2Client:
+    """Cliente OAuth2 para autenticação com a API"""
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str | None = None,
+        cert: str | None = None,
+        pvk: str | None = None,
+        cert_pfx: str | bytes | BinaryIO | None = None,
+        pwd_pfx: str | None = None,
+        sandbox_mode: bool = False,
+    ) -> None:
+        """Inicializa o cliente OAuth2
+
+        Args:
+            client_id: Client ID para autenticação OAuth2
+            cert: Path para o certificado PEM (opcional)
+            pvk: Path para a chave privada PEM (opcional)
+            cert_pfx: Path ou dados do certificado PFX (opcional)
+            pwd_pfx: Senha do certificado PFX (opcional)
+            sandbox_mode: Se True, não requer certificado (default: False)
+        """
+        load_dotenv()
+
+        self.client_id = client_id or os.getenv('CLIENT_ID')
+        self.cert = cert or os.getenv('CERT')
+        self.pvk = pvk or os.getenv('PVK')
+        self.cert_pfx = cert_pfx or os.getenv('CERT_PFX')
+        self.pwd_pfx = pwd_pfx or os.getenv('PWD_PFX')
+
+        self.token_url = token_url  # URL de autenticação OAuth2
+        self.token_cache = {}  # Cache de tokens por escopo
+        self.session = requests.Session()
+
+        self.sandbox_mode = sandbox_mode
+
+        if not self.sandbox_mode:
+            self.session = get_session_with_mtls(
+                cert=self.cert,
+                pvk=self.pvk,
+                cert_pfx=self.cert_pfx,
+                pwd_pfx=self.pwd_pfx,
+                sandbox_mode=self.sandbox_mode,
+            )
+
+    def get_token(self, scope: str | None = None) -> str:
+        """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: str) -> bool:
+        """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

pypix_api-0.0.3/pypix_api/banks/base.py

@@ -0,0 +1,50 @@
+from abc import ABC
+from typing import BinaryIO
+from pypix_api.auth.oauth2 import OAuth2Client
+from pypix_api.banks.cobv_methods import CobVMethods
+
+
+class BankPixAPIBase(CobVMethods, ABC):
+    """Classe base abstrata para clientes Pix de bancos."""
+
+    BASE_URL = None
+    TOKEN_URL = None
+    SCOPES = None
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        cert: str | None = None,
+        pvk: str | None = None,
+        cert_pfx: str | bytes | BinaryIO | None = None,
+        pwd_pfx: str | None = None,
+        sandbox_mode: bool = False,
+    ) -> None:
+        if not self.BASE_URL or not self.TOKEN_URL or not self.SCOPES:
+            raise ValueError(
+                'BASE_URL, TOKEN_URL e SCOPES devem ser definidos na subclasse.'
+            )
+        self.sandbox_mode = sandbox_mode
+        self.client_id = client_id
+
+        self.oauth = OAuth2Client(
+            token_url=self.TOKEN_URL,
+            client_id=client_id,
+            cert=cert,
+            pvk=pvk,
+            cert_pfx=cert_pfx,
+            pwd_pfx=pwd_pfx,
+            sandbox_mode=sandbox_mode,
+        )
+        self.session = self.oauth.session
+
+    def _create_headers(self) -> dict[str, str]:
+        """
+        Cria os headers necessários para as requisições.
+        """
+        token = self.oauth.get_token()
+        return {
+            'Authorization': f'Bearer {token}',
+            'Content-Type': 'application/json',
+            'client_id': self.client_id or '',
+        }

pypix_api-0.0.3/pypix_api/banks/bb.py

@@ -0,0 +1,18 @@
+from pypix_api.banks.base import BankPixAPIBase
+
+
+class BBPixAPI(BankPixAPIBase):
+    """Banco do Brasil API client for Pix operations."""
+
+    BASE_URL = "https://api.bb.com.br/pix/v1"
+    SANDBOX_BASE_URL = "https://api.sandbox.bb.com.br/pix/v1"
+    TOKEN_URL = "https://oauth.bb.com.br/oauth/token"
+    SCOPES = "pix.read pix.write"
+
+    def get_base_url(self) -> str:
+        """
+        Retorna a URL base da API, diferenciando entre produção e sandbox.
+        """
+        if self.sandbox_mode:
+            return self.SANDBOX_BASE_URL
+        return self.BASE_URL

pypix_api-0.0.3/pypix_api/banks/cobv_methods.py

@@ -0,0 +1,101 @@
+"""
+Módulo cobv_methods.py
+
+Este módulo define a classe CobVMethods, que implementa métodos para
+  integração com cobranças Pix com vencimento (CobV) via API bancária.
+Inclui operações para criar, revisar, consultar e listar cobranças com vencimento,
+  utilizando autenticação OAuth2 e requisições HTTP.
+
+Principais funcionalidades:
+- Criação de cobrança com vencimento (CobV)
+- Revisão de cobrança com vencimento
+- Consulta de cobrança por txid
+- Listagem de cobranças por período e filtros
+
+Dependências:
+- OAuth2 para autenticação (self.oauth)
+- Cliente HTTP de sessão (self.session)
+- Python 3.10+ (tipos nativos)
+
+Autor: [Fabio Thomaz(fabio@ladder.dev.br)]
+"""
+
+from typing import Any
+
+
+class CobVMethods:  # pylint: disable=E1101
+    """
+    Métodos para lidar com cobrança Pix com vencimento (CobV).
+    """
+
+    def criar_cobv(self, txid: str, body: dict[str, Any]) -> dict[str, Any]:
+        """
+        Cria uma cobrança com vencimento (CobV).
+        """
+        headers = self._create_headers()
+        url = f'{self.get_base_url()}/cobv/{txid}'
+        resp = self.session.put(url, headers=headers, json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    def revisar_cobv(self, txid: str, body: dict[str, Any]) -> dict[str, Any]:
+        """
+        Revisa uma cobrança com vencimento (CobV).
+        """
+        headers = self._create_headers()
+        url = f'{self.get_base_url()}/cobv/{txid}'
+        resp = self.session.patch(url, headers=headers, json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+    def consultar_cobv(
+        self, txid: str, revisao: int | None
+    ) -> dict[str, Any]:
+        """
+        Consulta uma cobrança com vencimento (CobV) por txid.
+        """
+        headers = self._create_headers()
+        params = {}
+        if revisao is not None:
+            params['revisao'] = revisao
+        url = f'{self.get_base_url()}/cobv/{txid}'
+        resp = self.session.get(url, headers=headers, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def listar_cobv(
+        self,
+        inicio: str,
+        fim: str,
+        cpf: str | None = None,
+        cnpj: str | None = None,
+        location_presente: bool | None = None,
+        status: str | None = None,
+        lote_cob_v_id: int | None = None,
+        pagina_atual: int | None = None,
+        itens_por_pagina: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Consulta lista de cobranças com vencimento (CobV).
+        """
+        headers = self._create_headers()
+        params = {'inicio': inicio, 'fim': fim}
+        if cpf:
+            params['cpf'] = cpf
+        if cnpj:
+            params['cnpj'] = cnpj
+        if location_presente is not None:
+            params['locationPresente'] = str(location_presente).lower()
+        if status:
+            params['status'] = status
+        if lote_cob_v_id is not None:
+            params['loteCobVId'] = lote_cob_v_id
+        if pagina_atual is not None:
+            params['paginaAtual'] = pagina_atual
+        if itens_por_pagina is not None:
+            params['itensPorPagina'] = itens_por_pagina
+
+        url = f'{self.get_base_url()}/cobv'
+        resp = self.session.get(url, headers=headers, params=params)
+        resp.raise_for_status()
+        return resp.json()

pypix_api-0.0.3/pypix_api/banks/sicoob.py

@@ -0,0 +1,20 @@
+from pypix_api.banks.base import BankPixAPIBase
+
+
+class SicoobPixAPI(BankPixAPIBase):
+    """Sicoob API client for Pix operations."""
+
+    BASE_URL = "https://api.sicoob.com.br/pix/api/v2"
+    SANDBOX_BASE_URL = "https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2"
+    TOKEN_URL = (
+        "https://auth.sicoob.com.br/auth/realms/sicoob/protocol/openid-connect/token"
+    )
+    SCOPES = "cob.read cob.write pix.read pix.write"
+
+    def get_base_url(self) -> str:
+        """
+        Retorna a URL base da API, diferenciando entre produção e sandbox.
+        """
+        if self.sandbox_mode:
+            return self.SANDBOX_BASE_URL
+        return self.BASE_URL

pypix_api-0.0.3/pypix_api/models/pix.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class PixCobranca:
+    txid: str
+    valor: float
+    status: str
+    chave: str

pypix_api-0.0.3/pypix_api/utils/http_client.py

@@ -0,0 +1,5 @@
+import requests
+
+
+def get(url, headers=None, cert=None):
+    return requests.get(url, headers=headers, cert=cert)

pypix_api-0.0.3/pypix_api.egg-info/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: pypix-api
+Version: 0.0.3
+Summary: Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX
+Author-email: Fábio Thomaz <fabio@ladder.dev.br>
+License: MIT License
+        
+        Copyright (c) 2025 Seu Nome
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/laddertech/pypix-api
+Project-URL: Repository, https://github.com/laddertech/pypix-api
+Keywords: pix,api,banco,pagamento,brasil
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.1
+Requires-Dist: python-dotenv>=0.15.0
+Requires-Dist: requests-pkcs12>=1.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.6.1; extra == "dev"
+Requires-Dist: build>=1.2.2.post1; extra == "dev"
+Requires-Dist: twine>=6.1.0; extra == "dev"
+Requires-Dist: ruff>=0.4.2; extra == "dev"
+Dynamic: license-file
+
+# pypix-api
+
+Biblioteca em Python para comunicação com APIs bancárias, focada na integração com o PIX.
+
+## Sumário
+
+- [pypix-api](#pypix-api)
+  - [Sumário](#sumário)
+  - [Visão Geral](#visão-geral)
+  - [Instalação](#instalação)
+  - [Exemplo de Uso](#exemplo-de-uso)
+  - [Estrutura do Projeto](#estrutura-do-projeto)
+  - [Configuração](#configuração)
+  - [Testes](#testes)
+  - [Contribuição](#contribuição)
+  - [Licença](#licença)
+
+## Visão Geral
+
+O `pypix-api` facilita a integração de sistemas Python com APIs bancárias brasileiras, com ênfase no ecossistema do PIX. A biblioteca abstrai autenticação, comunicação segura (MTLS/OAuth2), e operações comuns de bancos como Banco do Brasil e Sicoob.
+
+## Instalação
+
+Recomenda-se o uso de ambiente virtual.
+
+```bash
+pip install .
+```
+
+Ou, para desenvolvimento:
+
+```bash
+git clone https://github.com/seu-usuario/pypix-api.git
+cd pypix-api
+pip install -e .
+```
+
+## Exemplo de Uso
+
+```python
+from pypix_api.banks.bb import BancoDoBrasil
+
+# Instanciação do banco (OAuth2 é inicializado internamente)
+bb = BancoDoBrasil(
+    client_id="SEU_CLIENT_ID",
+    client_secret="SEU_CLIENT_SECRET",
+    cert_path="caminho/do/certificado.pem",
+    key_path="caminho/da/chave.key"
+)
+
+# Exemplo: Cobrança com Vencimento
+payload = {
+    "calendario": {
+        "dataDeVencimento": "2025-12-31",
+        "validadeAposVencimento": 30
+    },
+    "loc": {
+        "id": 789
+    },
+    "devedor": {
+        "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
+        "cidade": "Recife",
+        "uf": "PE",
+        "cep": "70011750",
+        "cpf": "12345678909",
+        "nome": "Francisco da Silva"
+    },
+    "valor": {
+        "original": "123.45",
+        "multa": {
+        "modalidade": "2",
+        "valorPerc": "15.00"
+        },
+        "juros": {
+        "modalidade": "2",
+        "valorPerc": "2.00"
+        },
+        "desconto": {
+        "modalidade": "1",
+        "descontoDataFixa": [
+            {
+            "data": "2025-11-30",
+            "valorPerc": "30.00"
+            }
+        ]
+        }
+    },
+    "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
+    "solicitacaoPagador": "Cobrança dos serviços prestados."
+    }
+cobv = bb.criar_cobv(txid="uuid-unico", body=payload)
+print(cobv)
+```
+
+## Estrutura do Projeto
+
+```
+pypix_api/
+├── auth/           # Autenticação (MTLS, OAuth2)
+├── banks/          # Integrações com bancos (BB, Sicoob, métodos PIX)
+├── models/         # Modelos de dados do PIX
+├── utils/          # Utilitários (HTTP client, helpers)
+tests/              # Testes automatizados
+openapi.yaml        # Especificação OpenAPI (se aplicável)
+pyproject.toml      # Configuração do projeto Python
+Makefile            # Comandos úteis para desenvolvimento
+.env.exemplo        # Exemplo de variáveis de ambiente
+```
+
+## Configuração
+
+Crie um arquivo `.env` baseado em `.env.exemplo` com as credenciais e configurações necessárias para autenticação e acesso às APIs bancárias.
+
+## Testes
+
+Para rodar os testes automatizados:
+
+```bash
+make test
+```
+ou diretamente com pytest:
+```bash
+pytest
+```
+
+## Contribuição
+
+Contribuições são bem-vindas! Siga os passos:
+
+1. Fork este repositório
+2. Crie uma branch (`git checkout -b feature/nova-funcionalidade`)
+3. Commit suas alterações (`git commit -am 'Adiciona nova funcionalidade'`)
+4. Push para a branch (`git push origin feature/nova-funcionalidade`)
+5. Abra um Pull Request
+
+## Licença
+
+Este projeto está licenciado sob os termos da licença MIT.

pypix_api-0.0.3/pypix_api.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+pypix_api/__init__.py
+pypix_api.egg-info/PKG-INFO
+pypix_api.egg-info/SOURCES.txt
+pypix_api.egg-info/dependency_links.txt
+pypix_api.egg-info/requires.txt
+pypix_api.egg-info/top_level.txt
+pypix_api/auth/mtls.py
+pypix_api/auth/oauth2.py
+pypix_api/banks/base.py
+pypix_api/banks/bb.py
+pypix_api/banks/cobv_methods.py
+pypix_api/banks/sicoob.py
+pypix_api/models/pix.py
+pypix_api/utils/http_client.py
+tests/test_auth.py
+tests/test_banks.py
+tests/test_models.py
+tests/test_utils.py

pypix_api-0.0.3/pypix_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pypix_api-0.0.3/pypix_api.egg-info/requires.txt

@@ -0,0 +1,10 @@
+requests>=2.25.1
+python-dotenv>=0.15.0
+requests-pkcs12>=1.25
+
+[dev]
+pytest>=7.0.0
+pytest-mock>=3.6.1
+build>=1.2.2.post1
+twine>=6.1.0
+ruff>=0.4.2

pypix_api-0.0.3/pypix_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+pypix_api

pypix_api-0.0.3/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "pypix-api"
+version = "0.0.3"
+description = "Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Fábio Thomaz", email = "fabio@ladder.dev.br" }
+]
+license.file = "LICENSE"
+keywords = ["pix", "api", "banco", "pagamento", "brasil"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+    "requests>=2.25.1",
+    "python-dotenv>=0.15.0",
+    "requests-pkcs12>=1.25"
+]
+
+[project.urls]
+Homepage = "https://github.com/laddertech/pypix-api"
+Repository = "https://github.com/laddertech/pypix-api"
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.6.1",
+    "build>=1.2.2.post1",
+    "twine>=6.1.0",
+    "ruff>=0.4.2"
+]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+# Configurações base do Ruff
+line-length = 88
+exclude = [
+    ".venv",
+    "build",
+    "dist",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C",   # flake8-comprehensions
+    "UP",  # pyupgrade
+    "YTT", # flake8-2020
+    "ANN", # flake8-annotations
+    "S",   # flake8-bandit
+    "RUF", # Ruff-specific rules
+]
+ignore = [
+    "E501", # Line too long (handled by black)
+    "S101", # Use of print (handled by black)
+]
+
+# Configurações específicas
+[tool.ruff.lint.isort]
+known-first-party = ["pypix_api"]
+
+[tool.ruff.format]
+quote-style = "single"

pypix_api-0.0.3/setup.cfg

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

pypix_api-0.0.3/tests/test_auth.py

@@ -0,0 +1,23 @@
+from pypix_api.auth.oauth2 import OAuth2Client
+
+def test_oauth2client_init(monkeypatch):
+    class DummySession:
+        pass
+    monkeypatch.setattr("pypix_api.auth.oauth2.get_session_with_mtls", lambda *a, **kw: DummySession())
+    client = OAuth2Client(
+        token_url="token_url",
+        client_id="client_id",
+        cert="cert_path",
+        pvk="key_path",
+        cert_pfx="cert.pfx",
+        pwd_pfx="senha",
+        sandbox_mode=False,
+    )
+    assert client.client_id == "client_id"
+    assert client.cert == "cert_path"
+    assert client.pvk == "key_path"
+    assert client.cert_pfx == "cert.pfx"
+    assert client.pwd_pfx == "senha"
+    assert client.token_url == "token_url"
+    assert client.sandbox_mode is False
+    assert isinstance(client.session, DummySession)

pypix_api-0.0.3/tests/test_banks.py

@@ -0,0 +1,47 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from pypix_api.banks.base import BankPixAPIBase
+from pypix_api.banks.bb import BBPixAPI
+from pypix_api.banks.sicoob import SicoobPixAPI
+from pypix_api.banks.cobv_methods import CobVMethods
+
+class DummyCobVMethods(CobVMethods):
+    def criar_cobv(self, txid, body):
+        return {"txid": txid, "body": body}
+    def revisar_cobv(self, txid, body):
+        return {"txid": txid, "body": body}
+    def consultar_cobv(self, txid):
+        return {"txid": txid}
+    def listar_cobv(self):
+        return []
+
+def test_bankpixapibase_init():
+    class DummyBank(BankPixAPIBase, DummyCobVMethods):
+        BASE_URL = "https://dummy"
+        TOKEN_URL = "https://dummy/token"
+        SCOPES = ["dummy.scope"]
+
+    import sys
+    with patch("pypix_api.banks.base.OAuth2Client", MagicMock()), \
+         patch("pypix_api.auth.mtls.get_session_with_mtls", MagicMock(return_value=object())):
+        bank = DummyBank("id", "secret", "cert", "key")
+        assert hasattr(bank, "session")
+        assert hasattr(bank, "oauth")
+
+def test_bb_pix_api_inheritance():
+    with patch("pypix_api.banks.base.OAuth2Client", MagicMock()), \
+         patch("pypix_api.auth.mtls.get_session_with_mtls", MagicMock(return_value=object())):
+        api = BBPixAPI("id", "secret", "cert", "key")
+        assert isinstance(api, BankPixAPIBase)
+
+def test_sicoob_pix_api_inheritance():
+    with patch("pypix_api.banks.base.OAuth2Client", MagicMock()), \
+         patch("pypix_api.auth.mtls.get_session_with_mtls", MagicMock(return_value=object())):
+        api = SicoobPixAPI("id", "secret", "cert", "key")
+        assert isinstance(api, BankPixAPIBase)
+
+def test_cobv_methods_criar():
+    cobv = DummyCobVMethods()
+    result = cobv.criar_cobv("123", {"valor": 10})
+    assert result["txid"] == "123"
+    assert result["body"]["valor"] == 10

pypix_api-0.0.3/tests/test_models.py

@@ -0,0 +1,8 @@
+import pytest
+from pypix_api.models.pix import PixCobranca
+
+def test_pix_cobranca_init():
+    cobranca = PixCobranca(txid="abc123", valor=100.0, status="ATIVA", chave="minha-chave")
+    assert cobranca.txid == "abc123"
+    assert cobranca.valor == 100.0
+    assert cobranca.status == "ATIVA"

pypix_api-0.0.3/tests/test_utils.py

@@ -0,0 +1,20 @@
+import pytest
+from pypix_api.utils.http_client import get
+
+def test_get(monkeypatch):
+    class DummyResponse:
+        def __init__(self):
+            self.status_code = 200
+            self.text = "ok"
+        def json(self):
+            return {"result": "ok"}
+    def dummy_requests_get(url, headers=None, cert=None):
+        assert url == "http://test"
+        assert headers == {"Authorization": "Bearer token"}
+        assert cert == "cert.pem"
+        return DummyResponse()
+    monkeypatch.setattr("requests.get", dummy_requests_get)
+    response = get("http://test", headers={"Authorization": "Bearer token"}, cert="cert.pem")
+    assert response.status_code == 200
+    assert response.text == "ok"
+    assert response.json() == {"result": "ok"}