Família FlowPost

FlowZap: arquitetura de uma plataforma multi-tenant de WhatsApp

O FlowZap é uma plataforma brasileira de integração não oficial com o WhatsApp, desenvolvida e operada pela S82. Várias pessoas de uma empresa atendem pelo mesmo número, por console ou API. A arquitetura combina API de controle em TypeScript, motor Go/Whatsmeow com lease e fencing por sessão, Postgres com RLS e envio idempotente.

Integração não oficial com o WhatsApp: o FlowZap não é afiliado nem endossado pela Meta, e o uso depende dos termos do próprio WhatsApp.

O problema

O que o produto resolve

Empresas querem atender clientes no WhatsApp com várias pessoas no mesmo número e integrar o canal aos seus sistemas. Isso exige resolver, ao mesmo tempo, isolamento entre clientes, exclusividade de cada sessão do WhatsApp, envio sem duplicidade e uma interface que leigos consigam operar. O desafio de engenharia é entregar isso com segurança de dados e comportamento previsível quando algo falha.

O que faz

Capacidades

  • Vários atendentes no mesmo número, com identificação de quem enviou cada mensagem
  • Conectar um número em um fluxo guiado, por QR code, sem apoio técnico
  • API pública versionada para enviar mensagens, receber eventos por webhook e integrar a sistemas próprios
  • Chaves de API para ferramentas como n8n, Make e Chatwoot, e servidor MCP para apps de IA operarem a conta com permissões controladas
  • Conversas com status de entrega e leitura, CRM, campanhas e chaves de API gerenciadas pelo próprio cliente
  • Central interna para operação, suporte e acompanhamento financeiro, separada do console do cliente

Arquitetura

Como o sistema é organizado

Das camadas de uso até os dados e serviços externos.

  1. Usuários e integrações

    • Console do cliente (Vue)
    • Sistemas do cliente via API e webhooks
    • Apps de IA via MCP
    • Ferramentas como n8n, Make e Chatwoot via API
  2. Interfaces

    • Site comercial (Nuxt)
    • Console (Vue 3, Vite, Tailwind)
    • Central interna (Vue)
    • Sistema de design compartilhado
  3. Plano de controle

    • API Express 5 modular
    • Organizações, workspaces e permissões
    • Idempotência, outbox e inbox
    • Adaptador de cobrança (Asaas)
  4. Plano de mensagens

    • Workers Go com Whatsmeow
    • Lease com heartbeat e fencing epoch
    • Operações do motor cifradas e executadas pelo worker dono
    • Interface de provedor substituível
  5. Dados

    • PostgreSQL 16 com RLS
    • Papéis SQL separados por função
    • Armazenamento privado de mídia
  6. Serviços externos

    • WhatsApp (integração não oficial)
    • Gateway de pagamento
    • Endpoints de webhook do cliente

Decisões

Escolhas técnicas e seus trade-offs

Dono único por sessão, com lease e fencing

Por quê: Cada sessão do WhatsApp só pode ter um processo ativo. O worker obtém lease com heartbeat no banco e carrega um epoch em todo comando; perder o lease interrompe os envios e fecha o socket.

Trade-off: Sob partição de rede, o lease expirado não prova que o worker antigo parou. Por isso a transferência exige confirmação de shutdown, e o sistema prefere ficar indisponível a arriscar duas conexões.

Envio idempotente que admite incerteza

Por quê: O aceite grava comando e outbox na mesma transação e só então responde, com chave de idempotência por operação. Quando o resultado é ambíguo, a mensagem vai para um estado explícito de reconciliação, nunca para reenvio cego.

Trade-off: Idempotência no aceite não equivale a exactly-once na rede do WhatsApp. O custo é tratar o estado incerto e, em alguns casos, pedir confirmação humana.

Monólito modular no controle, Go só no protocolo

Por quê: TypeScript no plano de controle reduz custo operacional e mantém transações simples. Go entra apenas onde a biblioteca de protocolo é nativa, atrás de uma interface de provedor que isola o resto do sistema do motor.

