A forma correta de fazer isso é tratar WhatsApp como camada de notificação, não como sistema de monitoramento. Você continua monitorando com ferramentas e sinais confiáveis (uptime, métricas, logs, filas, erros), mas centraliza o envio e a governança dos alertas em um lugar só — e aí o Notifish entra bem.

A ideia é simples: qualquer evento relevante → vira um “evento de notificação” → Notifish entrega no WhatsApp.

O que vale a pena mandar para o WhatsApp (e o que não vale)

WhatsApp deve receber só o que exige ação ou atenção rápida. Em produção, eu separo em três níveis:

Crítico (manda sempre):

• aplicação fora do ar / endpoint crítico fora
• erro 5xx em alta (explosão de taxa de erro)
• fila parou de consumir / backlog crescendo rápido
• disco quase cheio / risco de indisponibilidade
• falha em integração crítica (pagamento, mensagens, etc.)

Alerta (manda com filtro):

• latência acima do normal por X minutos
• aumento gradual de erros específicos
• Redis indisponível (com fallback) ou lento
• uso de CPU/memória alto por período sustentado

Informativo (geralmente não manda no WhatsApp):

• deploy realizado
• logs de rotina
• warnings esporádicos

O que destrói o canal é “alerta informativo demais”. WhatsApp é para sinal forte.

Arquitetura recomendada (sem gambiarra)

O melhor padrão é este:

1. Você tem fontes de evento (monitoramento/observabilidade):

• Uptime/health-check (aplicação)
• Métricas do servidor (CPU, RAM, disco)
• Logs (erros específicos, padrões)
• Erros de aplicação (exceptions)
• Filas (backlog, falhas, retries)

2. Um “gerador de eventos” cria um evento padronizado.
3. Você envia esse evento para o Notifish via API.
4. Você define roteamento, deduplicação e templates

• para qual número/grupo enviar
• se deve agrupar, deduplicar, aplicar rate limit
• qual template usar (curto, completo, escalonamento)

Esse desenho escala porque você não espalha envio de WhatsApp por todo sistema. Você centraliza.

Como fica uma mensagem boa no WhatsApp

Uma mensagem útil precisa ter contexto mínimo e ação sugerida:

• Título curto (o que aconteceu)
• Ambiente (prod, staging)
• Serviço (api, worker, site)
• Sintoma (erro, timeout, backlog)
• Impacto (estimado)
• Link (dashboard/logs, se existir)
• Ação recomendada (1 linha)

Exemplo de payload humano:

ALERTA CRÍTICO: API 5xx alto
Ambiente: prod | Serviço: api
Erros 5xx: 18% (últimos 5 min)
Endpoint: /api/orders
Ação: verificar logs + dependência “Payments”

Implementação via API com Notifish (modelo prático)

Você pode integrar de dois jeitos:

1) Seu sistema envia eventos diretamente (Laravel, cron, scripts)

Bom quando você mesmo detecta (fila, logs, métricas internas).

2) Ferramentas externas chamam o Notifish (uptime/monitoramento)

Bom para health-check e métricas do servidor (quando a ferramenta já faz o “detector”).

Como você pediu implementação via API, vou te mostrar um modelo que funciona bem

Payload recomendado (evento)

{
  "message": "Sua mensagem de alerta",
  "identifier": "seu identificador único de disparo",
  "link": true,
  "typing": "composing",
  "delayMessage": 1200
}

Por que esse formato funciona:

• identifier: chave de deduplicação / idempotência do alerta
• message: texto já formatado com contexto (ambiente/serviço/ação)
• delayMessage/typing: ajustes de entrega (opcionais)

Exemplo em Laravel enviando evento ao Notifish

class NotifishClient
{
    public function sendToGroups(string $message, string $identifier, bool $link = true, int $delayMs = 0, string $typing = 'composing'): void
    {
        $url = rtrim(config('services.notifish.base_url'), '/')
            . '/api/v2/' . config('services.notifish.instance')
            . '/whatsapp/message/groups';

        $payload = [
            'message' => $message,
            'identifier' => $identifier,
            'link' => $link,
            'typing' => $typing,
            'delayMessage' => $delayMs,
        ];

        $response = Http::withToken(config('services.notifish.token'))
            ->acceptJson()
            ->contentType('application/json')
            ->timeout(8)
            ->post($url, $payload);

        if (!$response->successful()) {
            logger()->error('Notifish send failed', [
                'status' => $response->status(),
                'body' => $response->body(),
                'identifier' => $identifier,
            ]);
        }
    }
}

