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.

Com a aprovação no diretório oficial, o plugin passa a atender padrões rígidos de segurança, qualidade de código e boas práticas exigidas pela equipe do WordPress, o que garante mais confiabilidade para quem busca soluções profissionais de distribuição de conteúdo.

👉 Repositório oficial do plugin:
https://wordpress.org/plugins/notifish/

O que é o plugin Notifish

O Notifish é um plugin que conecta o WordPress à plataforma Notifish, permitindo que publicações sejam enviadas automaticamente para grupos, listas ou contatos no WhatsApp a partir do momento em que um post é publicado ou atualizado.

Na prática, ele elimina processos manuais comuns em portais, blogs e sites de conteúdo, como copiar links, formatar mensagens e disparar envios individualmente, centralizando tudo dentro do próprio fluxo editorial.

Para quem o Notifish é indicado

O plugin foi desenvolvido para cenários reais de uso, como:

• Portais de notícias e sites jornalísticos
• Blogs com publicação frequente
• Produtores de conteúdo e infoprodutores
• Empresas que usam WhatsApp como canal de comunicação
• Projetos WordPress que dependem de distribuição rápida de conteúdo

Em todos esses casos, o WhatsApp deixa de ser apenas um canal complementar e passa a fazer parte da estratégia de publicação.

Como funciona a integração com o WordPress

Após a instalação do plugin e a configuração da chave de API, o funcionamento é simples:

1. O conteúdo é publicado normalmente no WordPress
2. O plugin identifica a publicação
3. O Notifish envia a mensagem para os grupos ou listas configuradas
4. O envio fica registrado para controle e auditoria

Todo o processo acontece de forma transparente para o editor, sem necessidade de ferramentas externas ou fluxos paralelos.

Principais vantagens do Notifish

Automação real no fluxo editorial

O envio das mensagens acontece no momento certo, integrado ao ciclo de publicação, sem depender de ações manuais.

Distribuição imediata do conteúdo

Assim que a matéria vai ao ar, ela já pode ser entregue ao público em um canal com alta taxa de abertura e leitura.

Centralização de operações

O WordPress deixa de ser apenas um CMS e passa a ser também um ponto central de distribuição de conteúdo.

Mais controle sobre comunicação via WhatsApp

O uso de automação reduz falhas humanas, duplicidade de envios e inconsistências na comunicação.

Aprovação no repositório oficial do WordPress

A presença do Notifish no repositório oficial do WordPress é um ponto relevante, pois indica que o plugin:

• Segue as diretrizes de segurança do WordPress
• Utiliza boas práticas de desenvolvimento
• Passou por revisão manual da equipe do WordPress
• Pode ser instalado e atualizado diretamente pelo painel administrativo

Isso reduz riscos técnicos e aumenta a confiabilidade do projeto para uso em produção.

Impacto em SEO e engajamento

Embora o WhatsApp não seja um fator direto de ranqueamento, a automação de distribuição impacta positivamente métricas importantes para SEO, como:

• Aumento de tráfego recorrente
• Maior taxa de retorno ao site
• Crescimento de engajamento com o conteúdo
• Ampliação do alcance orgânico das publicações

Em projetos editoriais, isso significa conteúdo sendo consumido mais rápido e com mais frequência.

Onde instalar o plugin Notifish

O plugin está disponível no repositório oficial do WordPress e pode ser instalado diretamente pelo painel administrativo ou acessado pelo link abaixo:

https://wordpress.org/plugins/notifish

Considerações finais

O Notifish não é apenas um plugin de envio de mensagens, mas uma ferramenta de integração entre conteúdo e distribuição, pensada para quem publica com frequência e precisa de escala sem perder controle.

Para sites WordPress que utilizam o WhatsApp como canal estratégico, a automação deixa de ser um diferencial e passa a ser uma necessidade operacional.

The post Automação de WhatsApp para WordPress: uma solução escalável para empresas e portais 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.

Mais do que uma nota colorida, o Lighthouse é uma ferramenta de diagnóstico. Saber usá-lo corretamente evita decisões erradas e otimizações inúteis.