Trade-off: Dois toolchains e um contrato interno para manter. A versão do Whatsmeow é fixada por commit, com validação antes de atualizar.

Isolamento por organização no banco

Por quê: RLS e papéis SQL separados protegem os dados no próprio banco. Cada consulta carrega a organização e o banco recusa linhas de outros clientes, mesmo diante de um erro na aplicação.

Trade-off: Políticas de RLS exigem disciplina em toda migração e em todo papel novo, e o teste de isolamento precisa acompanhar cada tabela.

Sem IA na cadeia crítica

Por quê: Envio de mensagens e cobrança não dependem de modelo de linguagem. A IA entra como interface opcional, via servidor MCP, sob as mesmas permissões e regras da API.

Trade-off: O produto não automatiza respostas por conta própria; a automação é decisão do cliente e das ferramentas que ele conecta.

Desafios resolvidos

Problemas difíceis, soluções concretas

A mesma conversa em dois identificadores

O WhatsApp pode apresentar o mesmo contato por número ou por identificador interno (LID), e números brasileiros circulam com e sem o nono dígito. O resultado eram conversas divididas. A solução usa o recibo cifrado da mensagem enviada como prova para unificar, normaliza o número em uma regra única e separa de forma conservadora quando não há prova.

Estados que não cabem em um campo só

A conexão do número, o recurso de instância, a assinatura e o direito de envio são eixos independentes. Modelá-los separadamente evita mensagens como um número marcado como inadimplente: a interface compõe os eixos e mostra, por exemplo, conectado com envio suspenso por pagamento.

Esconder a engenharia de quem opera

Termos como instância, worker e lease não fazem sentido para o cliente. O console foi remodelado com um nome por destino de menu, conexão do número em um fluxo único e manual embutido, sem alterar o backend nem as garantias de idempotência.

Dados sensíveis de sessão em um sistema compartilhado

O acesso aos dados de sessão do Whatsmeow foi segregado por papéis SQL separados por função, a caixa de entrada é cifrada na aplicação e o acesso às chaves de sessão fica restrito.

Stack

Tecnologia por camada

Plano de controle
TypeScript, Node.js, Express 5, Sequelize
Motor do WhatsApp
Go, Whatsmeow, Docker
Banco de dados
PostgreSQL 16 com RLS e papéis SQL separados
Console e central interna
Vue 3, Vite, Tailwind 4, componentes Reka
Site comercial
Nuxt 4
Contratos e validação
Zod em pacote compartilhado
Cobrança
Adaptador de pagamentos (Asaas), com inbox e reconciliação
Qualidade
ESLint com regras próprias, testes unitários, de banco e de Go, pnpm workspaces

Outros produtos

Família FlowPost

FlowPost

Posts e carrosséis com IA, agendados e publicados sozinhos no LinkedIn e no Instagram.

Plataforma de produção e publicação de conteúdo para LinkedIn e Instagram, criada e operada pela S82. Nasceu de um app Lovable com Supabase e foi reconstruída na stack padrão da S82, com migração real de dados e corte com congelamento curto e reversível.

Família Host Academy

Host Academy

Portal de conteúdo sobre locação por temporada, com um agente de IA que pesquisa, escreve e só publica o que passa nas regras.

Portal de conteúdo sobre locação por temporada que a S82 construiu e opera, no lugar de um site feito em Lovable. Um agente autônomo produz o blog com fontes citadas, e temas tributários e jurídicos esperam aprovação humana antes de ir ao ar.

Família Host Academy

Stays Aval

Análise de anúncios de hospedagem com IA, do link ao relatório.

Plataforma em que o anfitrião cola o link do anúncio e recebe score atual, score potencial, recomendações priorizadas e relatório em tela e PDF. A S82 reconstruiu o produto, antes no Lovable, em arquitetura própria, com migração real dos dados.

Airbnb, Booking.com, Hoteis.com, Expedia e Decolar são marcas de seus respectivos donos. O Stays Aval não é afiliado a elas nem endossado por elas.

Diagnóstico estratégico

Precisa de uma arquitetura assim no seu negócio?

Agendar diagnóstico estratégico