Sistema completo de cobranças via WhatsApp: boleto, Pix e NF-e na prática

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:

1. Você cadastra um cliente
2. Cadastra um serviço
3. Vincula o serviço ao cliente
4. 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?

1. O Inter chama o webhook
2. O sistema valida a assinatura
3. Atualiza o status da cobrança
4. Invalida caches relacionados
5. Registra logs
6. (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:

• Dockerfile
• docker-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