O que é o Lighthouse

O Lighthouse é uma ferramenta automatizada de auditoria de páginas web. Ele analisa uma URL e gera um relatório com métricas e recomendações em cinco áreas principais:

• Performance
• Acessibilidade
• Boas práticas
• SEO
• Progressive Web App (PWA)

O objetivo não é apenas pontuar o site, mas mostrar onde estão os gargalos reais.

Onde o Lighthouse está disponível

Você pode usar o Lighthouse de várias formas:

• Chrome DevTools (nativo do navegador)
• Linha de comando (CLI)
• CI/CD (auditorias automatizadas)
• Ferramentas online baseadas no Lighthouse

Para a maioria dos casos, o DevTools já resolve bem.

Como rodar o Lighthouse pelo Chrome

1. Abra o site no Chrome
2. Pressione F12 ou Ctrl + Shift + I
3. Vá até a aba Lighthouse
4. Escolha o tipo de dispositivo (Mobile ou Desktop)
5. Clique em Generate report

Em poucos segundos, o relatório é gerado.

As métricas mais importantes (e o que elas significam)

Performance

Avalia tempo de carregamento e resposta da página. Algumas métricas-chave:

• LCP (Largest Contentful Paint)
  Mede quando o maior elemento visível aparece. Impacta diretamente a percepção de velocidade.
• INP (Interaction to Next Paint)
  Avalia a resposta do site às interações do usuário.
• CLS (Cumulative Layout Shift)
  Mede instabilidade visual (elementos “pulando” na tela).

Essas métricas fazem parte do Core Web Vitals, usados pelo Google como sinal de experiência.

Acessibilidade

Verifica se o site pode ser usado por pessoas com limitações visuais, motoras ou cognitivas. Exemplos de checagem:

• contraste de cores
• textos alternativos em imagens
• labels em formulários
• estrutura semântica do HTML

Mesmo que não seja um requisito legal em todos os casos, acessibilidade melhora usabilidade para todos.

Boas práticas

Aqui entram problemas mais técnicos, como:

• uso de APIs inseguras
• imagens com proporções erradas
• erros de console
• bibliotecas desatualizadas

É uma área que ajuda a manter o site saudável ao longo do tempo.

SEO

O Lighthouse não substitui ferramentas avançadas de SEO, mas valida o básico:

• meta tags essenciais
• indexabilidade
• uso correto de links
• estrutura mínima de conteúdo

Se o site falha aqui, dificilmente terá bom desempenho orgânico.

O erro mais comum: otimizar só para a nota

Muita gente usa o Lighthouse como competição de pontuação. Isso é um erro.

Um site pode ter nota 100 e ainda assim:

• carregar dados desnecessários
• ter arquitetura ruim
• sofrer em cenários reais de tráfego

O relatório deve ser lido como ferramenta de diagnóstico, não como objetivo final.

Mobile vs Desktop: sempre priorize mobile

O Google avalia sites com mobile-first indexing. Isso significa que:

• o relatório mobile é mais relevante
• problemas no mobile impactam mais SEO
• otimizações devem começar pelo mobile

Um site rápido no desktop e lento no celular está em desvantagem.

Lighthouse em produção e CI/CD

Em projetos mais maduros, o Lighthouse pode rodar automaticamente:

• antes de deploy
• após mudanças críticas
• em pipelines de CI/CD

Isso ajuda a evitar regressões de performance e garante que melhorias não sejam perdidas com o tempo.

Limitações do Lighthouse

Apesar de poderoso, o Lighthouse tem limites:

• roda em ambiente controlado
• não reflete todos os cenários reais
• não substitui métricas de usuários reais (RUM)

O ideal é combiná-lo com dados reais de uso, como relatórios de experiência de campo.

Quando o Lighthouse faz mais diferença

Ele é especialmente útil para:

• identificar gargalos iniciais de performance
• validar mudanças estruturais
• educar times sobre impacto técnico
• criar baseline de qualidade

