Contratos, partes, recibos e previsão de caixa do sistema de locação
Versões e aditivos juntos no contrato lógico, vigência pelas datas
Ativos no fim do mês, novos, encerrados, churn e taxa de administração
Dashboard da carteira, agente de IA e alertas
O que resolve
- A administração sabe quantos contratos tinha ativos no fim de cada mês, mesmo com o sistema mostrando só a foto de hoje.
- Renovação e aditivo deixam de aparecer como um contrato cancelado e outro novo.
- O churn é calculado sobre a carteira do início do mês e bate com o que a gerência conta.
Perguntas de negócio que responde
Faça estas perguntas ao seu agente quando o caso estiver pronto.
O que você precisa
- O sistema de locação conectado na Nekt (ou o espelho mensal exportado dele)
- A regra de contrato ativo, aviso e encerrado combinada com a administração
- O código do imóvel do contrato ligado ao CRM de imóveis
O que você recebe
- Uma tabela por contrato com status, datas, partes, aluguel e taxa
- Uma série mensal com ativos, novos, encerrados, churn e taxa de administração
- Dashboard da carteira com evolução de 12 meses
- Um agente de IA que responde sobre a carteira com a regra certa
Onde ativar
Evolução de 12 meses de ativos, novos, encerrados, churn, VGL e taxa de administração, com comparação com o ano anterior.
Responde quantos contratos estavam ativos, quem saiu e por quê e quem está atrasado, com a regra de contrato lógico já aplicada.
Lista semanal dos contratos que entraram em aviso de desocupação, que vencem nos próximos 90 dias ou que têm boleto atrasado.
A conta é simples depois que o contrato lógico existe. O trabalho está em juntar as versões de cada contrato e em tratar datas e valores que chegam como texto. O detalhado traz as regras de negócio, as armadilhas e o teste de aceitação. Ou mande tudo direto para o seu agente com o MCP da Nekt.
O sistema de locação mostra os contratos como estão hoje e cria uma versão nova a cada renovação ou aditivo. Quem conta contratos pelo status atual não tem histórico, e quem conta versões vê um cancelamento e um contrato novo a cada renovação. Datas chegam como texto dd/mm/aaaa, valores com vírgula e as partes do contrato em listas, e o churn sai diferente em cada planilha.
Como costuma ser feito, e a regra
Cada linha é um erro que já aconteceu na prática.
Renovação e aditivo criam uma versão nova do contrato, com o código interno acrescido de um sufixo (por exemplo, 1234-1). O contrato lógico é o código antes do hífen. Ele está ativo se alguma versão está ativa e não excluída; o início é a menor data de contrato entre as versões; o fim efetivo é a maior data de exclusão quando nenhuma versão está ativa. Os atributos (aluguel, partes, taxa) vêm da versão atual: a ativa e, entre as ativas, a de data mais recente.
Agrupe o status do sistema em ativo, em aviso de desocupação e desativado. Em aviso continua ativo na contagem, com uma marca própria, até a saída. O motivo da saída vem do próprio status ou do campo de motivo de exclusão (rescisão, venda do imóvel, troca de administradora).
Ativo num dia = início menor ou igual ao dia e fim efetivo nulo ou maior que o dia. Gere uma série de dias ou de meses (por exemplo, os últimos 5 anos) e conte os contratos ativos no último dia de cada mês. Novos do mês pela data de início, encerrados pela data de fim efetivo. Quando o sistema não tem datas confiáveis, grave um espelho mensal da carteira desde já.
Churn do mês = contratos encerrados no mês / contratos ativos no fim do mês anterior. Contratos novos do mês ficam fora do denominador. Crescimento do mês = (novos menos encerrados) / ativos no início. Compare com o mesmo mês do ano anterior para tirar a sazonalidade de fim de ano e de volta às aulas.
Para conferir a carteira, use os recibos: contrato ativo no mês tem recibo de aluguel previsto no mês com valor maior que zero (no Msys, o evento de aluguel nos recebimentos). Fique com o último recibo de cada contrato. Contrato ativo sem recibo, ou recibo de contrato encerrado, vai para revisão.
Taxa de administração mensal = aluguel x percentual de administração do contrato. Taxa de contrato (intermediação na assinatura) é receita pontual e fica separada. Aluguel sob gestão (VGL) = soma do aluguel dos contratos ativos no fim do mês. Aluguel médio = VGL / contratos ativos.
Um contrato pode ter vários locadores, locatários e fiadores, cada um com uma ordem. O principal é o de ordem 1; guarde todos num array e a quantidade. Quando o contrato vem sem as partes na raiz, pegue o primeiro locatário e o primeiro proprietário das listas do contrato. Ligue as pessoas à base única pelo documento.
Atrasado = boleto não pago com vencimento antes de hoje. Para o caixa previsto, use uma janela de 30 dias para trás e 90 para frente: valor total, pago, em aberto e atrasado por contrato. Locatário inadimplente é quem tem pelo menos um boleto atrasado.
Datas chegam como dd/mm/aaaa, às vezes vazias, '-' ou 'null'; valores com vírgula decimal. Converta na primeira camada: texto com menos de 8 caracteres vira nulo, vírgula vira ponto, e o resultado é tipado. Nunca compare datas como texto.
Carência de multa de saída, índice e data do próximo reajuste e tipo de garantia locatícia vêm do contrato. Regras internas, como isentar a multa depois de 12 meses, ficam numa constante com nome e comentário dizendo que são política da imobiliária, não lei.
Como cada contrato é lido
Pelo contrato lógico (todas as versões), no último dia do mês.
Definições
Armadilhas que já aconteceram
Cada aditivo criava uma versão nova, e a carteira mostrava um cancelamento e um contrato novo a cada renovação.
Agrupe as versões pelo código base antes de contar.
O sistema de locação só entregava a foto atual, e a série histórica não existia para os meses anteriores.
Reconstrua pela vigência dos contratos e grave um espelho mensal desde já.
A tabela de contratos não trazia locatário e proprietário, e era impossível saber quem alugava e quem era dono.
Leia o primeiro locatário e o primeiro proprietário das listas do contrato.
O cruzamento com locadores e fiadores repetiu o contrato uma vez por pessoa e o VGL dobrou.
Agregue as partes em arrays antes de juntar ao contrato.
Datas no formato dd/mm/aaaa vindas de planilha foram filtradas como texto e meses inteiros sumiram do intervalo.
Converta para data na entrada.
A consulta de contratos ativos tinha o mês escrito no filtro e ficou parada naquele mês enquanto o painel avançava.
Use a série de meses, nunca um mês fixo no código.
Teste de aceitação
O caso está pronto quando todos os itens passam.
- Os contratos ativos no fim do último mês fechado batem com o relatório de contratos ativos do sistema de locação (diferença abaixo de 1%).
- Para cada mês, ativos no fim do mês anterior + novos - encerrados = ativos no fim do mês.
- Nenhum código base aparece mais de uma vez na tabela de contratos.
- O VGL do mês é igual à soma do aluguel dos contratos ativos, sem duplicação por locador ou fiador.
- Para três contratos renovados escolhidos, não há encerramento registrado na data da renovação.
Pacote para o agente
Cole no Claude, ChatGPT ou outro cliente com o MCP da Nekt conectado.
Carteira de locação - Contrato = contrato lógico: todas as versões e aditivos do mesmo código base (antes do hífen). Nunca conte versões. - Ativo: alguma versão ativa e não excluída. Em aviso de desocupação conta como ativo, com marca própria. - Ativos no mês: contados no último dia do mês, pela vigência (início até o dia e fim efetivo nulo ou depois). - Novos pela data de início; encerrados pela data de fim efetivo. Renovação não é encerramento. - Churn mensal = encerrados no mês / ativos no fim do mês anterior. Novos ficam fora do denominador. - VGL = soma do aluguel dos ativos no fim do mês. Aluguel médio = VGL / ativos. - Taxa de administração = aluguel x percentual do contrato; taxa de contrato (intermediação) é pontual e fica separada. - Inadimplente: boleto não pago com vencimento antes de hoje. - Locador, locatário e fiador principais são os de ordem 1; os demais estão nos arrays. - Taxa com denominador zero retorna nulo. Exceções por cliente: - <cliente>: carência de multa de saída de <meses> meses, regra interna da imobiliária. - <cliente>: a carteira vem do espelho mensal <fonte> antes de <data> e da vigência dos contratos depois.
Construa no meu workspace Nekt o caso "Carteira de locação" seguindo as regras em https://academy.nekt.com/industrias/imobiliario/carteira-de-locacao.md. 1) Encontre as tabelas de origem e confirme as colunas usadas pelas regras. 2) Crie uma transformação no grão indicado aplicando todas as regras. 3) Rode o teste de aceitação e me mostre o resultado de cada item. 4) Crie o context document do caso no workspace, com as exceções dos meus clientes em aberto para eu preencher.
Variações
Contratos agrupados pelo mês de início, acompanhando quantos seguem ativos após 6, 12 e 24 meses.
Para imóveis de temporada, a carteira é de imóveis ativos e o indicador central é o repasse ao proprietário: em dia, atrasado ou faltante pela diferença entre competência e caixa.
Contratos encerrados alimentam o segmento de ex-locatários para campanhas de primeiro imóvel e de nova locação.