Regras importantes para não virar caos

Se você fizer só “manda mensagem”, em 2 semanas o canal morre. Algumas regras que eu considero obrigatórias:

1) Deduplicação

• Todo alerta precisa de dedupe_key.
• Se o mesmo alerta acontecer 100 vezes, você manda 1 e “atualiza”/agrupa.

2) Rate limit por severidade

• Crítico: pode repetir, mas com intervalo mínimo (ex.: 5–10 min).
• Alerta: intervalo maior (ex.: 15–30 min).
• Informativo: geralmente fora do WhatsApp.

3) Idempotência

• Eventos iguais devem produzir o mesmo estado.
• Se a chamada repetir, não deve disparar em duplicidade.

4) Conteúdo curto
WhatsApp é leitura rápida. Se precisar detalhe, coloque em meta e mande link para logs/dashboard quando possível.

5) Escalonamento
Se continuar crítico por X tempo, notifica outro grupo/gestor.

O que monitorar para disparar eventos úteis (fontes típicas)

Você pode começar com estes gatilhos (são os que mais dão retorno):

• Health-check HTTP (200/500, tempo de resposta, quedas)
• Taxa de erro (5xx e exceções por minuto)
• Fila (backlog, jobs failed, tempo médio)
• Banco (conexões, queries lentas, timeouts)
• Redis (latência, indisponibilidade, memória/eviction)
• Servidor (disco, load alto sustentado)
• Integrações externas (timeout e falha por janela)

Monitorar “pelo WhatsApp” não é substituir observabilidade por chat. É transformar sinais importantes em alertas acionáveis, com governança. O Notifish entra como a peça que centraliza o envio e impede que cada sistema invente seu próprio jeito de notificar.

Se você faz dedupe, rate limit, severidade e contexto mínimo, o WhatsApp vira um canal confiável — e não um spam de produção.

The post Como monitorar aplicação e servidor pelo WhatsApp (logs, erros e alertas) 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.

Spoiler: quando é ruim, os sinais aparecem rápido

Projetos WordPress mal feitos não falham em silêncio. Eles deixam rastros.
O problema é que muita gente não sabe onde olhar.

Em 10 minutos, você consegue ter uma boa noção se está diante de:

• Um projeto profissional ou uma bomba-relógio disfarçada de site bonito

Abra o site no celular (primeiro minuto)

Antes de qualquer ferramenta, abra no mobile.

Sinais clássicos de problema:

• Site lento para carregar
• Layout “pulando”
• Texto pequeno ou mal espaçado
• Elementos quebrados

Se o site já sofre no mobile, o problema geralmente é estrutural — não é “só ajuste fino”.

Inspecione o HTML (2 minutos)

Clique com o botão direito → Inspecionar.

Se você vê:

• Camadas infinitas de <div>
• Classes genéricas e repetidas
• Estrutura semântica inexistente
• Conteúdo principal perdido no meio do código

Isso indica HTML inflado, típico de projetos feitos no arrastar e soltar.

HTML ruim é sinal de:

• SEO fraco
• Performance ruim
• Manutenção difícil

Veja quantos arquivos CSS e JS são carregados (1 minuto)

Abra a aba Network do navegador.

Red flags claras:

• 15, 20, 30 arquivos CSS
• JS sendo carregado em todas as páginas, sem necessidade
• Scripts de plugins que nem aparecem na tela

Quanto mais dependência global, pior a saúde do projeto.

Cheque a hierarquia de títulos (H1, H2, H3) (1 minuto)

Use qualquer extensão simples ou até o próprio inspector.

Problemas comuns:

• Mais de um H1
• H1 usado como elemento visual
• Pulando de H2 para H4
• Headings usados só para “aumentar fonte”

Isso é um tiro no pé para SEO e acessibilidade.

Abra o painel administrativo (2 minutos)

Se você tem acesso ao admin, a verdade aparece rápido.

Sinais de alerta:

• 15, 30, 50 plugins ativos
• Plugins com funções sobrepostas
• Plugins abandonados ou sem atualização
• Tudo resolvido com plugin, nada com código

Projeto bom usa plugin como ferramenta, não como muleta.

Dê uma olhada no banco de dados (1 minuto)

Mesmo sem aprofundar, alguns sinais gritam:

• Tabelas demais para um site simples
• Prefixos estranhos
• Plugins que criaram dezenas de tabelas
• Lixo acumulado de plugins removidos