Não é uma bala de prata, mas é um excelente ponto de partida.

O Lighthouse não serve para “tirar nota alta”, mas para entender como o site se comporta do ponto de vista do usuário. Quando usado com critério, ele direciona otimizações que realmente fazem diferença.

Ignorá-lo pode custar performance, experiência e visibilidade. Usá-lo mal pode custar tempo. O valor está em interpretar os dados, não apenas executá-los.

The post O que é Lighthouse e como usar para melhorar seu site 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.

Estruturar um projeto Laravel bem não é sobre “inventar arquitetura”. É sobre reduzir atrito: facilitar manutenção, evitar acoplamento desnecessário e deixar o código previsível para quem chega depois.

A seguir estão práticas que funcionam bem em projetos médios e grandes, especialmente quando já existe operação de produção, roadmap e mudanças frequentes.

Comece pela regra: controller não é lugar de lógica

Controller deveria orquestrar: receber request, validar, chamar a camada certa e responder. Quando regra de negócio fica no controller, você cria um ponto de acoplamento difícil de testar e difícil de reutilizar. Em projeto grande isso vira padrão ruim rapidamente, porque todo mundo copia o que já existe.

O que funciona melhor é mover lógica para classes dedicadas (services/use cases/actions), e deixar o controller como uma “casca” fina. Você ganha clareza, reaproveitamento e testes mais simples.

Estruture por domínio (feature) quando o sistema crescer

A estrutura padrão do Laravel (Controllers, Models, Jobs, etc.) é ótima até um certo ponto. Em sistemas grandes, ela tende a espalhar a mesma funcionalidade por várias pastas e o dev precisa “caçar” arquivos para entender um fluxo.

Uma abordagem que escala melhor é organizar por domínio/feature. Exemplo: tudo relacionado a “Billing” fica próximo (requests, actions, policies, resources, etc.). Isso reduz a fricção para manter e evoluir partes específicas do sistema.

Você não precisa mudar tudo de uma vez. Dá para começar com um ou dois domínios e ir migrando aos poucos, sem reescrever o projeto inteiro.

Estrutura tradicional do Laravel (por tipo)

app/
├── Http/
│   ├── Controllers/
│   ├── Requests/
│   └── Resources/
├── Models/
├── Jobs/
├── Policies/
├── Services/

Problema em projeto grande:
para entender Billing, você precisa abrir 6 pastas diferentes.

Estrutura por domínio / feature

app/
└── Domains/
└── Billing/
├── Http/
│ ├── Controllers/
│ ├── Requests/
│ └── Resources/
├── Actions/
├── Jobs/
├── Policies/
├── Models/
└── Services/

Ou até mais simples:

app/
└── Billing/
    ├── BillingController.php
    ├── CreateInvoice.php
    ├── Invoice.php
    ├── InvoicePolicy.php
    ├── SendInvoiceJob.php
    └── InvoiceResource.php

O Laravel não se importa com a pasta, desde que o namespace esteja correto.

Por que isso escala melhor?

Porque quando alguém entra no projeto e precisa mexer em Billing:

• não precisa caçar arquivos espalhados
• não quebra coisas de outros domínios
• entende o fluxo mais rápido
• reduz medo de alterar código

Em projeto grande, isso faz muita diferença.

Requests e validações como primeiro filtro

Em projeto grande, dado ruim entrando vira bug caro. Centralizar validação em Form Requests mantém o controller limpo e torna regras de entrada explícitas.

Além disso, vale padronizar:

• mensagens de erro;
• formatos de resposta (principalmente APIs);
• validações compartilhadas (traits, rules customizadas).

Quando a validação é consistente, o sistema vira mais previsível e o time para de reinventar a roda a cada endpoint.

Padronize respostas de API desde cedo

Quando cada endpoint responde de um jeito, cada client precisa de lógica diferente, e isso vira dívida técnica distribuída. Para projetos médios e grandes, uma camada consistente de resposta é obrigatória: Resources, transformers, ou uma padronização interna.

