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

The post Sistema completo de cobranças via WhatsApp: boleto, Pix e NF-e na prática appeared first on Leonardo Nascimento | Engenheiro de Software.

O que diferencia um dev mais experiente não é o que ele sabe fazer, mas o que ele evita fazer.

Vou te ensinar aqui um padrão prático, usado em projetos reais, que resolve três problemas clássicos:

• Controllers inchados
• Regras de negócio espalhadas
• Código impossível de testar ou evoluir

public function store(Request $request)
{
if (!$request->email) {
return response()->json([‘error’ => ‘Email obrigatório’], 422);
}

$user = User::create([
    'name' => $request->name,
    'email' => $request->email,
]);

Mail::to($user->email)->send(new WelcomeMail($user));

Log::info('Usuário criado', ['id' => $user->id]);

return response()->json($user);

}

Funciona? Funciona.

É bom? Não.

Por quê?

• Controller decide regra de negócio
• Controller cria usuário
• Controller dispara e-mail
• Controller registra log

Isso acopla tudo.

Pensamento pleno/sênior: separar responsabilidade

Controller não decide regra.
Controller orquestra.

Vamos refatorar com um Service + DTO, padrão simples e poderoso.

Criando um DTO (Data Transfer Object)

Isso evita Request sendo usado como regra de negócio.

final class CreateUserDTO
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {}
}

Simples, explícito e tipado.

Criando o Service (onde a regra mora)

final class CreateUserService
{
    public function execute(CreateUserDTO $dto): User
    {
        if (!filter_var($dto->email, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException('Email inválido');
        }

        $user = User::create([
            'name' => $dto->name,
            'email' => $dto->email,
        ]);

        Mail::to($user->email)->send(new WelcomeMail($user));

        Log::info('Usuário criado', ['id' => $user->id]);

        return $user;
    }
}

Agora sim:

• Regra centralizada
• Código reutilizável
• Fácil de testar
• Fácil de evoluir

Controller limpo (como deveria ser)

public function store(Request $request, CreateUserService $service)
{
    $dto = new CreateUserDTO(
        name: $request->name,
        email: $request->email
    );

    $user = $service->execute($dto);

    return response()->json($user);
}

O controller:

• Recebe request
• Constrói DTO
• Chama serviço
• Retorna resposta

Nada além disso.

O ganho real (que júnior não enxerga)

Testabilidade

Agora você testa a regra sem framework:

public function test_user_creation()
{
    $service = new CreateUserService();

    $dto = new CreateUserDTO(
        name: 'Leo',
        email: 'leo@email.com'
    );

    $user = $service->execute($dto);

    $this->assertEquals('Leo', $user->name);
}

Sem Request.
Sem Controller.
Sem gambiarra.

Evolução sem dor

Amanhã você precisa:

• Enviar evento para fila
• Criar usuário em sistema externo
• Validar regra nova

Você altera um lugar só.

Mentalidade sênior (isso vale ouro)

” Código que funciona não é código bom.mCódigo bom é o que aguenta mudança.”

Pleno/sênior pensa assim:

• Onde essa regra deve morar?
• O que vai mudar daqui 6 meses?
• Quem vai dar manutenção nisso?

Erros clássicos que isso evita

• Fat models
• Controllers gigantes
• Services que viram controllers
• Regra duplicada
• Código impossível de refatorar

Esse tipo de abordagem não aparece em tutorial de YouTube, mas é exatamente o que mantém sistemas vivos em produção.

The post PHP além do CRUD: como escrever código que não vira problema em produção appeared first on Leonardo Nascimento | Engenheiro de Software.

Porém, todavia, entretanto, contudo, se você não tem um grande conhecimento em gerenciamento de hospedagens, ou simplesmente não quer se incomodar em prestar suporte para o seu cliente, poderá muito bem optar por um Cloud 100% configurado com:

• Servidor Cloud individual (Apenas o seu site hospedado no Cloud)
• E-mails ilimitados
• SSL grátis
• Firewall
• Tráfego ilimitado
• Banco de dados ilimitados
• Backup grátis
• Acesso SSH
• Software anti-spam para e-mails
• Upgrade/Downgrade de plano direto pelo painel, sem precisar abrir ticket e sem downtime
• Suporte grátis
• Instalações de aplicações com poucos cliques
• Revenda de hospedagem
• Plugin de cache (WordPress)
• Editor de arquivos
• FTP
• Deploy pelo GitLab em breve Github e Bitbucket
• Restauração de backup em poucos cliques
• Gerenciador de banco de dados (PHPMYADMIN)
• Acesso remoto ao banco de dados
• Escolher entre Mysql e PostgreSQL
• Balanceador de carga
• Escolher versões do PHP (5.4 até >= 8.0)
• CronJob direto pelo painel
• Logs de erro do PHP e do servidor
• Migração dos seus dados gratuitamente (Consulte)
• Hospedagem individualizada, sem compartilhamento de CPU e memória com outros sites
• Sem fidelidade (cancele quando quiser)
• A partir de R$ 10,90

Lembrando que o valor de R$ 10,90 é a configuração inicial, se você precisar de mais poder de processamento, poderá efetuar upgrade da sua instância, com valores adicionais.

Sem surpresas na conta

Você está no controle da sua hospedagem, no painel de controle, é possível verificar uma estimativa de quantos créditos você ainda possuí e quanto tempo ele irá durar.

Você pode optar por deixar a recarga automática através de cartão de crédito, também é possível inserir créditos através de boleto bancário, Pix ou mercado pago.

Você no controle

Com a hostoo você está no controle e não precisa ser expert em servidores, é possível efetuar upgrade e downgrade de servidor com poucos cliques e sem deixar o seu site offline. Instale e configure aplicações em poucos cliques. Gosta do WordPress? Plugin de cache gratuito para acelerar ainda mais o carregamento do seu site.

No print abaixo, podemos notar o domínio do site, versão do PHP, SSL ativo, detalhes do plano, detalhes de consumo de CPU, RAM, disco e outras configurações da hospedagem.

Precisa de mais?

Além de ter servidores nos Estados Unidos, também é possível hospedar seus sites em clouds aqui no Brasil, claro, por um valor adicional. Com a Hostoo você pode fazer upgrade de plano facilmente. Suponhamos que durante o dia, você teve visitas atípicas em seu website, resultando em um consumo máximo de CPU e RAM, e agora o que fazer? Em poucos cliques, você pode efetuar upgrade do seu plano, contratando um cloud melhor, pagando por hora utilizada, e posteriormente, retornar ao plano original, você está 100% no controle.

Suporte que não te deixa 48h esperando

Estou com a Hostoo há mais de 1 ano e diferente de outros serviços de hospedagem, o suporte é muito rápido e definitivamente resolve seus problemas. Até o momento, precisei abrir apenas 1 ticket de site fora do ar, onde ficou constatado que o problema não era na hospedagem e sim no servidor dns que eu estava utilizando como proxy, o outro ticket? Foi aberto pela própria empresa, quando me deparei com um erro 500 no painel de hospedagem. Tempo da primeira resposta < 22 minutos.

Sem dúvidas, foi um grande achado que estou compartilhando com você! https://hostoo.io

The post Hospede seu site em um servidor Cloud por menos de R$ 11 Mês appeared first on Leonardo Nascimento | Engenheiro de Software.