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.

Este artigo detalha a arquitetura de uma API REST desenvolvida em Laravel para gerenciamento de tarefas, criada como parte de um teste técnico, mas estruturada como um projeto pronto para produção, seguindo boas práticas amplamente utilizadas em ambientes corporativos.

Visão geral da solução

A aplicação consiste em uma API RESTful para gerenciamento de tarefas, com suporte a:

• Autenticação via Bearer Token (Laravel Sanctum)
• CRUD completo de tarefas
• Marcação de tarefas como concluídas
• Cache de consultas com Redis
• Banco de dados PostgreSQL
• Documentação interativa via Swagger
• Ambiente Dockerizado (dev, test e prod)
• Testes automatizados
• Pipeline de CI/CD com GitHub Actions

O foco não foi apenas “fazer funcionar”, mas pensar a aplicação como um produto escalável e previsível.

Decisão arquitetural: API stateless e autenticação

A API foi construída como stateless, utilizando Bearer Token via Laravel Sanctum.

Benefícios dessa abordagem:

• Facilidade de integração com frontends (SPA, mobile, terceiros)
• Independência de sessão
• Escalabilidade horizontal
• Compatibilidade com gateways, load balancers e proxies

A autenticação é desacoplada do fluxo de negócio, o que facilita manutenção e evolução futura.

PostgreSQL como banco principal

A escolha do PostgreSQL não foi aleatória. Ele é amplamente utilizado em ambientes corporativos por oferecer:

• Confiabilidade transacional
• Suporte avançado a índices
• Tipos de dados ricos
• Excelente desempenho em cenários complexos

Isso torna a aplicação preparada para crescer sem precisar trocar a base de dados no curto ou médio prazo.

Redis como camada de cache

Para reduzir carga no banco e melhorar tempo de resposta, foi implementado cache com Redis, com TTL de 120 segundos nas consultas mais comuns.

Benefícios diretos:

• Redução de queries repetitivas
• Menor latência
• Melhor desempenho sob carga
• Escalabilidade em leitura

Essa abordagem demonstra preocupação com performance real, não apenas com lógica funcional.

Arquitetura limpa: Repository Pattern + Service Layer

A aplicação segue princípios de Clean Architecture, separando responsabilidades de forma clara:

• Controllers: recebem requisições e retornam respostas
• Services: concentram regras de negócio
• Repositories: isolam o acesso a dados
• Models: representam as entidades

Vantagens dessa separação:

• Código mais legível
• Facilidade de testes
• Menor acoplamento
• Evolução segura do domínio

Essa estrutura é comum em times maduros e projetos de longo prazo.

Docker como base do ambiente

Toda a aplicação roda em Docker, com ambientes bem definidos:

Desenvolvimento

• Código em volume
• Hot reload
• PostgreSQL + Redis + Nginx
• Testes executados automaticamente

Produção

• Build otimizado
• Código embutido na imagem
• Assets compilados no build
• Sem dependência de volume

Essa separação reduz o clássico problema de “funciona na minha máquina” e aproxima o ambiente local da produção.

Testes automatizados como parte do fluxo

A aplicação conta com testes unitários e de feature, executados de três formas:

• Localmente no ambiente dev
• Isoladamente via Docker
• Automaticamente no CI/CD

Isso garante:

• Segurança para refatorações
• Detecção precoce de bugs
• Confiança na entrega contínua

Testes não são tratados como opcional, mas como parte da arquitetura.

CI/CD com GitHub Actions

Cada push ou pull request dispara um workflow que:

1. Sobe toda a stack Docker (app, banco, cache)
2. Executa migrations
3. Roda a suíte completa de testes
4. Bloqueia o merge em caso de falha

Esse processo simula um pipeline real de empresas que operam com entrega contínua e qualidade de código como requisito.

Documentação com Swagger

A API possui documentação interativa via Swagger, acessível após subir a aplicação.

Isso permite:

• Testes manuais rápidos
• Onboarding mais fácil
• Comunicação clara entre backend e frontend
• Uso por terceiros sem dependência de documentação externa

Documentação é tratada como parte do produto, não como etapa posterior.

Benefícios dessa arquitetura em um contexto profissional

Essa abordagem entrega vantagens claras em ambientes reais:

• Código organizado e previsível
• Facilidade de manutenção
• Escalabilidade técnica
• Padronização de ambientes
• Menor risco em deploys
• Base sólida para crescimento

Não se trata apenas de uma API de tarefas, mas de um modelo replicável para aplicações reais.

O que esse projeto demonstra tecnicamente

Esse projeto evidencia competências como:

• Domínio de Laravel além do básico
• Conhecimento de arquitetura backend
• Uso consciente de cache e banco
• Experiência com Docker e ambientes reais
• Cultura de testes
• Automação de CI/CD
• Pensamento orientado a produto e escala

São exatamente esses pontos que diferenciam um desenvolvedor pleno/sênior em processos seletivos.

Conclusão

Mais do que cumprir um teste técnico, o objetivo deste projeto foi demonstrar capacidade de pensar sistemas como um todo, indo além do CRUD simples.