O ponto aqui não é “estética”. É operação. Quando algo quebra, você quer logs previsíveis, payload previsível, erros previsíveis. Isso reduz tempo de diagnóstico.

Regras de negócio: não misture persistência com decisão

Um erro comum em Laravel é “decidir” coisas dentro de models e ao mesmo tempo persistir em todo lugar, sem fronteira clara. Em sistemas maiores, o ideal é separar:

• Decisão / regra (o que pode ou não pode)
• Persistência (salvar, consultar)
• Orquestração (fluxo do caso de uso)

Isso permite evoluir regra sem quebrar camada de persistência, e vice-versa. E facilita testar o que realmente importa: a regra.

Jobs, filas e idempotência não são detalhe

Em projeto grande, você inevitavelmente vai para filas: e-mails, notificações, integrações, processamento pesado. O que quebra sistemas grandes não é “usar fila”. É usar fila sem cuidado com:

• idempotência (job rodar duas vezes sem duplicar efeito);
• retries (quando deve tentar de novo e quando deve falhar);
• timeouts;
• dead letter / estratégia para falhas recorrentes;
• logs por job.

Se o seu projeto depende de integração externa, trate isso como cenário normal: o externo vai falhar. A fila é o lugar certo para absorver isso, desde que bem desenhado.

Serviços externos: isole e trate como dependência instável

Integrações externas deveriam estar em classes próprias (clients/adapters), com:

• timeout explícito;
• tratamento de erro consistente;
• retry controlado quando fizer sentido;
• logs contextualizados.

Evite espalhar Http::post() por todo lugar. Em projeto grande isso vira caos, porque não existe ponto único para ajustar comportamento (ex: mudar header, adicionar auth, alterar timeout).

Migrations, seeds e dados de referência bem cuidados

Projeto grande normalmente tem muita migration. E migration desorganizada vira armadilha: ambientes quebram, dev novo não sobe projeto, staging fica inconsistente.

Boas práticas que ajudam:

• migrations com nomes claros;
• dados de referência (enums/tabelas fixas) com seeders idempotentes;
• evitar “seed que depende de estado manual”;
• sempre testar “do zero” em ambiente limpo.

Isso evita que o setup do projeto vire uma gincana.

Configuração: tudo em config e .env, nada hardcoded

Quando cresce, o sistema precisa rodar em múltiplos ambientes e, muitas vezes, múltiplos clientes. Configuração hardcoded vira problema de deploy e vira risco de segurança.

Padronize:

