| Name | pypix-api JSON |
| Version |
0.3.2
JSON |
| download |
| home_page | None |
| Summary | Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX |
| upload_time | 2025-07-30 12:41:45 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| 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.
|
| keywords |
pix
api
banco
pagamento
brasil
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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)
- [Banco do Brasil](#banco-do-brasil)
- [Sicoob](#sicoob)
- [Estrutura do Projeto](#estrutura-do-projeto)
- [Configuração](#configuração)
- [Parâmetros de Inicialização](#parâmetros-de-inicialização)
- [URLs das APIs](#urls-das-apis)
- [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
### Banco do Brasil
```python
from pypix_api.banks.bb import BancoDoBrasil
from pypix_api.auth.oauth2 import OAuth2Client
# Primeiro crie o cliente OAuth2
oauth = OAuth2Client(
client_id="SEU_CLIENT_ID",
cert="caminho/do/certificado.pem",
pvk="caminho/da/chave.key"
)
# Depois instancie o banco passando o OAuth2Client
bb = BancoDoBrasil(oauth=oauth)
# 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."
}
# Criar cobrança com vencimento
cobv = bb.criar_cobv(txid="uuid-unico", body=payload)
print(cobv)
```
### Sicoob
```python
from pypix_api.banks.sicoob import Sicoob
# Instanciação do Sicoob
sicoob = Sicoob(oauth=oauth) # Reutilizando o mesmo OAuth2Client
# Exemplo: Cobrança imediata
payload_cob = {
"calendario": {
"expiracao": 3600
},
"devedor": {
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"valor": {
"original": "37.00"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Pagamento de serviços."
}
cob = sicoob.criar_cob(txid="uuid-unico-2", body=payload_cob)
print(cob)
```
## 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
### Parâmetros de Inicialização
1. Primeiro crie uma instância de OAuth2Client:
```python
from pypix_api.auth.oauth2 import OAuth2Client
oauth = OAuth2Client(
client_id="SEU_CLIENT_ID", # ID do cliente fornecido pelo banco
cert="caminho/do/certificado.pem", # Certificado digital (.pem)
pvk="caminho/da/chave.key" # Chave privada (.key)
)
```
2. Depois instancie o banco passando o OAuth2Client:
```python
banco = BancoDoBrasil(oauth=oauth) # Ou Sicoob(oauth=oauth)
```
### URLs das APIs
As URLs base são configuradas automaticamente por cada banco:
- **Banco do Brasil**: Definido internamente pela classe `BBPixAPI`
- **Sicoob**: Definido internamente pela classe `SicoobPixAPI`
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "pypix-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "pix, api, banco, pagamento, brasil",
"author": null,
"author_email": "F\u00e1bio Thomaz <fabio@ladder.dev.br>",
"download_url": "https://files.pythonhosted.org/packages/77/06/bb995a19b151dc58253ef63fa7119f42aeb047e8ce60f5970e5729bd1430/pypix_api-0.3.2.tar.gz",
"platform": null,
"description": "# pypix-api\n\nBiblioteca em Python para comunica\u00e7\u00e3o com APIs banc\u00e1rias, focada na integra\u00e7\u00e3o com o PIX.\n\n## Sum\u00e1rio\n\n- [pypix-api](#pypix-api)\n - [Sum\u00e1rio](#sum\u00e1rio)\n - [Vis\u00e3o Geral](#vis\u00e3o-geral)\n - [Instala\u00e7\u00e3o](#instala\u00e7\u00e3o)\n - [Exemplo de Uso](#exemplo-de-uso)\n - [Banco do Brasil](#banco-do-brasil)\n - [Sicoob](#sicoob)\n - [Estrutura do Projeto](#estrutura-do-projeto)\n - [Configura\u00e7\u00e3o](#configura\u00e7\u00e3o)\n - [Par\u00e2metros de Inicializa\u00e7\u00e3o](#par\u00e2metros-de-inicializa\u00e7\u00e3o)\n - [URLs das APIs](#urls-das-apis)\n - [Testes](#testes)\n - [Contribui\u00e7\u00e3o](#contribui\u00e7\u00e3o)\n - [Licen\u00e7a](#licen\u00e7a)\n\n## Vis\u00e3o Geral\n\nO `pypix-api` facilita a integra\u00e7\u00e3o de sistemas Python com APIs banc\u00e1rias brasileiras, com \u00eanfase no ecossistema do PIX. A biblioteca abstrai autentica\u00e7\u00e3o, comunica\u00e7\u00e3o segura (MTLS/OAuth2), e opera\u00e7\u00f5es comuns de bancos como Banco do Brasil e Sicoob.\n\n## Instala\u00e7\u00e3o\n\nRecomenda-se o uso de ambiente virtual.\n\n```bash\npip install .\n```\n\nOu, para desenvolvimento:\n\n```bash\ngit clone https://github.com/seu-usuario/pypix-api.git\ncd pypix-api\npip install -e .\n```\n\n## Exemplo de Uso\n\n### Banco do Brasil\n\n```python\nfrom pypix_api.banks.bb import BancoDoBrasil\n\nfrom pypix_api.auth.oauth2 import OAuth2Client\n\n# Primeiro crie o cliente OAuth2\noauth = OAuth2Client(\n client_id=\"SEU_CLIENT_ID\",\n cert=\"caminho/do/certificado.pem\",\n pvk=\"caminho/da/chave.key\"\n)\n\n# Depois instancie o banco passando o OAuth2Client\nbb = BancoDoBrasil(oauth=oauth)\n\n# Exemplo: Cobran\u00e7a com Vencimento\npayload = {\n \"calendario\": {\n \"dataDeVencimento\": \"2025-12-31\",\n \"validadeAposVencimento\": 30\n },\n \"loc\": {\n \"id\": 789\n },\n \"devedor\": {\n \"logradouro\": \"Alameda Souza, Numero 80, Bairro Braz\",\n \"cidade\": \"Recife\",\n \"uf\": \"PE\",\n \"cep\": \"70011750\",\n \"cpf\": \"12345678909\",\n \"nome\": \"Francisco da Silva\"\n },\n \"valor\": {\n \"original\": \"123.45\",\n \"multa\": {\n \"modalidade\": \"2\",\n \"valorPerc\": \"15.00\"\n },\n \"juros\": {\n \"modalidade\": \"2\",\n \"valorPerc\": \"2.00\"\n },\n \"desconto\": {\n \"modalidade\": \"1\",\n \"descontoDataFixa\": [\n {\n \"data\": \"2025-11-30\",\n \"valorPerc\": \"30.00\"\n }\n ]\n }\n },\n \"chave\": \"5f84a4c5-c5cb-4599-9f13-7eb4d419dacc\",\n \"solicitacaoPagador\": \"Cobran\u00e7a dos servi\u00e7os prestados.\"\n}\n\n# Criar cobran\u00e7a com vencimento\ncobv = bb.criar_cobv(txid=\"uuid-unico\", body=payload)\nprint(cobv)\n```\n\n### Sicoob\n\n```python\nfrom pypix_api.banks.sicoob import Sicoob\n\n# Instancia\u00e7\u00e3o do Sicoob\nsicoob = Sicoob(oauth=oauth) # Reutilizando o mesmo OAuth2Client\n\n# Exemplo: Cobran\u00e7a imediata\npayload_cob = {\n \"calendario\": {\n \"expiracao\": 3600\n },\n \"devedor\": {\n \"cpf\": \"12345678909\",\n \"nome\": \"Francisco da Silva\"\n },\n \"valor\": {\n \"original\": \"37.00\"\n },\n \"chave\": \"5f84a4c5-c5cb-4599-9f13-7eb4d419dacc\",\n \"solicitacaoPagador\": \"Pagamento de servi\u00e7os.\"\n}\n\ncob = sicoob.criar_cob(txid=\"uuid-unico-2\", body=payload_cob)\nprint(cob)\n```\n\n## Estrutura do Projeto\n\n```\npypix_api/\n\u251c\u2500\u2500 auth/ # Autentica\u00e7\u00e3o (MTLS, OAuth2)\n\u251c\u2500\u2500 banks/ # Integra\u00e7\u00f5es com bancos (BB, Sicoob, m\u00e9todos PIX)\n\u251c\u2500\u2500 models/ # Modelos de dados do PIX\n\u251c\u2500\u2500 utils/ # Utilit\u00e1rios (HTTP client, helpers)\ntests/ # Testes automatizados\nopenapi.yaml # Especifica\u00e7\u00e3o OpenAPI (se aplic\u00e1vel)\npyproject.toml # Configura\u00e7\u00e3o do projeto Python\nMakefile # Comandos \u00fateis para desenvolvimento\n.env.exemplo # Exemplo de vari\u00e1veis de ambiente\n```\n\n## Configura\u00e7\u00e3o\n\n### Par\u00e2metros de Inicializa\u00e7\u00e3o\n\n1. Primeiro crie uma inst\u00e2ncia de OAuth2Client:\n```python\nfrom pypix_api.auth.oauth2 import OAuth2Client\n\noauth = OAuth2Client(\n client_id=\"SEU_CLIENT_ID\", # ID do cliente fornecido pelo banco\n cert=\"caminho/do/certificado.pem\", # Certificado digital (.pem)\n pvk=\"caminho/da/chave.key\" # Chave privada (.key)\n)\n```\n\n2. Depois instancie o banco passando o OAuth2Client:\n```python\nbanco = BancoDoBrasil(oauth=oauth) # Ou Sicoob(oauth=oauth)\n```\n\n### URLs das APIs\n\nAs URLs base s\u00e3o configuradas automaticamente por cada banco:\n\n- **Banco do Brasil**: Definido internamente pela classe `BBPixAPI`\n- **Sicoob**: Definido internamente pela classe `SicoobPixAPI`\n\nCrie um arquivo `.env` baseado em `.env.exemplo` com as credenciais e configura\u00e7\u00f5es necess\u00e1rias para autentica\u00e7\u00e3o e acesso \u00e0s APIs banc\u00e1rias.\n\n## Testes\n\nPara rodar os testes automatizados:\n\n```bash\nmake test\n```\nou diretamente com pytest:\n```bash\npytest\n```\n\n## Contribui\u00e7\u00e3o\n\nContribui\u00e7\u00f5es s\u00e3o bem-vindas! Siga os passos:\n\n1. Fork este reposit\u00f3rio\n2. Crie uma branch (`git checkout -b feature/nova-funcionalidade`)\n3. Commit suas altera\u00e7\u00f5es (`git commit -am 'Adiciona nova funcionalidade'`)\n4. Push para a branch (`git push origin feature/nova-funcionalidade`)\n5. Abra um Pull Request\n\n## Licen\u00e7a\n\nEste projeto est\u00e1 licenciado sob os termos da licen\u00e7a MIT.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Seu Nome\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Biblioteca em Python para comunica\u00e7\u00e3o com APIs banc\u00e1rias focada na integra\u00e7\u00e3o com o PIX",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/laddertech/pypix-api",
"Repository": "https://github.com/laddertech/pypix-api"
},
"split_keywords": [
"pix",
" api",
" banco",
" pagamento",
" brasil"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d69c1fb98dd379b005add07d876779a03874b4eda8cc40e108945d45103d514f",
"md5": "b426039b49f82ed090feccf9129f0dc1",
"sha256": "73073342c628ca866173b4367c6bd9e0f24474155f96a7d34bc89a622810cc9a"
},
"downloads": -1,
"filename": "pypix_api-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b426039b49f82ed090feccf9129f0dc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22788,
"upload_time": "2025-07-30T12:41:45",
"upload_time_iso_8601": "2025-07-30T12:41:45.094784Z",
"url": "https://files.pythonhosted.org/packages/d6/9c/1fb98dd379b005add07d876779a03874b4eda8cc40e108945d45103d514f/pypix_api-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7706bb995a19b151dc58253ef63fa7119f42aeb047e8ce60f5970e5729bd1430",
"md5": "f03050cb7d63d9e6d8bdd721592bc1be",
"sha256": "79fc8ffbe3e80d7ba96a93a1d057e93d6a5a9df49cd65a875ae5a23feab348a3"
},
"downloads": -1,
"filename": "pypix_api-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "f03050cb7d63d9e6d8bdd721592bc1be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16652,
"upload_time": "2025-07-30T12:41:45",
"upload_time_iso_8601": "2025-07-30T12:41:45.884809Z",
"url": "https://files.pythonhosted.org/packages/77/06/bb995a19b151dc58253ef63fa7119f42aeb047e8ce60f5970e5729bd1430/pypix_api-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 12:41:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "laddertech",
"github_project": "pypix-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pypix-api"
}
