Automatizar cobranças nunca foi simples. Entre regras bancárias, vencimentos, Pix, boletos registrados, notificações, inadimplência e conciliação, a maioria dos sistemas acaba virando um emaranhado de scripts difíceis de manter.
Neste artigo, vou mostrar como funciona, na prática, um sistema real de cobrança construído em Laravel, integrando Boleto e Pix do Banco Inter, com webhooks, PDFs, crons, Docker, e-mails, WhatsApp, SMS e até ligações automáticas.
Todo o conteúdo é baseado em um projeto open source real, usado em produção, disponível no GitHub:
👉 Repositório:
https://github.com/leonardop21/boleto-inter-free
Importante: este não é um “tutorial de Hello World”. É um guia técnico completo, voltado para quem quer entender arquitetura, evitar erros comuns e colocar cobrança automática em produção com segurança.
Por que integrar diretamente com o Banco Inter?
O Banco Inter oferece uma API robusta para PJ, com suporte nativo a:
- Boletos registrados
- Pix com QR Code dinâmico
- Webhooks de status
- Consulta de cobranças
- Download de PDFs
- Extratos bancários
Ao integrar diretamente com o Inter, você elimina intermediários, reduz custos e ganha controle total sobre o fluxo financeiro.
Mas isso vem com desafios:
- Certificados mTLS
- OAuth2
- Regras rígidas de vencimento
- Webhooks que precisam ser idempotentes
- PDFs que precisam ser armazenados ou regenerados
- Conciliação automática
É exatamente isso que o projeto resolve.
Visão geral da arquitetura do sistema
Antes de entrar em código, é importante entender como o sistema foi pensado.
Componentes principais
- Laravel 8 como base
- MySQL para dados transacionais
- Redis para cache com tags
- Banco Inter API para cobranças
- Notifish para WhatsApp
- SMTP para e-mails
- SMS Dev para SMS
- King SMS (Voicer) para ligações
- Docker + Nginx + PHP-FPM em produção
Nada aqui é experimental. Tudo foi pensado para rodar 24/7, com falhas previsíveis e logs rastreáveis.
Por que Redis é obrigatório neste projeto?
Um erro comum em sistemas de cobrança é consultar a API do banco o tempo todo.
Esse projeto evita isso usando cache agressivo com tags, por exemplo:
- Cache de cobranças
- Cache de clientes
- Cache de serviços
- Cache de status de boletos e Pix
Quando um boleto muda de status (via webhook), o cache relacionado é invalidado.
👉 Sem Redis (ou Memcached), o sistema não funciona corretamente.
Instalação do projeto (ambiente local)
1. Clonando o repositório
git clone https://github.com/leonardop21/boleto-inter-free.git
cd boleto-inter-free
composer install
2. Configuração inicial
cp .env.example .env
php artisan key:generate
Configurando o banco de dados e cache
No .env:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=boleto_inter
DB_USERNAME=user
DB_PASSWORD=pass
CACHE_DRIVER=redis
SESSION_DRIVER=redis
TIME_CACHE_IN_SECONDS=604800
Depois:
php artisan migrate
Como funciona o modelo de cobrança
O sistema foi pensado para cobrança recorrente, mas funciona também para cobranças pontuais.
Entidades principais
- Cliente
- Serviço
- Cliente x Serviço
- Boleto
- Pix
- NF-e (opcional)
O fluxo é simples:
- Você cadastra um cliente
- Cadastra um serviço
- Vincula o serviço ao cliente
- O sistema gera boletos ou Pix automaticamente
Integração com o Banco Inter (parte crítica)
Certificados mTLS
O Inter exige:
- Um arquivo
.crt - Um arquivo
.key
No .env:
INTER_PATH_CRT=/caminho/inter.crt
INTER_PATH_KEY=/caminho/inter.key
OAuth2
INTER_CLIENT_ID=seu_client_id
INTER_CLIENT_SECRET=seu_client_secret
INTER_CLIENT_SCOPE="extrato.read boleto-cobranca.read boleto-cobranca.write"
INTER_BASE_URL="https://cdpj.partners.bancointer.com.br/"
Sem isso, nenhuma requisição funciona.
Webhooks: o coração da automação
O sistema registra dois webhooks no Inter:
- Boleto
- Pix
INTER_WEBHOOK_URL=https://seusite.com/api/inter/webhook/boleto
INTER_WEBHOOK_URL_PIX=https://seusite.com/api/inter/webhook/pix
O que acontece quando um pagamento é feito?
- O Inter chama o webhook
- O sistema valida a assinatura
- Atualiza o status da cobrança
- Invalida caches relacionados
- Registra logs
- (Opcional) dispara notificações internas
Isso evita:
- Jobs de polling
- Consultas desnecessárias
- Status desatualizado
Geração automática de boletos
Este é um dos pontos mais sofisticados do projeto.
Comando:
php artisan ln:auto_generate_boleto
Regras implementadas
- Se o dia de vencimento já passou → gera para o mês seguinte
- Se o cliente escolheu dia 31 → ajusta para último dia do mês
- Respeita meses com 28, 29, 30 ou 31 dias
- Evita boletos duplicados
- Gera PDF automaticamente
- Salva logs detalhados
Tudo isso roda sem intervenção humana.
Geração automática de Pix
Comando:
php artisan ln:auto_generate_pix
- Gera QR Code
- Gera payload Pix
- Cria cobrança no Inter
- Registra vencimento
- Gera imagem do QR Code (GD)
Envio de cobranças por e-mail
O sistema envia:
- Boleto em PDF
- Pix com QR Code
- NF-e (se configurado)
Configuração SMTP no .env:
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
Além disso, o layout do e-mail é personalizável:
- Logo
- Cor de fundo
- Links de suporte
Envio por WhatsApp (Notifish)
Integração direta com a API do Notifish.
NOTIFISH_BASE_URL=https://seu.notifish.com/api/v2/
NOTIFISH_API_KEY=sua_key
NOTIFISH_UUID=sua_instancia
O sistema gera uma URL assinada temporária para o PDF do boleto, válida por poucos minutos — sem expor IDs internos.
SMS e ligações automáticas para inadimplentes
SMS
php artisan ln:send-boleto-sms
php artisan ln:send-pix-sms
Ligação (voz robótica)
php artisan ln:send-boleto-voicer
php artisan ln:send-pix-voicer
Isso é usado somente após o vencimento, como camada extra de cobrança.
Crons: como tudo roda sozinho
Você não agenda cada comando individualmente.
Apenas:
* * * * * php artisan schedule:run
O Laravel Scheduler cuida do resto.
Exemplo:
- Dia 1 → gera boletos
- Antes do vencimento → envia lembrete
- Após vencimento → cobrança progressiva
Docker em produção
O projeto já vem com:
Dockerfiledocker-compose.prod.yml- Nginx configurado
- PHP-FPM otimizado
- Redis
- MySQL
Subir produção:
docker compose -f docker-compose.prod.yml up -d --build
Logs, rastreabilidade e auditoria
Cada processo tem seu próprio log:
- Boletos
- Pix
- NF-e
- Webhooks
- Erros de API
Isso é fundamental para:
- Suporte
- Auditoria
- Contabilidade
- Diagnóstico rápido
Para quem este projeto é indicado?
- Desenvolvedores PHP/Laravel
- SaaS com cobrança recorrente
- Sistemas internos de empresas
- Agências que querem padronizar cobrança
- Projetos que precisam de autonomia financeira
Conclusão
Automatizar cobranças não é só “gerar boleto”.
É lidar com:
- Datas
- Erros bancários
- Comunicação
- Inadimplência
- Escala
- Observabilidade
Este projeto resolve isso de forma pragmática, realista e testada em produção.
👉 Repositório completo:
https://github.com/leonardop21/boleto-inter-free
