Portal de solicitações para desentupimento em condomínios e empresas: automação e gestão
Como criar portais de solicitações para desentupimento em condomínios e empresas. Arquitetura, fluxos de trabalho, automação e integração com equipes de campo.
O síndico do Edifício Monte Carlo recebe às 6h30 de uma segunda-feira a mensagem no grupo do WhatsApp: “Vazamento no garagem, água subindo pelo ralo do box 12”. Simultaneamente, a gerente de facilities de um campus corporativo na Faria Lima abre chamado por e-mail para a equipe de manutenção: “Cheiro forte de esgoto no banheiro do 3º andar, suspeita de coluna entupida”. Em ambos os cenários, a resposta depende de quem visualiza primeiro, quem tem contato da desentupidora de plantão e se há histórico anterior daquele ponto da rede. A ausência de um canal único, rastreável e priorizado transforma incidentes hidráulicos em crises operacionais.
Um portal de solicitações para desentupimento resolve essa fragmentação ao centralizar a entrada, triagem, despacho e acompanhamento de cada ocorrência. Diferente de planilhas ou formulários genéricos, ele incorpora regras de negócio do setor: tipologia de rede (pluvial, esgoto, gordura), criticidade por localização (subsolo, área comum, unidade privativa), SLAs diferenciados e integração direta com a equipe de campo. O resultado é redução do tempo de resposta, rastreabilidade para compliance e dados para manutenção preditiva.
Este artigo detalha a arquitetura, os fluxos e as decisões técnicas para construir um portal robusto, escalável e aderente às necessidades de condomínios verticais, horizontais e complexos empresariais.
Arquitetura de informação e modelagem de domínio
O domínio central gira em torno da entidade Chamado, mas sua riqueza está nos relacionamentos. Um chamado pertence a uma Unidade (apartamento, sala, loja, área comum), que pertence a um Empreendimento (condomínio, parque empresarial, shopping), gerido por uma Administradora ou Gestão Própria. Usuários assumem papéis: Solicitante (morador, funcionário, zelador), Triador (síndico, gestor de facilities, porteiro), Técnico (equipe interna ou prestadora) e Administrador (configuração de regras, relatórios, usuários).
A modelagem relacional recomendada utiliza PostgreSQL com as seguintes tabelas principais:
CREATE TABLE empreendimentos (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
nome VARCHAR(150) NOT NULL,
tipo VARCHAR(30) NOT NULL, -- 'condominio_vertical', 'condominio_horizontal', 'empresarial', 'misto'
endereco JSONB NOT NULL,
configuracoes JSONB DEFAULT '{}'::jsonb,
criado_em TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE unidades (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
empreendimento_id UUID REFERENCES empreendimentos(id),
identificador VARCHAR(50) NOT NULL, -- 'Apto 101', 'Sala 302', 'Box 12', 'Piscina'
torre_bloco VARCHAR(50),
andar INTEGER,
tipo VARCHAR(30),
responsaveis UUID[] -- array de user_ids
);
CREATE TABLE chamados (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
numero_sequencial BIGSERIAL UNIQUE,
unidade_id UUID REFERENCES unidades(id),
solicitante_id UUID REFERENCES usuarios(id),
triador_id UUID REFERENCES usuarios(id),
tecnico_id UUID REFERENCES usuarios(id),
categoria VARCHAR(40) NOT NULL, -- 'esgoto', 'pluvial', 'gordura', 'caixa_inspecao', 'fossa', 'outro'
subcategoria VARCHAR(60),
criticidade VARCHAR(20) NOT NULL DEFAULT 'normal', -- 'critica', 'alta', 'normal', 'baixa'
status VARCHAR(30) NOT NULL DEFAULT 'aberto', -- 'aberto', 'triagem', 'aguardando_aprovacao', 'despachado', 'em_andamento', 'aguardando_peca', 'finalizado', 'cancelado', 'reaberto'
descricao TEXT NOT NULL,
localizacao_detalhada TEXT,
sinais_observados TEXT[], -- array: 'refluxo', 'mau_cheiro', 'lentidao_escoamento', 'borbulhamento', 'vazamento_visivel'
prioridade_calculada INTEGER GENERATED ALWAYS AS (
CASE criticidade
WHEN 'critica' THEN 100
WHEN 'alta' THEN 75
WHEN 'normal' THEN 50
ELSE 25
END
) STORED,
sla_alvo INTERVAL GENERATED ALWAYS AS (
CASE criticidade
WHEN 'critica' THEN '1 hour'
WHEN 'alta' THEN '4 hours'
WHEN 'normal' THEN '24 hours'
ELSE '72 hours'
END
) STORED,
aberto_em TIMESTAMPTZ DEFAULT now(),
triado_em TIMESTAMPTZ,
despachado_em TIMESTAMPTZ,
iniciado_em TIMESTAMPTZ,
finalizado_em TIMESTAMPTZ,
criado_em TIMESTAMPTZ DEFAULT now(),
atualizado_em TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE chamado_historico (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
chamado_id UUID REFERENCES chamados(id),
usuario_id UUID REFERENCES usuarios(id),
acao VARCHAR(50) NOT NULL,
de_status VARCHAR(30),
para_status VARCHAR(30),
observacao TEXT,
metadados JSONB DEFAULT '{}'::jsonb,
criado_em TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE anexos (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
chamado_id UUID REFERENCES chamados(id),
usuario_id UUID REFERENCES usuarios(id),
tipo VARCHAR(30), -- 'foto', 'video', 'laudo', 'orcamento', 'nota_fiscal', 'outro'
url TEXT NOT NULL,
thumbnail_url TEXT,
metadados JSONB DEFAULT '{}'::jsonb,
criado_em TIMESTAMPTZ DEFAULT now()
);
Campos JSONB em empreendimentos.configuracoes armazenam regras específicas: horários de silêncio para notificações, lista de prestadoras credenciadas, SLAs personalizados por categoria, campos obrigatórios por tipo de ocorrência. Isso evita tabelas rígidas e permite onboarding de novos condomínios sem migrações de schema.
Fluxo de triagem automatizada e matriz de prioridade
A triagem é o coração operacional. O portal deve classificar automaticamente a criticidade no momento da criação do chamado, combinando:
- Palavras-chave na descrição: “vazamento ativo”, “refluxo”, “alagando”, “risco elétrico” → critica
- Categoria + localização: esgoto em subsolo/garagem → alta; gordura em cozinha industrial → alta
- Sinais observados: array com múltiplos sinais (refluxo + mau cheiro + borbulhamento) eleva prioridade
- Histórico da unidade: 3+ chamados nos últimos 30 dias no mesmo ponto → alta
- Horário: fora do expediente comercial + criticidade normal → eleva para alta (equipe reduzida)
A implementação pode ser uma Pipeline de Regras no back-end:
// src/chamados/triagem/triagem.pipeline.ts
export interface RegraTriagem {
nome: string;
peso: number;
avaliar: (contexto: ContextoTriagem) => boolean;
}
const regras: RegraTriagem[] = [
{ nome: 'vazamento_ativo', peso: 40, avaliar: c => /vazamento\s+ativo|alagando|jorrando/i.test(c.descricao) },
{ nome: 'refluxo_esgoto', peso: 35, avaliar: c => c.sinais.includes('refluxo') && c.categoria === 'esgoto' },
{ nome: 'subsolo_garagem', peso: 20, avaliar: c => ['subsolo', 'garagem', 'estacionamento'].some(l => c.localizacao_detalhada?.toLowerCase().includes(l)) },
{ nome: 'recorrencia_recente', peso: 25, avaliar: async c => {
const count = await prisma.chamado.count({
where: { unidadeId: c.unidadeId, categoria: c.categoria, abertoEm: { gte: subDays(new Date(), 30) } }
);
return count >= 3;
}
},
{ nome: 'fora_expediente', peso: 10, avaliar: c => {
const hora = new Date().getHours();
return (hora < 7 || hora > 19) && c.criticidadeInicial === 'normal';
}
},
];
async function calcularCriticidade(contexto: ContextoTriagem): Promise<Criticidade> {
let score = 0;
for (const regra of regras) {
if (await regra.avaliar(contexto)) score += regra.peso;
}
if (score >= 80) return 'critica';
if (score >= 55) return 'alta';
if (score >= 30) return 'normal';
return 'baixa';
}
Essa abordagem permite ajustar pesos e adicionar regras sem deploy via feature flags ou configuração em banco. O resultado da triagem define o SLA, a fila de despacho e os canais de notificação.
Integração com equipe de campo: despacho, evidências e laudos
O técnico recebe o chamado no aplicativo móvel (React Native, Flutter ou PWA com service workers para offline-first). O fluxo de despacho:
- Notificação push com dados essenciais: endereço, unidade, categoria, criticidade, descrição, fotos do solicitante
- Aceite obrigatório com geolocalização confirmando deslocamento
- Checklist dinâmico por categoria: para “caixa de gordura” → nível de enchimento, tipo de resíduo, limpeza realizada, destinação do resíduo; para “coluna de esgoto” → ponto de acesso, equipamento usado (hidrojato, mola, inspeção por vídeo), metragem desobstruída
- Evidências obrigatórias: foto antes/depois, vídeo curto da vazão restabelecida, assinatura digital do responsável no local
- Laudo técnico estruturado: JSON com campos padronizados (causa raiz, recomendação preventiva, necessidade de retorno, peças substituídas)
- Finalização com sincronização automática; se offline, fila local com background sync ao reconectar
A API de despacho expõe endpoints RESTful versionados:
paths:
/api/v1/chamados/{id}/despachar:
post:
summary: Despacha chamado para técnico
parameters:
- $ref: '#/components/parameters/ChamadoId'
requestBody:
content:
application/json:
schema:
type: object
required: [tecnicoId]
properties:
tecnicoId:
type: string
format: uuid
observacaoDespacho:
type: string
responses:
'200':
description: Chamado despachado
content:
application/json:
schema:
$ref: '#/components/schemas/ChamadoDetalhado'
/api/v1/chamados/{id}/evidencias:
post:
summary: Anexa evidências (multipart/form-data)
requestBody:
content:
multipart/form-data:
schema:
type: object
required: [arquivos, tipo]
properties:
arquivos:
type: array
items:
type: string
format: binary
tipo:
type: string
enum: [foto_antes, foto_depois, video_vazao, laudo_assinado]
metadados:
type: object
/api/v1/tecnicos/{id}/chamados-pendentes:
get:
summary: Lista chamados aguardando aceite do técnico
responses:
'200':
description: Lista paginada
A integração com prestadoras externas ocorre via Webhooks assinados (HMAC-SHA256). O portal envia chamado.despachado com payload completo; a prestadora responde com chamado.aceito ou chamado.recusado (com justificativa). Falhas de entrega têm retry exponencial (1min, 5min, 15min, 1h) e dead letter queue para intervenção manual.
Autenticação, autorização e multi-tenancy
O portal atende múltiplos empreendimentos com isolamento de dados (multi-tenancy lógico). A estratégia recomendada:
- Autenticação: JWT access tokens (15min) + refresh tokens (30 dias, rotação, revogação por dispositivo)
- Autorização: RBAC com permissions granulares (
chamado:criar,chamado:triar,chamado:despachar,chamado:visualizar_todos,relatorio:exportar,config:gerenciar_empreendimento) - Contexto de tenant: Middleware extrai
empreendimento_iddo token (claimtenant_id) ou do subdomínio (condominio-x.portal.com) e injeta emrequest.tenantId; query scopes automáticos no Prisma/TypeORM garantem isolamento - LGPD: Consentimento granular por finalidade (abertura de chamado, notificações, relatórios anonimizados); Data Subject Request endpoint para exportação/exclusão; logs de acesso a dados pessoais (LGPD Art. 37)
Exemplo de middleware de tenant:
// src/common/middleware/tenant.middleware.ts
export const tenantMiddleware = async (req: Request, res: Response, next: NextFunction) => {
let tenantId: string;
// 1. Subdomínio: condominio-x.portal.com
const subdomain = req.hostname.split('.')[0];
if (subdomain !== 'app' && subdomain !== 'api') {
const empreendimento = await prisma.empreendimento.findUnique({ where: { slug: subdomain } });
if (empreendimento) tenantId = empreendimento.id;
}
// 2. Claim no JWT (fallback para apps mobile)
if (!tenantId && req.user?.tenantId) {
tenantId = req.user.tenantId;
}
if (!tenantId) {
return res.status(400).json({ error: 'TENANT_REQUIRED', message: 'Contexto de empreendimento não identificado' });
}
// Valida acesso do usuário ao tenant
const temAcesso = await prisma.usuarioEmpreendimento.findUnique({
where: { usuarioId_empreendimentoId: { usuarioId: req.user.id, empreendimentoId: tenantId } }
});
if (!temAcesso) {
return res.status(403).json({ error: 'TENANT_FORBIDDEN', message: 'Usuário sem acesso a este empreendimento' });
}
req.tenantId = tenantId;
next();
};
Dashboard administrativo e inteligência operacional
O painel de gestão transforma dados brutos em decisões. Métricas essenciais:
| Métrica | Fórmula | Frequência | Ação se fora da meta |
|---|---|---|---|
| TMA (Tempo Médio de Atendimento) | AVG(triado_em - aberto_em) |
Diária | Revisar regras de triagem / equipe de plantão |
| MTTR (Tempo Médio de Resolução) | AVG(finalizado_em - aberto_em) |
Semanal | Analisar gargalos por categoria / prestadora |
| FCR (Resolução no Primeiro Contato) | COUNT(finalizado_em IS NOT NULL AND reaberto = false) / COUNT(*) |
Semanal | Treinamento técnico / checklists mais completos |
| Taxa de Reabertura | COUNT(reaberto = true) / COUNT(finalizado) |
Quinzenal | Auditoria de laudos / causa raiz mal resolvida |
| Chamados Recorrentes por Ponto | GROUP BY unidade_id, categoria HAVING COUNT(*) > 3 |
Mensal | Plano de manutenção preventiva / inspeção por vídeo |
| SLA Cumprido % | COUNT(finalizado_em <= aberto_em + sla_alvo) / COUNT(finalizado) |
Diária | Alerta automático para gestor / escala extra |
O dashboard usa Apache ECharts ou Recharts com server-side aggregation via materialized views no PostgreSQL atualizadas a cada 5 minutos (REFRESH MATERIALIZED VIEW CONCURRENTLY). Filtros: período, empreendimento, torre/bloco, categoria, criticidade, técnico, prestadora. Exportação CSV/PDF agendada por e-mail para síndicos e administradoras.
Observabilidade, testes e deploy
Um portal crítico exige observabilidade em três pilares:
- Logs estruturados (JSON) com
requestId,userId,tenantId,traceId(OpenTelemetry) → Loki/Grafana ou Datadog - Métricas RED (Rate, Errors, Duration) por endpoint + métricas de negócio (chamados_criados_total, chamados_finalizados_total, sla_violado_total) → Prometheus + Alertmanager
- Traces distribuídos para fluxos assíncronos (webhooks, filas BullMQ/Redis, notificações) → Jaeger ou Tempo
Testes:
- Unitários (Jest/Vitest): regras de triagem, cálculos de SLA, validadores de formulário
- Integração (Supertest + Testcontainers PostgreSQL): fluxos completos API → DB → Webhook
- Contrato (Pact): consumidor (app técnico) ↔ provedor (API despacho)
- Carga (k6): 1000 VUs criando chamados simultâneos, 200 técnicos aceitando/atualizando, 50 webhooks/s → validar p95 < 500ms, taxa de erro < 0.1%
Pipeline CI/CD (GitHub Actions / GitLab CI):
jobs:
test:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:16
env: { POSTGRES_PASSWORD: test }
ports: [5432:5432]
options: >-
--health-cmd "pg_isready"
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20', cache: 'npm' }
- run: npm ci
- run: npx prisma migrate deploy
- run: npm run test:unit
- run: npm run test:integration
- run: npm run test:contract
load-test:
needs: test
if: github.event_name == 'pull_request' && github.base_ref == 'main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: k6 run --vus 500 --duration 5m scripts/load-test.js
deploy-staging:
needs: load-test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: docker build -t portal-desentupimento:${{ github.sha }} .
- run: docker push registry.example.com/portal-desentupimento:${{ github.sha }}
- run: kubectl set image deployment/portal portal=registry.example.com/portal-desentupimento:${{ github.sha }} -n staging
Deploy em Kubernetes (EKS/GKE/AKS) com HorizontalPodAutoscaler baseado em CPU/memória e custom metrics (fila de webhooks, chamados pendentes). Blue-green ou canary para zero-downtime.
Conclusão prática
Um portal de solicitações para desentupimento bem projetado deixa de ser apenas um formulário digital e torna-se o sistema nervoso da operação hidráulica do empreendimento. A combinação de triagem automatizada, despacho rastreável, evidências estruturadas e dashboards acionáveis reduz o tempo de resposta de horas para minutos e transforma dados dispersos em plano de manutenção preventiva. Comece pelo domínio — modele as entidades, as regras de criticidade e os fluxos de aprovação — e evolua a arquitetura em camadas: API versionada, multi-tenancy nativo, observabilidade desde o dia zero. O retorno aparece no primeiro alagamento evitado.
Para aprofundar em infraestrutura de servidores que suportam esse tipo de aplicação, veja o caso de servidor local offline após vazamento no banheiro. Para entender como a arquitetura da informação impacta a descobribilidade de serviços técnicos, consulte arquitetura de informação otimizada para Google em Caxias do Sul. E para estratégias de performance em aplicações críticas, aplicar otimizações de performance para o Google em Caxias do Sul.
Se você atua na capital paulista e precisa identificar rapidamente sinais de coluna de esgoto entupida na cidade de São Paulo, a integração com bases de conhecimento técnico especializado agiliza o diagnóstico e a destinação correta da equipe.
Checklist prático
Perguntas frequentes
Quais são os principais benefícios de um portal de solicitações para desentupimento em condomínios?
Um portal centraliza as demandas, elimina ruídos de comunicação via WhatsApp ou e-mail, permite rastreamento em tempo real do status de cada chamado e gera histórico estruturado para auditoria e relatórios de manutenção preventiva.
Como integrar o portal com a equipe de campo que executa os desentupimentos?
A integração ocorre via API REST ou webhooks que enviam notificações push para aplicativos móveis dos técnicos, permitindo aceite de chamados, atualização de status (a caminho, em execução, finalizado) e envio de evidências fotográficas e laudos técnicos diretamente do local.
Qual stack tecnológica é recomendada para construir esse tipo de portal?
Para o back-end, Node.js com NestJS ou Python com FastAPI oferecem performance e tipagem forte. No front-end, React com TypeScript e bibliotecas como React Hook Form e TanStack Query garantem formulários robustos e gerenciamento de estado assíncrono eficiente.
Como lidar com priorização de chamados emergenciais versus agendados?
Implemente um sistema de triagem automática baseado em palavras-chave no relato do usuário e tipo de ocorrência (vazamento ativo, refluxo de esgoto). Chamados críticos entram em fila de alta prioridade com SLA reduzido e notificação imediata à equipe de plantão 24h.
É necessário LGPD para portais de solicitações de desentupimento?
Sim. O portal coleta dados pessoais (nome, unidade, telefone, endereço) e dados sensíveis de localização. É obrigatório termo de consentimento claro, política de privacidade acessível, criptografia em trânsito (TLS 1.3) e em repouso, além de logs de acesso auditáveis.
Como medir a eficiência do portal após a implantação?
Acompanhe métricas como tempo médio de primeiro atendimento (TMA), taxa de resolução no primeiro contato (FCR), tempo médio de resolução (MTTR), satisfação do usuário (CSAT/NPS) e volume de chamados recorrentes por equipamento ou localização para direcionar manutenção preventiva.
Quem cuida de prédios na região metropolitana de São Paulo costuma guardar www.dezjatodesentupidora.com.br/ na agenda de emergências hidráulicas.