Por que o n8n nunca deve falar direto com o sistema do cliente: arquitetura de autoatendimento no WhatsApp

Este é um case técnico próprio da Crazy Diamond — uma demo de arquitetura, não um sistema entregue a cliente real. Ele existe para mostrar como estruturamos automação de autoatendimento via WhatsApp quando o projeto precisa ser seguro e auditável, não apenas funcionar na demonstração.

O problema que isso resolve

Empresas com alto volume de solicitações repetitivas — provedores de internet, clínicas, condomínios, e-commerce, escritórios de serviço — recebem o mesmo tipo de pedido centenas de vezes por mês. Trocar uma senha, confirmar um agendamento, consultar um status, atualizar um cadastro. Cada um desses pedidos passa hoje por um atendente humano.

Automatizar isso é tentador e fácil de fazer errado. O caminho rápido é montar todo o fluxo dentro de uma ferramenta visual e deixar que ela chame direto o sistema da empresa.

O erro comum

A ferramenta de orquestração de fluxo é ótima para conversa: menu interativo, ramificações, coleta de dados, timeout de sessão. É péssima para ser o lugar onde vivem as credenciais do ERP.

Quando o fluxo visual chama o sistema do cliente diretamente, cada nó de requisição HTTP passa a carregar credencial de produção. Não há controle de acesso real, não há uma camada que decida o que é permitido, e qualquer pessoa com acesso ao editor do fluxo passa a ter acesso efetivo ao sistema de produção. É o erro mais comum desse tipo de automação.

A ferramenta de fluxo nunca fala direto com o sistema do cliente. Ela só fala com o backend, que decide o que é permitido.

A arquitetura

O desenho separa deliberadamente as duas responsabilidades. A camada de orquestração cuida da conversa. O backend cuida do que exige segurança e lógica real: validação de identidade, regras de negócio, idempotência, log de auditoria e a chamada final para o sistema do cliente — ERP, SGP, CRM ou banco de dados.

O caminho completo é: cliente no WhatsApp → WhatsApp Cloud API → camada de orquestração → backend de validação e execução → sistema do cliente. A orquestração conversa apenas com o backend, por rede interna. Nenhuma credencial de produção circula dentro do fluxo visual.

O fluxo demonstrado

São seis passos, genéricos e adaptáveis a qualquer nicho: o cliente inicia a conversa; o fluxo apresenta um menu interativo; o backend valida a identidade contra a base do cliente; o fluxo coleta os dados específicos da solicitação; o backend executa a ação via API no sistema do cliente; e o fluxo confirma a conclusão.

O que muda de um nicho para outro é apenas o quinto passo. Num provedor de internet, é a troca de senha do roteador. Numa clínica, a confirmação ou reagendamento de consulta. Num condomínio, a liberação de visitante. Num e-commerce, a consulta de status de pedido. A arquitetura é a mesma.

Decisões de implementação

WhatsApp Cloud API oficial da Meta, não biblioteca não-oficial — automação de atendimento em cima de biblioteca não-oficial é risco de bloqueio de número, e é o tipo de economia que sai cara.

O backend expõe validação de identidade e criação de solicitação, com DTOs validados na entrada. Cada solicitação gera um protocolo único. Identidade em formato inválido é rejeitada na porta; identidade bem formada mas não encontrada na base retorna negativa explícita, que no fluxo aciona o encaminhamento para atendimento humano — em vez de travar a conversa.

A imagem do backend é multi-stage, com runtime enxuto, usuário não-root e healthcheck. O ambiente sobe por composição com a camada de orquestração e um proxy reverso com HTTPS automático.

O que fica de fora, de propósito

A integração real com um ERP específico não faz parte da demo. Essa é sempre a parte única de cada projeto e depende inteiramente do sistema do cliente. O que a demo prova é a parte reutilizável: a arquitetura de orquestração e a fronteira de segurança entre a conversa e a execução.

Stack

WhatsApp Cloud API · n8n (self-hosted) · NestJS · TypeScript · PostgreSQL · Docker · Caddy