Quando um site institucional tem mais de 200 tabelas, algo está muito errado. (História real)

Veja como o cache está sendo tratado (1 minuto)

Perguntas simples:

• Tem cache?
• Cache é de página, objeto, CDN?
• Limpa cache a cada acesso?

Cache mal configurado é quase tão ruim quanto não ter cache nenhum.

Observe como o site reage a pequenas mudanças

Esse é um teste indireto, mas poderoso.

Pergunte:

• Atualizar um plugin quebra layout?
• Trocar tema é inviável?
• Qualquer ajuste exige “rezar”?

Se sim, o projeto não foi pensado para evoluir.

O padrão por trás de tudo isso

Projetos WordPress mal feitos geralmente compartilham a mesma origem:

• Pressa
• Preço baixo
• Soluções visuais
• Falta de base técnica

O site até funciona, mas vive no limite.

Importante: WordPress não é o problema

WordPress bem utilizado:

• É rápido
• Escala
• É estável
• Aguenta tráfego
• É fácil de manter

O problema nunca foi o CMS.
O problema é como ele é usado.

Identificar um projeto WordPress mal feito cedo:

• Evita retrabalho
• Evita prejuízo
• Evita desgaste com cliente
• Evita promessas que não podem ser cumpridas

E a melhor parte:
você não precisa de ferramenta cara, só de olhar técnico.

The post Como identificar um projeto WordPress mal feito em 10 minutos appeared first on Leonardo Nascimento | Engenheiro de Software.

1. Claude.ai — o cérebro que resolve tudo
Criado pela Anthropic, o Claude é o rival direto do ChatGPT, e muitos juram que ele é ainda mais “humano”. Capaz de entender contextos complexos, revisar textos longos e até analisar documentos inteiros, o Claude virou o companheiro ideal para quem precisa de precisão e agilidade.

2. Ranked.ai — o impulso para o topo do Google
Essa IA é uma bênção para quem vive de SEO. Ela analisa, sugere e otimiza o conteúdo do seu site para conquistar posições valiosas nos resultados de busca. O melhor? Faz isso praticamente sozinha, com atualizações em tempo real.

3. Syllaby.io — vídeos prontos para bombar
Quer transformar roteiros em conteúdo de vídeo automático? O Syllaby faz isso com maestria. Ele cria, edita e entrega vídeos completos com narração e legenda, otimizados para TikTok, Reels e Shorts. Um aliado de peso para criadores e marcas.

4. Replit.com — código sem complicação
Mais do que um simples editor, o Replit é um ambiente de desenvolvimento guiado por IA. Ele escreve código, corrige bugs e até explica o que você está fazendo errado. É como ter um mentor de programação disponível 24 horas.

5. Manus.im — o superagente inteligente
Considerada uma das plataformas mais versáteis, o Manus é um agente de IA que centraliza tarefas: pesquisa, escrita, automação e até integração entre apps. Tudo num só lugar, com interface intuitiva e resultados rápidos.

6. Suno.com — música em segundos
Aqui, criatividade e tecnologia tocam juntos. O Suno permite criar faixas completas em poucos cliques, combinando estilos e vozes realistas. Ideal para trilhas de vídeos, podcasts ou simplesmente para quem quer experimentar novos sons.

7. Fliki.ai — texto que vira vídeo
Pegue um texto simples e veja ele se transformar em conteúdo visual dinâmico. O Fliki gera vídeos curtos, prontos para redes sociais, com narração natural e variedade de estilos. Um presente para quem quer produção rápida sem perder qualidade.

8. CloudXLR.com — o construtor de apps definitivo
Essa plataforma é o sonho de empreendedores e desenvolvedores. A CloudXLR usa IA para montar aplicativos completos, desde o design até a lógica interna, sem exigir uma linha de código manual.

9. Genspark.ai — o superagente da produtividade
Genspark é como um estagiário genial: escreve, pesquisa, planeja, organiza e ainda gera relatórios. Ele funciona como uma central de automação pessoal, perfeita para quem gerencia muitas tarefas ao mesmo tempo.

10. Fastread.io — eBooks na velocidade da luz
Produzir um livro digital nunca foi tão rápido. O Fastread cria, formata e finaliza eBooks a partir de poucos tópicos, com estrutura profissional e linguagem envolvente.

Bônus extra

• Perplexity — busca com IA que realmente responde, citando fontes.
• ElevenLabs — vozes artificiais extremamente naturais.
• Pika — geração de vídeos criativos com IA generativa.

