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 RLS
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-0001Empresa vem do token assinado
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-0002Pacotes uniformes com entidades ricas
Organizei os pacotes por funcionalidade e mantive regras nas entidades JPA para evitar camadas duplicadas no prazo do teste técnico.
Ler ADR-0003O webhook nunca reabre uma conversa
Criei uma nova conversa vinculada à anterior para preservar o encerramento feito pelo atendente sem perder a continuidade do histórico.
Ler ADR-0005WhatsApp Cloud API oficial
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-0009Uma conta, várias empresas
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-0010Remoção do Outbox
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-0011Só a plataforma cria empresas
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-0013Arquitetura
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.
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;GET /conversas HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9…
X-Tenant-ID: B ignorado pela APIPayload do tokenHS256assinatura válida
{
"sub": "usuario-42",
"tenant_id": "A", "exp": 1759276800
}A API usa a empresa que está no token e ignora o header.
POST /auth/switch-tenant
Authorization: Bearer token da empresa A
{ "empresaId": "b7e2…" }200 OKsem pedir a senha de novo
{
"accessToken": "eyJhbGciOiJIUzI1NiJ9…"
}O novo token carrega "tenant_id": "B"
POST /empresas
Authorization: Bearer token de administrador
{ "nome": "Empresa C" }403 ForbiddenAdministrador da empresa
{
"title": "Forbidden",
"status": 403
}application/problem+json
201 CreatedAdministrador da plataforma
{
"id": "c03d…",
"nome": "Empresa C"
}cria a empresa e um admin com senha temporária
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.