Arquitetura, automação, testes e previsibilidade são o que tornam uma aplicação sustentável — e é isso que empresas buscam quando contratam profissionais para projetos de longo prazo.

Link do teste prático

The post Arquitetura de uma API REST em Laravel preparada para produção appeared first on Leonardo Nascimento | Engenheiro de Software.

A maioria desses problemas não vem do Redis em si, mas da forma como ele é integrado à aplicação. A seguir estão erros que aparecem com frequência em produção e o que aprender com eles.

Um dos erros mais comuns é tratar Redis como banco de dados principal. Redis é rápido, mas não é fonte de verdade. Dados em memória podem ser perdidos por restart, eviction ou falha de infraestrutura. Quando o sistema depende do Redis para manter estado crítico, qualquer limpeza vira incidente. Em aplicações maduras, Redis é sempre camada auxiliar; o banco relacional continua sendo a referência.

Outro problema recorrente é cachear dados sem estratégia clara de invalidação. No começo, tudo parece funcionar: menos queries, respostas mais rápidas. Com o tempo, começam a aparecer dados desatualizados, comportamentos inconsistentes e bugs que “somem sozinhos”. Cache sem invalidação bem definida vira dívida técnica. Toda entrada em cache precisa ter resposta clara para três perguntas: quando expira, quem invalida e o que acontece se falhar.

Também é comum usar TTL genérico para tudo. Definir o mesmo tempo de expiração para dados completamente diferentes ignora o contexto. Dados quase estáticos podem ficar horas em cache; dados sensíveis a mudanças podem precisar de expiração curta ou invalidação ativa. TTL não é detalhe de configuração, é parte da regra de negócio.

Em projetos com filas e jobs, aparece bastante o erro de usar Redis sem pensar em concorrência. Dois workers acessando e alterando a mesma chave ao mesmo tempo geram condição de corrida. Incrementos, flags e estados intermediários precisam ser atômicos ou protegidos por lock. Ignorar isso funciona em teste, mas quebra sob carga.

Outro ponto crítico é usar Redis como solução para idempotência sem persistência complementar. Locks e flags em Redis ajudam, mas não garantem segurança total. Se o Redis reiniciar, o controle some. Para efeitos colaterais críticos (pagamento, notificação, integração externa), o controle final precisa estar no banco, com constraint ou registro explícito de processamento.

Muitos projetos também caem no erro de não separar namespaces ou prefixos de chave. Em aplicações maiores, isso gera colisão, dificuldade de debug e limpeza perigosa. Padronizar prefixos por domínio ou tipo de dado facilita manutenção e evita apagar cache errado.

Há ainda o uso excessivo de Redis para resolver problemas que não são de cache. Guardar lógica de negócio, estados complexos ou fluxos longos em memória costuma deixar o sistema frágil. Redis é ótimo para acelerar acesso, coordenar concorrência e compartilhar estado temporário, mas não substitui modelagem correta.

Outro erro que só aparece em produção é ignorar política de eviction e limites de memória. Quando a memória acaba, o Redis começa a remover chaves de acordo com a política configurada. Se isso não foi considerado no design, o sistema passa a perder cache crítico aleatoriamente, causando degradação inesperada. Monitorar uso de memória e entender eviction é obrigatório.

Também é comum não monitorar Redis como dependência crítica. Quando ele fica lento ou indisponível, a aplicação sofre. Sem métricas, alertas e logs específicos, o diagnóstico demora. Redis precisa estar no radar de observabilidade tanto quanto banco e API externa.

Por fim, um erro sutil: acoplar demais o código ao Redis. Quando a aplicação assume que Redis sempre está disponível, qualquer fallback vira difícil. Código mais saudável trata Redis como otimização opcional: se falhar, o sistema continua funcionando, mesmo que mais lento.

Redis é uma ferramenta poderosa, mas exige disciplina. Em aplicações Laravel, ele deve acelerar, proteger e coordenar — nunca sustentar a lógica principal do sistema. Quando tratado como camada auxiliar, com invalidação clara, controle de concorrência e observabilidade, ele entrega o que promete. Quando usado como atalho, cobra o preço em produção.

The post Erros comuns ao usar Redis em aplicações Laravel appeared first on Leonardo Nascimento | Engenheiro de Software.

Jobs e processamento assíncrono são excelentes quando usados com critério. Quando usados por impulso, viram fonte de incidentes.

O que fila realmente te dá (e o que ela não dá)

Fila te dá principalmente três coisas: desacoplamento do tempo de resposta, capacidade de absorver picos e reprocessamento controlado. Ela não te dá garantia de que algo vai rodar uma vez só, nem te livra de tratar falhas externas. Na verdade, ela te obriga a tratar isso.

Se você joga um processo para a fila sem pensar em idempotência, retries e observabilidade, você só mudou o problema de lugar.

Quando usar jobs e filas

1) Tudo que não precisa bloquear o usuário

Se o usuário não precisa do resultado imediato, isso já é um sinal forte de fila.