The post 10 inteligências artificiais que você não pode ignorar em 2026 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.

Você quer receber um evento via API (Webhook), enviar uma mensagem no WhatsApp via Notifish e registrar o resultado (sucesso/erro) em log.

Esse fluxo é útil para:

• alertas operacionais
• notificações de deploy
• falhas de integração
• notificações de sistema para grupos

Pré-requisitos

1. n8n rodando e acessível
2. endpoint do Notifish (o seu padrão):
   POST https://meu-dominio.notifish.com/api/v2/{INSTANCE_UUID}/whatsapp/message/groups
   com header Authorization: Bearer ...
3. um lugar para log
   Vou te dar 2 opções:

• A) log em arquivo via HTTP (endpoint seu) — mais profissional
• B) log no próprio n8n (Execution data) + uma planilha/banco (se preferir)

Aqui vou usar a opção A (mais “produção”).

Parte 1 — Contrato da API (Webhook)

Você vai expor um endpoint no n8n, por exemplo:

POST https://SEU_N8N/webhook/notify

Payload recomendado (simples e suficiente):

{
  "title": "API 5xx alto",
  "message": "Erros 5xx acima do normal em /api/orders",
  "url": "https://seu-dashboard",
  "identifier": "prod:api:5xx",
  "delayMessage": 0
}

Repare que já mandamos identifier. Isso permite deduplicar e evitar spam.

Parte 2 — Dedupe (anti-spam) usando Redis (opcional, mas recomendado)

Se você tiver Redis (muito comum), dá para usar um passo “check” antes do envio.

• chave: dedupe:{identifier}
• TTL: 300s (5 minutos) por exemplo
  Se existir, você não envia.

Se você não tiver Redis, dá para deduplicar com “Data Store” do n8n ou com um endpoint seu.

Vou te passar o fluxo com Data Store do n8n (não depende de infra extra).

Parte 3 — Enviar WhatsApp via Notifish

O Notifish recebe:

{
  "message": "...",
  "identifier": "...",
  "link": true,
  "typing": "composing",
  "delayMessage": 1200
}

A gente vai montar isso no n8n.

Parte 4 — Registrar Log

Depois do envio (sucesso ou falha), registramos em um endpoint de log. Exemplo:

POST https://seu-sistema.com/api/logs/notifish

Log recomendado:

{
  "identifier": "prod:api:5xx",
  "status": "success",
  "http_status": 200,
  "provider": "notifish",
  "payload": { ... },
  "response": { ... },
  "created_at": "2026-01-22T00:00:00-03:00"
}

NODES DO WORKFLOW (passo a passo)

1) Webhook (Trigger)

• Method: POST
• Path: notify
• Response: JSON (200)

2) Function (Normalize)

Cria um formato consistente e monta a mensagem final do WhatsApp:

• título + mensagem + url
• garante identifier
• define delayMessage

3) Data Store (Get)

Busca identifier na datastore (dedupe).

4) IF (Já enviou?)

Se já existe registro recente, responde 200 “ignored” e não envia.

5) HTTP Request (Notifish)

POST no endpoint do Notifish com Bearer Token.

6) Data Store (Set)

Salva identifier com TTL (ex.: 300s) para dedupe.

7) HTTP Request (Log Success)

Envia log para seu endpoint.

8) Error Trigger / Catch (Log Error)

Se Notifish falhar, manda log com status error.

JSON do workflow para importar no n8n

Abaixo um workflow base. Você só precisa trocar:

• NOTIFISH_INSTANCE_UUID
• NOTIFISH_TOKEN
• LOG_ENDPOINT_URL

Import: n8n → Workflows → Import from file/clipboard

