Pular para o conteúdo

Atendimento API

Empresas no mesmo banco,
sem ver os dados umas das outras

Uma API REST de atendimento por WhatsApp para várias empresas. Fiz sozinho, em julho de 2026, e registrei as decisões de arquitetura em 18 ADRs.

Papel
Arquitetura, backend, testes e deploy
Autoria
Teste técnico, feito sozinho
Período
Julho de 2026
Stack
  • Java 25
  • Spring Boot 4
  • PostgreSQL 17
  • Flyway
  • GitHub Actions
  • Dokploy

Contexto

Uma empresa usa a API para atender clientes pelo WhatsApp: contatos, conversas e mensagens. Várias empresas dividem o mesmo banco, e os dados de uma nunca podem aparecer para outra. Tratei isso como a regra de negócio mais crítica, e ela virou o primeiro ADR.

Restrições

  • O prazo era curto, e isso pesou em três decisões (ADR-0003, 0009 e 0016).
  • Não fiz frontend: a entrega era a API e a documentação (ADR-0015).
  • Testei o webhook só com payloads e assinaturas HMAC locais, sem mensagens reais da Meta (ADR-0009).

Autoria

O que foi meu
Fiz tudo: modelagem, isolamento com RLS, autenticação, webhook, testes, CI/CD e deploy, em 181 commits.
O que foi do time
Não teve time. Trabalhei sozinho.

Decisões

Separei oito das 18 decisões, na ordem dos ADRs.

Banco único com RLSADR-0001

Escolhi banco compartilhado para simplificar a operação, com RLS como garantia de isolamento entre empresas. Testei essa separação com dois tenants no PostgreSQL real via Testcontainers.

Ler ADR-0001
Empresa vem do token assinadoADR-0002

Coloquei a empresa ativa no JWT assinado para usar uma única fonte de contexto nas operações autenticadas do tenant. A troca de empresa valida o vínculo e emite outro token; o webhook resolve a empresa pelo phone_number_id.

Ler ADR-0002
Pacotes uniformes com entidades ricasADR-0003

Organizei os pacotes por funcionalidade e mantive regras nas entidades JPA para evitar camadas duplicadas no prazo do teste técnico.

Ler ADR-0003
O webhook nunca reabre uma conversaADR-0005

Criei uma nova conversa vinculada à anterior para preservar o encerramento feito pelo atendente sem perder a continuidade do histórico.

Ler ADR-0005
WhatsApp Cloud API oficialADR-0009

Escolhi a API oficial para reduzir riscos operacionais e implementei o recebimento do webhook com HMAC, testado só com payloads e assinaturas locais, sem mensagens reais da Meta. O envio pela Graph API ficou fora para priorizar isolamento e testes no prazo do teste técnico.

Ler ADR-0009
Uma conta, várias empresasADR-0010

Usei uma conta global para manter e-mail único e uma senha, com perfil e status no vínculo de cada empresa. Trocar de empresa reemite o token sem pedir a senha de novo.

Ler ADR-0010
Remoção do OutboxADR-0011

Retirei o outbox do desenho porque a mensagem já fica persistida e perder um aviso de tela não justificava manter tabela e worker. O aviso após commit que o substituiria ainda não foi implementado.

Ler ADR-0011
Só a plataforma cria empresasADR-0013

Restringi a criação de empresas à plataforma para manter o cadastro de clientes sob controle do operador. Consultar e editar dependem do recurso, e o administrador de uma empresa só mexe na dela.

Ler ADR-0013
Ver as 18 decisões

Arquitetura

As duas entradas chegam à mesma API, que fixa a empresa na transação; com RLS, o banco só devolve as linhas dessa empresa.

Como dá para ver funcionando

Não tem tela. Dá para ver o isolamento no banco: abaixo, a política de RLS e a mesma consulta feita como empresas diferentes.

V3__policy_rls_tenant_segura.sqlSQL
CREATE POLICY tenant_isolation ON conversa
  USING (empresa_id =
    NULLIF(current_setting('app.tenant_id', true), '')::uuid)
  WITH CHECK (empresa_id =
    NULLIF(current_setting('app.tenant_id', true), '')::uuid);

ALTER TABLE conversa FORCE ROW LEVEL SECURITY;

SELECT * FROM conversas;

Empresa fixada na transação
Empresa A na transação3 conversas
ContatoÚltimo assuntoEmpresa
Marina Costa
Segunda via de boleto
A
Bruno Alves
Alteração de endereço
A
Carla Mendes
Confirmação de pagamento
A

Simulação no navegador com conversas fictícias.

Na requisição autenticada, a empresa vem do tenant_id do JWT. No webhook, vem do phone_number_id do payload, depois da checagem do HMAC.

Cerca de 30 endpoints, por grupo

auth
login, troca de empresa, troca de senha
empresas
cadastro pela plataforma, desativação
usuarios
vínculos com empresas
contatos
por empresa
conversas
listar, encerrar, reabrir
mensagens
histórico da conversa
webhooks
POST /webhooks/messages, com HMAC

Ainda não implementado

  • Envio de mensagens pela Graph API.
  • Eventos em tempo real por SSE (ADR-0007 adiado).
  • Limite de requisições.

Resultado

ResultadoAinda não medido

Ainda não tenho número de uso real. O que já dá para conferir:

  • 49 testes passando em 11 segundos, rodados em 21/07/2026.
  • CI com testes, Spotless e Checkstyle em cada push.
  • Imagem publicada no GHCR e deploy em homologação e produção pelo Dokploy.

Próximo case

OPA, Orçamento Participativo do Piauí

Um portal do Estado com um frontend que o time mantém

Ler o case