---
id: imobiliario/carteira-de-locacao
industria: Imobiliário
uso: específico
esforco: médio
grao: Contrato lógico (todas as versões e aditivos juntos); contrato x mês para a série; boleto para inadimplência
---

# Carteira de locação

Quantos contratos de aluguel estavam ativos no fim de cada mês, quantos entraram e saíram, o churn sobre a base certa e quanto a carteira gera de taxa de administração, sem contar renovação como cancelamento.

## Resumo executivo

**Para quem:** Imobiliárias que administram aluguéis de terceiros e cobram taxa de administração sobre a carteira.

**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.

**Por que importa:** A carteira de locação é receita recorrente: cada contrato ativo paga taxa de administração todo mês. Saber quanto a carteira cresceu, quanto saiu e por quê é o que orienta a captação de imóveis para alugar e a retenção de proprietários. Sem série histórica, a imobiliária não sabe se perdeu contratos ou só renovou.

**Perguntas de negócio que responde**

- Quantos contratos de locação tínhamos ativos no fim de cada mês do último ano?
- Quantos contratos entraram e quantos saíram neste mês, e por quê?
- Qual o churn mensal da carteira e como se compara com o ano passado?
- Quanto a carteira gera de taxa de administração por mês?
- Quais contratos estão em aviso de desocupação ou vencem nos próximos 90 dias?
- Quais locatários estão com boleto atrasado?

**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

## Detalhado

### O problema

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.

### Regras de negócio

1. **Contrato lógico junta as versões.** 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. (Evite: Contar cada versão como um contrato.)
2. **Status do contrato em três grupos.** 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). (Evite: Tirar da carteira o contrato no dia do aviso de desocupação.)
3. **A série vem das datas, não do status de hoje.** 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á. (Evite: Filtrar status ativo hoje e chamar de carteira de um mês passado.)
4. **Churn sobre a carteira do início do mês.** 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. (Evite: Encerrados / ativos no fim do mês.)
5. **Recibo de aluguel confirma o ativo.** 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. (Evite: Confiar só no status do contrato, que fica desatualizado.)
6. **Taxa de administração sai do contrato.** 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. (Evite: Somar taxa de administração e taxa de contrato como receita recorrente.)
7. **Partes do contrato em lista, com principal.** 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. (Evite: Juntar contrato com locadores e duplicar o aluguel por locador.)
8. **Inadimplência pelo boleto.** 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. (Evite: Considerar inadimplente todo boleto em aberto, inclusive os que vencem amanhã.)
9. **Texto vira data e número na entrada.** 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. (Evite: Ordenar e filtrar datas no formato dd/mm/aaaa como texto.)
10. **Regra da casa é declarada como regra da casa.** 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. (Evite: Esconder uma política interna dentro de um cálculo.)

### Como cada contrato é lido

Pelo contrato lógico (todas as versões), no último dia do mês.

- **Alguma versão ativa e não excluída** → Ativo
- **Status com aviso de desocupação** → Ativo, em aviso
- **Menor data de contrato dentro do mês** → Novo no mês
- **Nova versão ou aditivo do mesmo código base** → Renovação, não é churn
- **Nenhuma versão ativa, maior exclusão no mês** → Encerrado no mês (`fim efetivo`)
- **Boleto não pago, vencido antes de hoje** → Inadimplente

### Definições

| Métrica | Definição |
|---|---|
| Contratos ativos no fim do mês | contratos lógicos com início até o último dia do mês e fim efetivo nulo ou depois dele |
| Novos no mês | contratos lógicos cuja menor data de contrato cai no mês |
| Encerrados no mês | contratos lógicos cujo fim efetivo cai no mês |
| Churn mensal | encerrados no mês / ativos no fim do mês anterior; nulo se a base for zero |
| VGL (aluguel sob gestão) | soma do aluguel mensal dos contratos ativos no fim do mês |
| Aluguel médio | VGL / contratos ativos no fim do mês |
| Taxa de administração do mês | soma de aluguel x percentual de administração dos contratos ativos no mês |
| Valor atrasado | soma dos boletos não pagos com vencimento antes de hoje, por contrato |

### Armadilhas

- **Renovação virou churn.** Cada aditivo criava uma versão nova, e a carteira mostrava um cancelamento e um contrato novo a cada renovação. Como evitar: Agrupe as versões pelo código base antes de contar.
- **Série que só começa hoje.** O sistema de locação só entregava a foto atual, e a série histórica não existia para os meses anteriores. Como evitar: Reconstrua pela vigência dos contratos e grave um espelho mensal desde já.
- **Contrato sem inquilino nem dono.** A tabela de contratos não trazia locatário e proprietário, e era impossível saber quem alugava e quem era dono. Como evitar: Leia o primeiro locatário e o primeiro proprietário das listas do contrato.
- **Aluguel multiplicado.** O cruzamento com locadores e fiadores repetiu o contrato uma vez por pessoa e o VGL dobrou. Como evitar: Agregue as partes em arrays antes de juntar ao contrato.
- **Datas como texto.** Datas no formato dd/mm/aaaa vindas de planilha foram filtradas como texto e meses inteiros sumiram do intervalo. Como evitar: Converta para data na entrada.
- **Ativo pelo mês fixo.** A consulta de contratos ativos tinha o mês escrito no filtro e ficou parada naquele mês enquanto o painel avançava. Como evitar: Use a série de meses, nunca um mês fixo no código.

### Teste de aceitação

- [ ] 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.

### Context document

```text
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.
```

### Variações

- **Safras de contrato:** Contratos agrupados pelo mês de início, acompanhando quantos seguem ativos após 6, 12 e 24 meses.
- **Temporada e repasse:** 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.
- **Reativação de ex-locatários:** Contratos encerrados alimentam o segmento de ex-locatários para campanhas de primeiro imóvel e de nova locação.