Exemplos comuns:

• envio de e-mail e notificações
• geração de relatórios
• criação de thumbnails / processamento de mídia
• sincronização com sistemas externos
• webhooks de saída (enviar eventos para terceiros)

A regra prática: se o usuário já pode seguir o fluxo sem esperar, tire do request.

2) Integrações externas e chamadas instáveis

API de terceiros falha, oscila, responde lento. Fila é ótima para isso porque permite retries e isolamento.

Exemplos:

• gateway de pagamento
• WhatsApp / SMS
• ERP e sistemas legados
• qualquer HTTP externo

Mas aqui entra o ponto crítico: fila não é desculpa para “tentar infinitamente”. Você precisa controlar tentativas e saber quando desistir.

3) Processamentos pesados e previsíveis

Tudo que consome CPU, memória ou I/O e pode gerar timeout em request tende a ser melhor em job.

Exemplos:

• exportar CSV grande
• processar lote de dados
• recalcular agregações
• rodar rotinas de normalização/validação em massa

4) Fan-out (um evento dispara várias ações)

Quando algo acontece e você precisa executar várias tarefas em sequência ou em paralelo, jobs ajudam a manter o sistema organizado.

Exemplo: “pedido pago” dispara:

• enviar confirmação
• baixar estoque
• emitir nota
• notificar financeiro
• gerar registro no CRM

Se você faz tudo no request, vira um fluxo pesado e frágil. Com jobs, você separa responsabilidades.

5) Absorver picos sem derrubar o sistema

Fila é uma forma de “buffer”. Em vez de o sistema tentar processar tudo na hora e morrer, você coloca em fila e processa no ritmo que aguenta.

Isso é útil quando:

• picos são comuns
• demanda varia muito
• você precisa garantir estabilidade

Quando evitar jobs e filas

1) Quando você precisa de resposta imediata e consistente

Se o usuário precisa saber na hora se deu certo, jogar em fila pode piorar a experiência.

Exemplos:

• login
• criar pagamento e retornar confirmação
• reservar algo que não pode duplicar
• operações transacionais críticas

Você até pode usar job para efeitos colaterais, mas a decisão central precisa ser síncrona.

2) Quando a operação é simples e rápida

Às vezes a operação leva 20ms e você coloca na fila “por padrão”. Isso adiciona:

• complexidade
• delay
• necessidade de monitoramento
• risco de falha assíncrona

Fila não pode ser usada como padrão para tudo. Senão você cria um sistema cheio de jobs pequenos e difíceis de rastrear.

3) Quando você não tem observabilidade

Fila sem visibilidade vira caixa-preta.

Se você não tem:

• logs por job
• métricas de falha
• alertas de backlog
• dead-letter ou estratégia de falha

você vai descobrir problemas tarde demais. Nesse cenário, manter síncrono pode ser mais seguro até organizar a casa.

4) Quando você não consegue garantir idempotência

Jobs podem rodar duas vezes. Isso é normal: retry, timeouts, quedas de worker, reentregas. Se o job não é idempotente, você corre risco de:

• cobrança duplicada
• disparo duplicado
• registro duplicado
• integração duplicada

Se não dá para tornar idempotente, trate o caso com mais cuidado. Às vezes o certo é manter a operação central síncrona e colocar apenas efeitos colaterais na fila.

O ponto que derruba sistemas: duplicidade

Em produção, o seu job vai rodar duas vezes em algum momento. Não é “se”, é “quando”. Por isso, projetos maduros tratam idempotência como requisito.

Algumas abordagens comuns:

• chave idempotente por evento (event_id / request_id)
• lock distribuído (Redis)
• uniqueness controlada (Laravel unique jobs quando aplicável)
• constraints no banco (único onde fizer sentido)

Não é uma bala de prata, mas é obrigatório ter uma estratégia.

Filas também precisam de limites

Jobs não podem tentar para sempre. Você precisa definir:

• número de tentativas
• backoff entre tentativas
• timeout
• comportamento ao falhar (alerta, dead letter, reprocessamento manual)

E precisa aceitar que algumas coisas falham. O sistema não pode entrar em loop eterno tentando recuperar erro externo.

Sinais de que você deve ir para fila

Se você está em dúvida, aqui vão sinais bem práticos:

• requests começando a estourar timeout
• picos derrubando a API
• integrações externas travando fluxos principais
• usuários esperando por coisas que não precisam esperar
• o mesmo fluxo acumulando responsabilidades demais

Jobs e filas são uma das melhores ferramentas para dar escala e estabilidade em sistemas Laravel, mas elas exigem maturidade. Quando bem usadas, melhoram performance, isolam falhas e deixam o sistema mais previsível. Quando usadas sem critério, viram um sistema difícil de operar, cheio de jobs duplicados e incidentes intermitentes.

Fila não é atalho. É arquitetura.

The post Laravel: Jobs, filas e processamento assíncrono: quando usar e quando evitar appeared first on Leonardo Nascimento | Engenheiro de Software.