Versão: 1.4.1 (cliente pip) | API: 1.5.0 | Python: 3.8+
Cliente Python oficial para a API de geração de Boletos Bancários Brasileiros.
- ✅ Interface Pythonic simples e intuitiva
- ✅ Suporte para 18 bancos brasileiros
- ✅ Retry automático com backoff exponencial
- ✅ TypedDict para tipagem estática
- ✅ Type hints completos
- ✅ Tratamento de erros robusto
- ✅ Validação de dados antes da geração
- ✅ Geração de PDF e imagens
- ✅ Logging configurável
- ✅ Sessão HTTP reutilizável
- ✅ Testes pytest completos (44 testes)
| Banco | Código | Status |
|---|---|---|
| Banco do Brasil | 001 | ✅ |
| Sicoob | 756 | ✅ |
| Bradesco | 237 | ✅ |
| Itaú | 341 | ✅ |
| Caixa Econômica | 104 | ✅ |
| Santander | 033 | ✅ |
| Sicredi | 748 | ✅ |
| Banrisul | 041 | ✅ |
| Banco C6 | 336 | ✅ (novo em v1.3.0) |
| + 9 outros | — | ✅ |
Veja docs/fields/all-banks.md para lista completa.
pip install boleto-cnab-clientgit clone https://github.com/Maxwbh/cobranca-api.git
cd cobranca-api/python-client
pip install -e .pip install -e ".[dev]"from boleto_cnab_client import BoletoClient
# Conectar à API local
client = BoletoClient('http://localhost:8000')
# Ou conectar à API em produção
client = BoletoClient('https://sua-api.onrender.com')# Dados do boleto
dados = {
"cedente": "Minha Empresa LTDA",
"documento_cedente": "12345678000100",
"sacado": "João da Silva",
"sacado_documento": "12345678900",
"agencia": "3073",
"conta_corrente": "12345678",
"convenio": "01234567",
"carteira": "18",
"nosso_numero": "123",
"valor": 150.00,
"data_vencimento": "2025/12/31"
}
# Validar antes de gerar
try:
resultado = client.validate('banco_brasil', dados)
if resultado['valid']:
print("✅ Dados válidos!")
else:
print(f"❌ Erros: {resultado['errors']}")
except Exception as e:
print(f"Erro: {e}")# Obter código de barras, linha digitável, etc.
response = client.get_boleto_data('banco_brasil', dados)
print(f"Nosso Número: {response.nosso_numero}")
print(f"Código de Barras: {response.codigo_barras}")
print(f"Linha Digitável: {response.linha_digitavel}")# Gerar PDF
pdf_bytes = client.generate_boleto('banco_brasil', dados, file_type='pdf')
# Salvar em arquivo
with open('boleto.pdf', 'wb') as f:
f.write(pdf_bytes)
print("✅ PDF gerado com sucesso!")from boleto_cnab_client import BoletoClient, BoletoValidationError
client = BoletoClient('http://localhost:8000')
dados_bb = {
"cedente": "Empresa Teste LTDA",
"documento_cedente": "12345678000100",
"sacado": "João da Silva",
"sacado_documento": "12345678900",
"sacado_endereco": "Rua Teste, 100, Centro, São Paulo, SP, CEP 01000000",
"agencia": "3073",
"conta_corrente": "12345678",
"convenio": "01234567", # OBRIGATÓRIO para BB
"carteira": "18",
"nosso_numero": "123",
"numero_documento": "CTR-2025-001",
"valor": 1500.00,
"data_vencimento": "2025/12/31",
"data_documento": "2025/11/27",
"especie_documento": "DM",
"aceite": "N",
"local_pagamento": "Pagavel em qualquer banco ate o vencimento",
"instrucao1": "Não receber após o vencimento"
}
try:
# 1. Validar
validation = client.validate('banco_brasil', dados_bb)
print(f"Validação: {validation['valid']}")
# 2. Obter dados
boleto = client.get_boleto_data('banco_brasil', dados_bb)
print(f"Código de Barras: {boleto.codigo_barras}")
print(f"Linha Digitável: {boleto.linha_digitavel}")
# 3. Gerar PDF
pdf = client.generate_boleto('banco_brasil', dados_bb)
with open('boleto_bb.pdf', 'wb') as f:
f.write(pdf)
print("✅ Sucesso!")
except BoletoValidationError as e:
print(f"❌ Erro de validação: {e}")
except Exception as e:
print(f"❌ Erro: {e}")dados_sicoob = {
"cedente": "Cooperativa Teste",
"documento_cedente": "98765432000100",
"sacado": "Maria Santos",
"sacado_documento": "98765432100",
"sacado_endereco": "Av. Principal, 50, Bairro, Rio de Janeiro, RJ, CEP 20000000",
"agencia": "4327",
"conta_corrente": "417270",
"carteira": "1",
"variacao": "01", # OBRIGATÓRIO para Sicoob
"convenio": "229385", # OBRIGATÓRIO para Sicoob
"nosso_numero": "7890",
"numero_documento": "NF-2025-1234",
"valor": 2500.00,
"data_vencimento": "2025/12/31",
"data_documento": "2025/11/27",
"especie_documento": "DM",
"aceite": "N", # DEVE ser 'N' para Sicoob
"local_pagamento": "Pagavel em qualquer banco ate o vencimento",
"instrucao1": "Não receber após 30 dias"
}
# Gerar PDF
pdf = client.generate_boleto('sicoob', dados_sicoob)
with open('boleto_sicoob.pdf', 'wb') as f:
f.write(pdf)
print("✅ Boleto Sicoob gerado!")from boleto_cnab_client import (
BoletoClient,
BoletoValidationError,
BoletoConnectionError,
BoletoTimeoutError
)
client = BoletoClient('http://localhost:8000', timeout=10, retries=3)
try:
boleto = client.get_boleto_data('banco_brasil', dados)
except BoletoValidationError as e:
print(f"Dados inválidos: {e}")
print(f"Detalhes: {e.details}")
except BoletoConnectionError as e:
print(f"Erro de conexão: {e}")
except BoletoTimeoutError as e:
print(f"Timeout: {e}")
except Exception as e:
print(f"Erro inesperado: {e}")from boleto_cnab_client import BoletoClient
from boleto_cnab_client.models import BoletoData
# Criar objeto BoletoData
boleto_data = BoletoData(
cedente="Minha Empresa",
documento_cedente="12345678000100",
sacado="João da Silva",
sacado_documento="12345678900",
agencia="3073",
conta_corrente="12345678",
convenio="01234567",
carteira="18",
nosso_numero="123",
valor=150.00,
data_vencimento="2025/12/31"
)
# Converter para dicionário
dados_dict = boleto_data.to_dict()
client = BoletoClient('http://localhost:8000')
pdf = client.generate_boleto('banco_brasil', dados_dict)client = BoletoClient('http://localhost:8000')
try:
status = client.health_check()
print(f"Status: {status['status']}")
print(f"Mensagem: {status['message']}")
except Exception as e:
print(f"API não está disponível: {e}")# Configurar timeout e número de retries
client = BoletoClient(
base_url='http://localhost:8000',
timeout=30, # 30 segundos
retries=5 # 5 tentativas
)import logging
# Configurar logging
logging.basicConfig(level=logging.DEBUG)
client = BoletoClient('http://localhost:8000')
# Agora você verá logs detalhados das requisiçõesimport requests
from boleto_cnab_client import BoletoClient
# Criar sessão customizada
session = requests.Session()
session.headers.update({'User-Agent': 'MeuApp/1.0'})
client = BoletoClient('http://localhost:8000')
client.session = session| Campo | Tipo | Descrição |
|---|---|---|
cedente |
string | Nome da empresa/pessoa que está emitindo o boleto |
documento_cedente |
string | CNPJ ou CPF do cedente |
sacado |
string | Nome do pagador |
sacado_documento |
string | CPF ou CNPJ do pagador |
agencia |
string | Número da agência |
conta_corrente |
string | Número da conta corrente |
nosso_numero |
string | Número do boleto (único) |
valor |
float | Valor do boleto em reais |
data_vencimento |
string | Data de vencimento (YYYY/MM/DD) |
convenio: OBRIGATÓRIO (4-8 dígitos)carteira: Padrão "18"
convenio: OBRIGATÓRIOvariacao: OBRIGATÓRIOaceite: DEVE ser "N" (não "S")especie_documento: OBRIGATÓRIO ("DM")
digito_conta: OBRIGATÓRIOcarteira: Ex: "09"
convenio: OBRIGATÓRIOdigito_conta: OBRIGATÓRIOnosso_numero: 15 dígitos (preencher com zeros)
Consulte a documentação completa para detalhes de todos os bancos.
O campo linha_digitavel pode retornar None no Sicoob quando usando get_boleto_data(). Isso NÃO é um bug. A linha digitável sempre aparece corretamente no PDF gerado.
boleto = client.get_boleto_data('sicoob', dados)
if boleto.linha_digitavel:
print(f"Linha Digitável: {boleto.linha_digitavel}")
else:
print("Linha digitável não disponível via /data, mas estará no PDF")A API faz mapeamento automático. Você pode usar numero_documento no cliente:
dados = {
"numero_documento": "NF-2025-001", # Cliente usa este
# API converte automaticamente para 'documento_numero'
}# Instalar dependências de desenvolvimento
pip install -e ".[dev]"
# Executar testes
pytest
# Com cobertura
pytest --cov=boleto_cnab_client
# Testes específicos
pytest tests/test_client.py -vContribuições são bem-vindas! Por favor:
- Fork o repositório
- Crie uma branch para sua feature (
git checkout -b feature/nova-feature) - Commit suas mudanças (
git commit -am 'Adiciona nova feature') - Push para a branch (
git push origin feature/nova-feature) - Abra um Pull Request
Veja CHANGELOG.md para histórico de versões.
Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.
Maxwell da Silva Oliveira
- GitHub: @Maxwbh
- Email: maxwbh@gmail.com
Este cliente utiliza a API Boleto CNAB, que por sua vez usa a gem BRCobranca para geração de boletos bancários brasileiros.
O endpoint POST /api/ofx/parse permite parsear extratos bancários OFX.
O cliente Python ainda não possui um método helper dedicado, mas pode ser usado via requests:
import requests
with open('extrato.ofx', 'rb') as f:
response = requests.post(
'http://localhost:8000/api/ofx/parse',
files={'file': f},
data={'somente_creditos': 'true'} # opcional
)
data = response.json()
print(f"Banco: {data['banco']['org']}")
print(f"Total de créditos: {data['resumo']['soma_creditos']}")
for tx in data['transacoes']:
nn = tx.get('nosso_numero_extraido')
if nn:
print(f" {tx['data']} R$ {tx['valor']:.2f} nosso_numero={nn}")Veja docs/api/ofx-parsing.md para detalhes do endpoint e docs/openapi.yaml para o schema completo.
Versão: 1.4.1 (cliente) / API 1.5.0
- Suporte ao Banco C6 (336) — basta usar
bank='banco_c6'com carteira'10'ou'20' - PIX híbrido documentado (8 bancos) — adicione
emvao payload - brcobranca atualizado para v12.6.1
- Endpoint
POST /api/ofx/parsepara parsing de extratos OFX - Extração automática de
nosso_numeropor banco - Fix:
RetryErrortratado comoBoletoAPIErrorno client
- TypedDict para tipagem estática (
BoletoDataDict,BoletoResponseDict) - Testes pytest completos
pyproject.toml(PEP 517/518)- Compatibilidade com Python 3.8+ via
typing_extensions