Uma plataforma única para emissão de boletos, remessas CNAB, processamento de retorno, Pix, Pix Automático e integração com as APIs dos bancos brasileiros.
Consuma de qualquer linguagem via HTTP — Python, Java, Node, PHP, C#, Go, Delphi, Oracle APEX e PL/SQL.

Swagger do Gateway →  ·  Swagger Offline →  ·  Engine PyCobrança →

Quick Start · Arquitetura · Casos de uso · Documentação · Reportar Bug

O que esta plataforma entrega: gateway para as APIs dos bancos (boleto registrado, Pix, Pix Automático, conciliação) · engine offline de boleto, CNAB 240/400 e carnê para 18 bancos · parsing de OFX · lote assíncrono com artefatos assinados · tudo por REST, em um único container 100% Python.

A Cobranca-API usa a PyCobrança — biblioteca open source 100% Python — como engine oficial de cobrança, responsável por:

A PyCobrança também pode ser usada diretamente em aplicações Python, sem esta API. ➡ github.com/Maxwbh/pyCobranca

Regra simples: app Python que roda tudo local → PyCobrança. Qualquer outra linguagem, ou precisa falar com a API do banco → Cobranca-API.

Dois caminhos, um contrato: o offline roda a engine PyCobrança dentro do próprio processo (sem rede, sem sidecar); o online fala com a API do banco (OAuth + mTLS) para cobrança registrada, Pix e conciliação.

Emitir cobrança no Brasil exige juntar peças que quase nunca vêm juntas: layout de boleto por banco, CNAB 240/400 com particularidades de cada convênio, QR Pix no padrão BACEN, conciliação por OFX e, ainda por cima, a API REST de cada instituição — cada uma com seu OAuth, seu mTLS e seu vocabulário.

A Cobranca-API entrega tudo isso atrás de um contrato REST único, num único container, em 100% Python. Quem chama não precisa saber se o boleto foi gerado localmente pela engine PyCobrança ou registrado na API do banco — o payload é o mesmo.

A proposta é ser a plataforma open source brasileira que unifica APIs bancárias, emissão de boletos, Pix, CNAB e OFX, utilizável a partir de qualquer linguagem: Oracle APEX, Java, C#, Node, PHP, Delphi, Go ou Python.

Exemplos reais gerados pela API (engine pyCobrança, Python puro), um por banco:

_{Banco do Brasil · Itaú · Santander · Caixa · C6 Bank · Sicoob · Bolepix (boleto híbrido com QR Pix) · Carnê (3 vias A4)  — e mais 12 bancos.}

💡 Todos acima saíram de uma chamada GET /api/boleto?bank=<banco>&type=pdf&data=<json> na demo ao vivo.

Se você precisa gerar boletos, processar arquivos CNAB ou conciliar pagamentos via OFX no Brasil, esta API resolve tudo via HTTP — sem instalar nada além de um container.

• 100% Python — Engine pyCobrança in-process: um runtime, um container, sem sidecar
• 18 bancos offline — boleto + CNAB (15 bancos com remessa, 26 combinações banco×layout, 7 com segmento PIX)
• Boleto registrado via API — C6 e Sicoob: Pix, Bolepix, Pix Automático, extrato e conciliação
• Lote assíncrono — POST /jobs/boletos e /jobs/cnab/remessas: 202 + job_id, falha por item isolada, artefatos com sha256 e webhook de conclusão
• Credenciais zero-knowledge — token bapi_; o servidor não decifra sem ele
• Carnê 3-vias — N parcelas em PDF A4
• Swagger UI — interativo em /docs (gateway) e /api/docs (offline)
• Docker ready — imagem única, deploy em 1 minuto no Render, Railway ou qualquer cloud

git clone https://github.com/Maxwbh/cobranca-api.git && cd cobranca-api

# Docker (serviço único 100% Python)
docker compose up --build

# Swagger UI
open http://localhost:8000/docs       # gateway REST (C6/Sicoob, Pix)
open http://localhost:8000/api/docs   # offline (boleto/CNAB/OFX)

