Uma API REST para boleto bancário, Pix, CNAB 240/400 e OFX

Integre 19 bancos brasileiros com um único endpoint REST. Emissão de boletos via API, cobrança registrada, Bolepix, Pix Automático, remessa e retorno CNAB 240/400 e conciliação por OFX — consumido por HTTP de qualquer linguagem: Java, PHP, C#, Node, Go, Delphi, Oracle APEX, PL/SQL ou Python.

Última versão publicada Status do build Licença MIT Stars no GitHub

19bancos

1endpoint REST

100%Python · 1 container

MITopen source

Dois mundos, um contrato. Online: boleto registrado, Pix, Pix Automático e link de pagamento com cartão nas APIs dos bancos (OAuth2 + mTLS). Offline: boleto em PDF, CNAB e carnê pela engine embutida — sem rede, sem convênio, sem sidecar. É o mesmo POST /cobranca: trocar de mundo é trocar um campo.

Terminal: POST /cobranca com um payload de boleto devolve id, status registrado, linha digitável, código de barras e o PDF em base64 — pelo caminho offline, sem credencial de banco. Resposta real, capturada da API — caminho offline, sem credencial e sem convênio. O mesmo POST /cobranca com provider=c6 registra no banco.

Por que não integrar banco a banco?

Cada banco tem sua API, seu OAuth, seu mTLS, seu layout de CNAB e seu dialeto de erro. A Cobranca-API existe para você integrar uma vez:

	Cobranca-API	Integração direta, banco a banco
Contrato	1 endpoint REST (`POST /cobranca`)	19 APIs diferentes
Autenticação	Credencial vira token `bapi_`; OAuth+mTLS são problema nosso	OAuth, mTLS e renovação implementados N vezes
Trocar de banco	Trocar o campo `provider` no payload	Reescrever a integração
CNAB 240/400	Unificado pela engine — remessa e retorno	Layout específico por banco e convênio
Erros	Normalizados (`422` payload, `424` credencial, `409` conflito…)	Um dialeto de erro por banco
Sem convênio ainda?	Começa offline hoje, liga o banco depois	Não começa

Emitir um boleto via API

Uma chamada devolve o PDF pronto:

curl -G https://cobranca-api-sq67.onrender.com/api/boleto \
  --data-urlencode 'bank=banco_brasil' \
  --data-urlencode 'type=pdf' \
  --data-urlencode 'data={"valor":1500.00,"cedente":"Empresa LTDA","documento_cedente":"11222333000181","sacado":"Joao da Silva","sacado_documento":"52998224725","agencia":"3073","conta_corrente":"12345678","convenio":"1234567","carteira":"18","nosso_numero":"123","data_vencimento":"2027-12-31"}' \
  -o boleto.pdf

Trocar type=pdf por /validate, /data ou /nosso_numero devolve validação e campos calculados sem gerar o PDF.

A instância pública roda no plano gratuito do Render e hiberna após 15 minutos de inatividade — a primeira chamada pode levar até um minuto. É ambiente de demonstração, não de produção, e a URL não é fixa: o Render a deriva do nome do serviço. Na sua instalação, troque pelo hostname do seu.

Bancos suportados

🌐 Integração online — na API do banco

C6 Bank · 336 Sicoob · 756 Banco Inter · 077

Boleto registrado e Bolepix
Pix e Pix Automático (padrão BACEN)
Link de pagamento com cartão (C6)
Webhook, extrato e conciliação

📦 Motor offline — engine embutida

Banco do BrasilBradescoItaúSantanderCaixaSicoobSicrediBanrisulC6SafraBanestesUnicredAilos+ 5

Boleto em PDF e carnê 3 vias
Remessa e retorno CNAB 240/400
Parsing de OFX para conciliação
Sem rede, sem convênio, sem sidecar

As duas listas não se sobrepõem por acaso, e o Inter mostra por quê: ele fala online e não tem layout offline, então provider=inter sem credencial responde 424 em vez de cair na engine — cair emitiria um boleto registrado no banco errado.