{
  "name": "API → Notifish WhatsApp → Log (com dedupe)",
  "nodes": [
    {
      "parameters": {
        "path": "notify",
        "httpMethod": "POST",
        "responseMode": "lastNode",
        "options": {}
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [260, 300]
    },
    {
      "parameters": {
        "functionCode": "const body = $json;\n\nconst title = body.title || 'Notificação';\nconst msg = body.message || '';\nconst url = body.url || '';\n\nconst identifier = body.identifier || `generic:${Date.now()}`;\nconst delayMessage = body.delayMessage ?? 0;\n\nconst whatsappMessage = `*${title}*\\n\\n${msg}${url ? `\\n\\n${url}` : ''}`;\n\nreturn [{\n  identifier,\n  delayMessage,\n  notifishPayload: {\n    message: whatsappMessage,\n    identifier,\n    link: true,\n    typing: 'composing',\n    delayMessage\n  },\n  original: body\n}];"
      },
      "name": "Normalize",
      "type": "n8n-nodes-base.function",
      "typeVersion": 2,
      "position": [520, 300]
    },
    {
      "parameters": {
        "operation": "get",
        "key": "={{$json.identifier}}"
      },
      "name": "Dedupe Get",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [760, 300]
    },
    {
      "parameters": {
        "conditions": {
          "boolean": [
            {
              "value1": "={{$json.value !== undefined && $json.value !== null}}",
              "value2": true
            }
          ]
        }
      },
      "name": "Já enviou?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2,
      "position": [980, 300]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"ignored\",\"reason\":\"dedupe\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return Ignored",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1210, 200]
    },
    {
      "parameters": {
        "url": "https://meu-dominio.notifish.com/api/v2/NOTIFISH_INSTANCE_UUID/whatsapp/message/groups",
        "method": "POST",
        "authentication": "none",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer NOTIFISH_TOKEN"
            },
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "Accept",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{$json.notifishPayload}}",
        "options": {
          "timeout": 8000
        }
      },
      "name": "Send Notifish",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1210, 380]
    },
    {
      "parameters": {
        "operation": "set",
        "key": "={{$json.identifier}}",
        "value": "={{JSON.stringify({sentAt: new Date().toISOString()})}}"
      },
      "name": "Dedupe Set",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [1450, 380]
    },
    {
      "parameters": {
        "url": "LOG_ENDPOINT_URL",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Content-Type",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{ {\n  identifier: $json.identifier,\n  status: 'success',\n  provider: 'notifish',\n  response: $json,\n  created_at: new Date().toISOString()\n} }}"
      },
      "name": "Log Success",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1690, 380]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"sent\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return OK",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1910, 380]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Normalize",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Normalize": {
      "main": [
        [
          {
            "node": "Dedupe Get",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Get": {
      "main": [
        [
          {
            "node": "Já enviou?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Já enviou?": {
      "main": [
        [
          {
            "node": "Return Ignored",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Send Notifish",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Send Notifish": {
      "main": [
        [
          {
            "node": "Dedupe Set",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Set": {
      "main": [
        [
          {
            "node": "Log Success",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Log Success": {
      "main": [
        [
          {
            "node": "Return OK",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false
}

Observações importantes (produção)

1) Dedupe com Data Store não tem TTL nativo

Ele salva “para sempre” se você não limpar. Em produção, o ideal é:

• usar Redis para TTL real, ou
• incluir timestamp e limpar por job diário

Se você quiser, eu te mando a versão com Redis (TTL real).

2) Log endpoint

Se você não tiver endpoint pronto, você pode logar em:

ou até em um arquivo via API sua

PostgreSQL/MySQL via node de banco

Google Sheets (rápido)

The post Fluxo n8n: API, WhatsApp, Log (com dedupe e tratamento de erro) appeared first on Leonardo Nascimento | Engenheiro de Software.

É nesse contexto que ferramentas como o n8n ganham espaço.

O que é o n8n

O n8n é uma ferramenta de automação baseada em workflows, onde cada fluxo representa uma sequência de ações encadeadas. Essas ações podem envolver chamadas HTTP, processamento de dados, decisões condicionais, integração com serviços externos ou execução de lógica personalizada.

Diferente de scripts isolados ou cron jobs espalhados, o n8n centraliza esse tipo de automação em um único lugar, com visibilidade e controle.

Como o n8n funciona na prática

O funcionamento do n8n se baseia em três conceitos principais:

1) Nodes (nós)

Cada node representa uma ação específica: receber um webhook, chamar uma API, transformar dados, enviar uma mensagem, salvar em banco, entre outros.

2) Workflows

Um workflow é o encadeamento desses nodes. Ele define:

• onde o fluxo começa
• quais decisões são tomadas
• quais ações acontecem em sequência

3) Execuções

Toda vez que um workflow roda, o n8n registra a execução. Isso permite:

• ver entradas e saídas
• identificar erros
• reprocessar execuções

Essa rastreabilidade é um dos pontos fortes da ferramenta.

Onde o n8n costuma ser usado

Na prática, o n8n aparece com frequência em cenários como:

• integração entre sistemas que não se conversam nativamente
• automação de processos manuais repetitivos
• consumo e envio de webhooks
• sincronização de dados entre APIs
• orquestração de tarefas assíncronas

Ele não substitui código em todos os casos, mas reduz bastante a necessidade de escrever lógica repetitiva.

n8n não é “low-code mágico”

Um erro comum é achar que o n8n elimina a necessidade de conhecimento técnico. Na realidade, ele expõe a complexidade de forma visual, mas não a remove.

Para usar bem o n8n, é importante entender:

• HTTP
• APIs REST
• autenticação (tokens, headers, OAuth)
• formatos de dados (JSON)
• tratamento de erros

Sem isso, o fluxo até pode funcionar, mas fica frágil.

A diferença entre automação e orquestração

Automação simples executa tarefas. Orquestração coordena sistemas.

O n8n se destaca quando usado como orquestrador:

• recebe eventos
• decide o que fazer
• chama serviços na ordem correta
• lida com falhas e exceções

Quando bem aplicado, ele vira um ponto central de integração, não apenas um “gatilho”.

Quando faz sentido usar n8n

O n8n costuma ser uma boa escolha quando:

• há muitas integrações externas
• a lógica muda com frequência
• manter código para cada integração ficou caro
• é importante visualizar e auditar fluxos

Ele também é útil para prototipação, desde que exista cuidado para não deixar soluções provisórias virarem definitivas sem revisão.

Quando não faz sentido

Nem tudo precisa de n8n. Em alguns casos, ele adiciona mais uma camada desnecessária.

Exemplos:

• lógica extremamente simples e estável
• processamento pesado ou de alta performance
• fluxos críticos que exigem controle fino de memória ou tempo

Nesses cenários, código direto costuma ser mais adequado.

n8n em produção: pontos de atenção

Rodar n8n em produção exige alguns cuidados:

• persistência de dados (banco configurado corretamente)
• controle de acesso
• versionamento de workflows
• monitoramento de falhas
• cuidado com loops e execuções em massa

Sem isso, a automação vira fonte de problemas, não de solução.

O papel do n8n na arquitetura moderna

O n8n não é o “coração” do sistema, mas funciona bem como camada de integração. Ele conecta serviços, traduz formatos e orquestra eventos, enquanto a regra de negócio principal permanece no backend.

Essa separação ajuda a manter o sistema mais flexível e adaptável a mudanças.

O n8n é uma ferramenta poderosa quando usada com consciência. Ele não substitui engenharia de software, mas resolve muito bem um problema específico: orquestrar integrações e automações de forma clara e controlada.

Quando entra como solução pensada, reduz complexidade. Quando entra como atalho, costuma cobrar seu preço depois.

The post N8N: o que é, como funciona e quando faz sentido usar appeared first on Leonardo Nascimento | Engenheiro de Software.

Essa mudança não aconteceu por moda, mas por necessidade.

O problema de depender apenas de dashboards

Sistemas modernos produzem dados o tempo todo: logs, eventos, erros, métricas, status de filas, integrações externas. Em teoria, tudo isso deveria ser acompanhado por dashboards bem configurados.

Na prática, dashboards só funcionam quando alguém está olhando para eles. Em incidentes reais, o que costuma acontecer é diferente: o problema aparece primeiro no efeito, não na métrica. Quando alguém percebe, o impacto já aconteceu.

É nesse ponto que canais ativos, como o WhatsApp, começam a fazer sentido.

Alertar não é o mesmo que informar

Um erro comum ao levar dados para o WhatsApp é tentar transformar o canal em espelho do sistema: enviar tudo, o tempo todo. O resultado costuma ser o oposto do esperado — excesso de mensagens, ruído e alertas ignorados.

O valor real está em selecionar o que importa, formatar bem a mensagem e entregar no momento certo. Não é sobre volume, é sobre contexto.

A importância de mensagens legíveis

Alertas técnicos mal formatados são tão inúteis quanto a ausência deles. Mensagens longas demais, payloads em JSON ou textos sem hierarquia não ajudam na tomada de decisão.

Em ambientes maduros, o WhatsApp recebe mensagens curtas, diretas e com contexto suficiente para entender:

• o que aconteceu
• onde aconteceu
• se exige ação imediata

Sem isso, o canal perde credibilidade rapidamente.

Quando a simplicidade vira vantagem

Algumas soluções optam por formatos extremamente estruturados, cheios de campos e metadados. Isso funciona bem para sistemas internos, mas não necessariamente para canais humanos.

Ferramentas como o Notifish seguem uma abordagem mais simples: recebem uma mensagem já pronta para leitura, com um identificador básico e controle de entrega. Isso desloca a inteligência para quem envia, não para quem recebe.

Na prática, isso facilita integração com sistemas existentes sem exigir grandes adaptações.

Um padrão que aparece em operações reais

Em operações com volume significativo, o WhatsApp costuma ser usado para:

• alertas críticos de produção
• falhas de integração externa
• eventos que exigem ação humana
• confirmações de processos assíncronos

Ele não substitui logs, métricas ou ferramentas de observabilidade. Ele complementa, cobrindo o espaço entre o evento técnico e a reação humana.

O risco de transformar alerta em ruído

Sempre que um novo canal é adicionado, surge o risco de exagero. Alertar tudo é quase tão ruim quanto não alertar nada.

Operações estáveis costumam ter regras claras:

• poucos tipos de alerta
• mensagens bem definidas
• identificação para evitar duplicidade
• silêncio como padrão

Quando o WhatsApp segue essa lógica, ele se mantém útil. Quando vira canal genérico, é rapidamente ignorado.

Integração como parte da arquitetura, não como atalho

Outro ponto importante é tratar a integração com WhatsApp como parte da arquitetura do sistema, e não como um remendo. Isso significa:

• decidir onde o alerta nasce
• quem é responsável por enviá-lo
• quando ele deve ser disparado
• e quando não deve

Sem esse cuidado, qualquer ferramenta vira apenas mais uma dependência.

Conclusão

O WhatsApp deixou de ser apenas um meio de comunicação informal e passou a ocupar um espaço relevante em operações técnicas. Quando usado com critério, ele encurta o tempo entre o problema e a reação.

Ferramentas que respeitam essa lógica — simples na entrada, claras na saída — tendem a se encaixar melhor em sistemas reais. Não por prometerem mais, mas por atrapalharem menos.

The post Quando o WhatsApp vira canal operacional (e não só meio de envio) appeared first on Leonardo Nascimento | Engenheiro de Software.

1. criar a instância
2. conectar o WhatsApp (QR Code)
3. enviar a mensagem

Se pular qualquer um deles, não funciona.

1️⃣ Confirmar dados básicos da instalação

Você precisa ter em mãos:

• Server URL
  Exemplo: https://api.seudominio.com
• API Key global (gerada pelo Orion na instalação)

Esses dois dados são usados em todas as chamadas.

2️⃣ Criar a instância (obrigatório)

Na Evolution API v2, não existe envio sem instância.

Endpoint

POST /instance/create

Exemplo com curl

curl -X POST https://api.seudominio.com/instance/create \
  -H "apikey: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "primeira-instancia"
  }'

Resposta esperada

Algo semelhante a:

{
  "instance": {
    "instanceName": "primeira-instancia",
    "status": "created"
  }
}

Se deu erro aqui, pare. O resto não vai funcionar.

3️⃣ Conectar o WhatsApp (QR Code)

Depois da instância criada, você precisa conectar o número.

Gerar QR Code

GET /instance/connect/{instanceName}

curl -X GET https://api.seudominio.com/instance/connect/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI"

A resposta vem com o QR Code em base64 ou link.

Abra no navegador ou use o manager do Orion:

https://api.seudominio.com/manager

Escaneie com o WhatsApp do celular.

Verificar status da instância

Antes de enviar mensagem, confirme que está conectada.

GET /instance/connectionState/{instanceName}

curl -X GET https://api.seudominio.com/instance/connectionState/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI"

Status esperado:

{
  "state": "open"
}

Se não estiver open, não adianta tentar enviar mensagem.

4️⃣ Primeiro disparo de mensagem (texto simples)

Agora sim.

Endpoint v2 para texto

POST /message/sendText/{instanceName}

Exemplo real

curl -X POST https://api.seudominio.com/message/sendText/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "559999999999",
    "text": "Olá! Este é meu primeiro disparo pela Evolution API v2."
  }'

⚠️ Formato do número

• Sempre com DDI + DDD + número
• Sem +, sem espaço, sem traço

Exemplo válido:

5591999999999

5️⃣ O que acontece se não enviar?

Os erros mais comuns no primeiro disparo:

❌ Instância não conectada

Resposta típica:

instance not connected

❌ Número inválido

• faltou DDI
• tem +
• tem espaço

❌ API Key errada

Resposta:

Unauthorized

❌ Endpoint errado (v1 ≠ v2)

Na v2:

/message/sendText/{instance}

Na v1 era diferente. Não misture.

6️⃣ Teste rápido pelo Manager (opcional)

Se quiser validar sem curl:

1. Acesse: https://api.seudominio.com/manager
2. Escolha a instância
3. Vá em Send Message
4. Envie um texto simples

Se funciona no manager e não via API, o problema é payload ou headers.

7️⃣ Próximos disparos possíveis (depois do primeiro)

Depois que o texto simples funciona, você pode evoluir para:

• imagem
• vídeo
• áudio
• botão
• lista
• disparos em massa
• integração com Laravel, n8n, Notifish etc.

Mas sempre valide texto primeiro.

Resumo rápido (ordem correta)

1️⃣ criar instância
2️⃣ conectar WhatsApp
3️⃣ confirmar state = open
4️⃣ enviar sendText

Se seguir isso, funciona.

The post Como fazer o primeiro disparo na Evolution API appeared first on Leonardo Nascimento | Engenheiro de Software.

Quando alguém usa “funciona local” como argumento técnico, geralmente está ignorando o contexto em que o sistema realmente vai operar. E é exatamente aí que os problemas começam.

Em local, você tem controle total. O banco está limpo, a latência é praticamente zero, não existem requisições concorrentes, não há retries, não há jobs acumulados, não há serviços externos oscilando. Você executa uma ação, olha o resultado e segue em frente. É um ambiente artificialmente perfeito.

Produção é o oposto disso.

A primeira diferença aparece com concorrência. Localmente, você clica uma vez. Em produção, dezenas ou centenas de usuários fazem a mesma ação ao mesmo tempo. Jobs rodam em paralelo. Requests competem por recursos. Código que nunca apresentou problema começa a gerar condição de corrida, duplicidade de execução e dados inconsistentes. Nada disso aparece no teste local simples.

Outra diferença crítica é latência. Em local, chamadas HTTP e queries são praticamente instantâneas. Em produção, uma API externa pode demorar segundos para responder, ou responder de forma intermitente. Um banco pode ficar lento sob carga. Um cache pode expirar no pior momento. Código que assume resposta imediata funciona local, mas degrada ou trava em produção.

Existe também a questão do volume de dados. Local costuma ter poucos registros. Produção tem milhares ou milhões. Queries que pareciam inofensivas passam a consumir tempo e recursos. Loops simples viram gargalo. Processamentos que eram aceitáveis começam a estourar timeout. O problema não é o código “errado”, é o código não preparado para escala.

Dependências externas são outro ponto ignorado em ambiente local. Muitas vezes você testa com mock, sandbox ou serviço estável. Em produção, serviços externos falham, ficam lentos ou retornam dados inesperados. Se o sistema não foi desenhado para lidar com isso, o erro externo vira indisponibilidade interna.

Local também não expõe problemas de observabilidade. Em produção, quando algo dá errado, você precisa responder rápido: o que aconteceu, quando, com qual dado, em qual fluxo. Código que “funciona local” mas não gera logs úteis transforma qualquer incidente em uma investigação longa e cara.

Outro ponto comum é configuração e ambiente. Local costuma ter permissões amplas, cache limpo, variáveis simples. Produção tem múltiplos ambientes, secrets, variáveis diferentes, limites de recurso e regras de segurança. Código que assume configuração fixa funciona local e quebra fora dele.

Existe ainda o fator tempo. Local você testa agora. Produção roda por semanas ou meses. Vazamentos de memória, acúmulo de jobs, crescimento de filas e degradação progressiva só aparecem com o tempo. “Funciona local” raramente considera isso.

Nada disso significa que testar local não importa. Significa que teste local valida comportamento, não valida operação. Ele é necessário, mas está longe de ser suficiente.

Código pronto para produção é aquele que:

• lida bem com concorrência
• assume latência e falha
• escala com dados reais
• é observável
• se comporta de forma previsível sob estresse

Sem isso, o “funciona local” vira apenas uma falsa sensação de segurança.

“Funciona local” não é critério de qualidade. É apenas o primeiro degrau. Produção cobra decisões que local nunca vai cobrar: resiliência, previsibilidade e responsabilidade técnica.

Quando alguém entende isso, muda a forma de escrever código. Quando não entende, continua apagando incêndio e se perguntando por que algo que “funcionava perfeitamente” começou a falhar sem explicação.

The post Na minha máquina funciona. Vamos levar sua máquina para o usuário então appeared first on Leonardo Nascimento | Engenheiro de Software.