• config/*.php como fonte de configuração;
• .env apenas para valores variáveis;
• nunca commitar senhas e keys;
• e preferencialmente separar integrações por “config + service container”.

Observabilidade: logs estruturados desde o começo

Em projetos grandes, o custo de “descobrir o que aconteceu” é alto. Sem logs bons você perde tempo, perde confiança e perde previsibilidade operacional.

O que vale padronizar:

• logs com contexto (tenant, user_id, request_id, correlation_id);
• níveis corretos (info, warning, error);
• logs de integrações e jobs;
• e um formato consistente (para facilitar busca).

Isso é o que transforma incidentes em diagnóstico rápido.

Testes: foque no que dá retorno real

Não dá para testar tudo em projeto grande, e tentar fazê-lo costuma falhar. O que dá mais retorno é:

• testes de regras de negócio (unit/integration);
• testes de fluxos críticos;
• testes de contratos de API;
• e testes de integração com serviços externos (com mocks ou ambientes controlados).

Teste não é para “subir porcentagem”. É para reduzir risco onde mais dói.

Conclusão

Projetos Laravel grandes não quebram porque Laravel é limitado. Eles quebram porque a base cresce sem estrutura, sem padrões e sem fronteiras claras entre responsabilidades.

Se você mantiver controllers finos, separar domínio/feature, isolar integrações, tratar filas com seriedade e padronizar validação/retorno/log, o projeto continua evoluindo sem virar um monstro. E o melhor: o time consegue manter velocidade sem sacrificar estabilidade.

The post Boas práticas para estruturar projetos em Laravel de médio e grande porte appeared first on Leonardo Nascimento | Engenheiro de Software.

A maioria dos problemas que aparecem em APIs não vem da linguagem, mas de decisões técnicas erradas ou simplesmente ignoradas. Abaixo estão os erros mais comuns que vejo em sistemas que começam a dar dor de cabeça depois de ir para produção.

1) Confiar demais no frontend

Esse é um clássico.

Validar apenas no frontend é assumir que:

• todo cliente vai se comportar bem;
• ninguém vai chamar a API direto;
• dados nunca vão chegar quebrados.

Em produção, isso não acontece.

API precisa validar tudo o que recebe: tipo, formato, limites e estados possíveis. Qualquer dado inválido que entra no sistema vira bug silencioso, inconsistência ou erro difícil de rastrear depois.

2) Não padronizar respostas de erro

Uma hora o endpoint retorna erro como string, outra hora como objeto, outra hora com HTTP 200 e mensagem de erro no corpo.

Isso gera:

• confusão para quem consome a API;
• lógica duplicada no client;
• dificuldade de debug.

API de produção precisa ter padrão. Mesmo formato de resposta, mesmos campos, mesmos códigos HTTP. Isso reduz erro e aumenta previsibilidade.

3) Ignorar controle de requisições

Sem rate limiting, uma API fica exposta a:

• abuso involuntário;
• loops mal implementados em integrações;
• sobrecarga em horários de pico.

Muitas quedas de API não são ataques. São apenas clientes chamando demais um endpoint que não foi preparado para isso.

Controle de requisições não é opcional em produção.

4) Misturar regra de negócio com camada HTTP

Quando controller começa a virar:

• regra de negócio;
• validação;
• persistência;
• resposta HTTP;

o código se torna frágil.

Esse tipo de acoplamento dificulta:

• testes;
• reutilização de lógica;
• manutenção futura.

Separar responsabilidades não é academicismo. É o que evita refatorações dolorosas depois.

5) Não pensar em idempotência

Em produção, requisições podem ser reenviadas. Jobs podem rodar mais de uma vez. Webhooks podem disparar duplicado.

Se a API não for idempotente:

• registros duplicam;
• ações são executadas mais de uma vez;
• efeitos colaterais aparecem.

Esse tipo de bug geralmente só aparece depois de um tempo, quando já tem dado real envolvido.

6) Assumir que dependências externas sempre funcionam

APIs de terceiros falham. Sempre.

Se sua API depende de outro serviço e não define:

• timeout;
• tratamento de erro;
• comportamento de fallback;

ela vai travar junto.

Código de produção não assume sucesso. Ele se prepara para falha.

7) Falta de timeout nas requisições

Sem timeout, uma chamada externa lenta pode:

• travar workers;
• consumir conexões;
• gerar fila acumulada;
• derrubar performance geral.

Timeout é uma forma de proteção do sistema. Não definir é deixar o sistema vulnerável.

8) Falta de logs úteis

Log demais é tão ruim quanto log nenhum.

Em produção, log precisa responder perguntas como:

• o que aconteceu?
• quando aconteceu?
• com qual dado?
• em qual ponto do fluxo?

Logs genéricos ou inexistentes transformam qualquer incidente em caça ao erro.

9) Falta de versionamento da API

Alterar contrato de API sem versionamento quebra clientes silenciosamente.

Versão não é detalhe. É o que permite evoluir a API sem destruir integrações existentes.

Ignorar isso costuma gerar retrabalho e retratação depois.

10) Tratar produção como ambiente de teste

Produção não é lugar para:

• “ver se funciona”;
• testar comportamento;
• improvisar correções.

APIs em produção precisam ser previsíveis, estáveis e fáceis de operar. Qualquer mudança deve assumir impacto real.

Conclusão

APIs quebram porque foram pensadas apenas para funcionar, não para operar em produção.

Evitar esses erros não exige ferramentas mirabolantes. Exige postura técnica, atenção ao contexto e responsabilidade com quem vai depender da API depois.

The post Erros comuns em APIs que causam problemas em produção appeared first on Leonardo Nascimento | Engenheiro de Software.

Através de uma interface simples e agradável, é possível monitorar múltiplos sites , com intervalos de tempo entre 15 segundos e 1 hora, selecionar até 8 localizações,  com tempo mínimo de resposta entre 0.125 e 2.0 segundos e “callbacks” (SMS, Telegram, Slack, StatusPage, Zapier) para ser informado em caso de queda ou restauração do serviço.

Desenvolvi a estratégia para um amigo, que gostaria de receber alertas no WhatsApp em tempo real, quando algum site ou sistema fica-se fora do ar, decidimos tornar o código fonte público.

Requerimentos

• Wppconnect Server
• PHP 7.4

O Wppconnect Server é uma lib não oficial do WhatsApp para envio e recebimento de mensagens. para receber a notificação em seu WhatsApp é necessário ter configurado o Wppconnect server.

Neste tutorial, aprenderemos a configurar o Updown Notify WhatsApp

Updown Notify Whatsapp

Clone o projeto e acesse o diretório

git clone https://github.com/leonardop21/updown-notify-whatsapp && cd updown-notify-whatsapp

Instale as dependências (Necessário ter o composer configurado na máquina)

composer install

Configurando o projeto

No arquivo /public/callback configure um chave pública, ex: Afwe14we555d1230we23sdx

No arquivo /services/WppInfo na função __construct() preencha os dados gerados no Wppconnect-server, para receber notificações no WhatsApp

Apontando para a pasta public

Configure seu servidor http, para ler a partir da pasta public.

Agora, no sistema do Updown.io

No Updown.io insira a sua url de callback junto com a key que definiu, ex: https://meusite.com.br/callback?key=Afwe14we555d1230we23sdx

O Updown Notify Whatsapp aceita apenas requisições post com a key configurada no passo anterior, do contrário, uma página 404 será exibida.

Testando a aplicação

Criei um subdomínio de teste e inseri no updown.io.

No momento em que o site ficou fora do ar, recebi um aviso no WhatsApp, quando voltou ao normal, recebi outro aviso, conforme demonstra as imagens abaixo.

Updown detectou site fora do ar

Callback Updown

O Updown enviou um callback ao sistema, que por sua vez acionou o Wppconnect-Server enviando uma mensagem para o número configurado no services/WppInfo

Site funcionando normalmente

Updown detectou que o site voltou a funcionar

Callback Updown

O Updown enviou um callback ao sistema, que por sua vez acionou o Wppconnect-Server enviando uma mensagem para o número configurado no services/WppInfo

Links úteis

WPPCONNECT-SERVER

UPDOWN-NOFITY-WHATSAPP

The post UPDOWN.IO: Receba notificação no WhatsApp caso seu site fique indisponível appeared first on Leonardo Nascimento | Engenheiro de Software.

A cada dia surgem diversas landing pages na web, seja para promover um evento ou até mesmo a venda de um produto, geralmente essas páginas possuem pelo menos um formulário de contato.

Precisamos proteger esses formulários, se deixarmos a “esmo” os clientes passarão a receber muitos spams e não queremos isso.

Alguns devs preferem criar um “honeypot” que é basicamente um field que recebe uma classe css e nesse css o campo é setado como hidden, no backend é feito uma validação, se esse field oculto for preenchido, o e-mail não é enviado, isso serve para bots menos “inteligentes”.

Uma das melhores soluções do mercado, querendo ou não, é a utilização do Captcha do Google. Pensando nisso, resolvi criar uma integração com o captcha e também utilizar o honeypot que citei acima. Tornei o projeto público, é muito simples de usar.

Você está livre para utilizar e modificar como preferir.

https://github.com/leonardop21/captcha-send-form

The post Protegendo formulários de Landing Page com Captcha v3 invisível e honeypot appeared first on Leonardo Nascimento | Engenheiro de Software.