curl "http://localhost:8000/api/boleto?bank=banco_brasil&type=pdf&include_data=true&data=$(python3 -c "
import json; print(json.dumps({
    'agencia': '3073', 'conta_corrente': '12345678', 'convenio': '1234567',
    'carteira': '18', 'nosso_numero': '123', 'cedente': 'Empresa LTDA',
    'documento_cedente': '11222333000181', 'sacado': 'Joao da Silva',
    'sacado_documento': '52998224725', 'valor': 1500.0,
    'data_vencimento': '2027-12-30'
}))"
)" | python3 -c "
import sys, json, base64
data = json.load(sys.stdin)
print(f'Nosso Numero: {data[\"nosso_numero\"]}')
print(f'Formatado:    {data[\"nosso_numero_formatado\"]}')
print(f'Cod. Barras:  {data[\"codigo_barras\"]}')
with open('boleto.pdf', 'wb') as f:
    f.write(base64.b64decode(data['content_base64']))
print('PDF salvo: boleto.pdf')
"

Use GET /api/bancos para capacidades completas em tempo real, incluindo carteiras aceitas e formatos PIX.

import requests, json, base64

API = "http://localhost:8000"

# 1. Gerar boleto com dados + PDF
response = requests.get(f"{API}/api/boleto", params={
    "bank": "sicoob", "type": "pdf", "include_data": "true",
    "data": json.dumps({
        "agencia": "4327", "conta_corrente": "417270",
        "convenio": "229385", "carteira": "1",
        "nosso_numero": "7890", "cedente": "Empresa LTDA",
        "documento_cedente": "11222333000181",
        "sacado": "Joao da Silva", "sacado_documento": "52998224725",
        "valor": 2500.00, "data_vencimento": "2027-12-30"
    })
})
data = response.json()
with open("boleto.pdf", "wb") as f:
    f.write(base64.b64decode(data["content_base64"]))

# 2. Parsear extrato OFX
with open("extrato.ofx", "rb") as f:
    ofx = requests.post(f"{API}/api/ofx/parse", files={"file": f}).json()
for tx in ofx["transacoes"]:
    if tx["nosso_numero"]:
        print(f"{tx['data']} R$ {tx['valor']} nn={tx['nosso_numero']}")

# 1. Cria o job -> 202 com job_id (processa em background)
curl -X POST http://localhost:8000/jobs/boletos \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: lote-2026-07-25' \
  -d '{"tenant_id":"empresa1","boletos":[{"bank":"banco_brasil","external_id":"F-001", ...}]}'

# 2. Acompanha o estado (completed | partially_completed | failed)
curl "http://localhost:8000/jobs/boletos/$JOB_ID?tenant_id=empresa1"

# 3. Baixa o consolidado (.zip com PDFs + manifesto + erros)
curl "http://localhost:8000/jobs/boletos/$JOB_ID/artifacts?tenant_id=empresa1"

Remessa CNAB em lote (POST /jobs/cnab/remessas) separa automaticamente em sublotes compatíveis — 1 arquivo por banco/layout/convênio/carteira/conta.

# Carnê em lote: N parcelas, 3 vias por folha A4 (cada item com seu "bank")
curl -X POST "http://localhost:8000/api/boleto/multi?type=pdf&template=carne" \
  -F 'data=@parcelas.json;type=application/json' -o carne-lote.pdf

# Ou pelo caminho canônico (registra as parcelas e monta o carnê)
curl -X POST http://localhost:8000/carne -H 'Content-Type: application/json' -d @carne.json

🐍 Imagem única 100% Python (Dockerfile): FastAPI + engine pyCobrança in-process. Sem Ruby, sem GhostScript, sem sidecar — um processo só.

Opção	Comando
Docker	docker build -t cobranca-api . && docker run -p 8000:8000 cobranca-api
Docker Compose	docker compose up --build
Render.com

Detalhes e variáveis de ambiente em DEPLOY.md.

Contribuições são bem-vindas! Veja o guia de contribuição.

# Setup
git clone https://github.com/Maxwbh/cobranca-api.git && cd cobranca-api
pip install -r gateway/requirements.txt -r gateway/requirements-dev.txt

# Testes
cd gateway && PYTHONPATH=. pytest -v

# Servidor local
uvicorn app.main:app --reload --port 8000

MIT — use livremente em projetos comerciais e open-source.

Projeto independente e 100% Python: gateway multi-banco, Pix, jobs em lote e engine offline PyCobrança próprios. Créditos históricos completos no arquivo LICENSE.

Desenvolvido por Maxwell da Silva Oliveira
@maxwbh · M&S do Brasil LTDA

⭐ Se este projeto foi útil, considere dar uma estrela!