A cobertura varia por recurso — em vez de repetir a lista aqui, consulte a fonte: GET /api/bancos responde a matriz offline e GET /bancos a online, ambas por introspecção do código (não há como envelhecer).

Casos de uso

🏭 ERP e financeiro

Emissão de boletos e remessas CNAB para sistemas de gestão — TOTVS, Senior, Sankhya, SAP, Oracle EBS — via POST /cobranca e POST /api/remessa, com lote assíncrono para o fechamento.

🔁 SaaS e assinaturas

Cobrança recorrente com boleto, carnê, Pix Automático e link de pagamento com cartão — e webhook assinado avisando a liquidação.

🅾️ Oracle APEX e PL/SQL

Integração bancária direto do banco de dados, via APEX_WEB_SERVICE/UTL_HTTP — com pacote PL/SQL e páginas APEX prontos.

🧳 Legado e migração

Delphi, C#, Java antigo: substitui N integrações específicas por uma API unificada — HTTP puro, PDF em binário ou base64, sem instalar nada no cliente.

Referência

Guia	Para quê
Gateway Python	Credenciais, cobrança online, Pix, conciliação e webhooks
Validação de campos	Regras por banco — tamanhos, carteiras, nosso número, CNPJ alfanumérico
Encargos na remessa	Multa, juros, desconto, IOF, abatimento e protesto no CNAB
Pix em boletos	Bolepix — BR Code EMV e QR no boleto e na remessa
Leitura de OFX	Extrato v1/v2 e conciliação com os boletos emitidos
Troubleshooting	Erros comuns e o que significam
Arquitetura	Como as peças se encaixam
Guia de deploy	Imagem no GHCR, Render, variáveis de ambiente e troubleshooting
Notas de engenharia	Roadmap de providers e o guia de integração de cada banco
Swagger — gateway REST	Todos os endpoints do gateway, publicados aqui
*Swagger — offline (`/api/`)**	Boleto, CNAB e OFX sem convênio

O Swagger publicado é gerado do código a cada versão e o CI reprova se ele ficar para trás — não é uma cópia que envelhece. Ele mora no site porque a instância de demonstração hiberna: documentação que some quando o servidor dorme não serve para quem está decidindo integrar.

Para executar as chamadas (o Try it out), use a demo ao vivo ou suba a sua com um docker run — aí o Swagger é servido pela própria API.

Como rodar

Imagem pronta, publicada a cada release no GitHub Container Registry — sem clonar e sem buildar:

docker run -p 8000:8000 -e LOG_LEVEL=info ghcr.io/maxwbh/cobranca-api:latest

Em produção, fixe a versão (ghcr.io/maxwbh/cobranca-api:2.2.0) em vez de latest. Para mexer no código, o caminho é o clone:

git clone https://github.com/Maxwbh/cobranca-api.git
cd cobranca-api
docker build -t cobranca-api .
docker run -p 8000:8000 -e LOG_LEVEL=info cobranca-api

Um Dockerfile, um processo, sem sidecar. O guia de deploy cobre o Render.com e as variáveis de ambiente — inclusive os tetos de lote (LOTE_MAX_ITENS, JOB_MAX_ITENS) e o que muda ao subir de plano.

Teste a API agora

Suba o container e emita o primeiro boleto em menos de 5 minutos — sem convênio, sem credencial, sem cadastro.

Ver o Swagger Testar na demo Ver no GitHub

Projeto sob licença MIT. A engine de cálculo e renderização é a pyCobrança, também open source.

Quem faz

Desenvolvido por Maxwell da Silva Oliveira (GitHub · maxwbh@gmail.com), da M&S do Brasil LTDA — consultoria e desenvolvimento em integração bancária, Oracle APEX e Python.

Precisa de ajuda para integrar a Cobranca-API ao seu ERP, Oracle APEX ou sistema legado? Fale com a gente.