Documentação
Documentação técnica e de negócio da Leila do Leilão. Todas as fontes de dados, cálculos financeiros, algoritmos e regras de negócio em um só lugar.
1. Visão Geral
Leila do Leilão é uma plataforma de inteligência para leilões de imóveis da Caixa Econômica Federal no estado de Minas Gerais. O diferencial é o uso de dados reais de transações ITBI (Imposto de Transmissão de Bens Imóveis) de Belo Horizonte para calcular descontos reais vs. preços de mercado — não preços de anúncio, que são 18-25% maiores que os preços reais de venda.
| Métrica | Valor Atual |
|---|---|
| Imóveis ativos | 1184 |
| Transações ITBI | 497.129 |
| Meses de dados ITBI | 217 (Jan/2008 a Jan/2026) |
| Municípios cobertos | 139 |
| Imóveis com ITBI | 56 (apenas BH — única cidade com dados abertos) |
| Imóveis com data de leilão | 893 (75% do total) |
| Imóveis 100% enriquecidos | 1184 (financiamento, CEP, leiloeiro) |
| Imóveis com tempo de deslocamento | 1184 |
| Fonte primária | venda-imoveis.caixa.gov.br |
2. Fontes de Dados
2.1 Caixa Econômica Federal — CSV
A Caixa disponibiliza um CSV por estado com todos os imóveis à venda. O arquivo é baixado diretamente via HTTP GET, sem necessidade de autenticação. Encoding Latin-1, delimitador ponto-e-vírgula.
| Campo | Origem | Exemplo |
|---|---|---|
| ID do imóvel | Coluna 'N° do imóvel' | 1555531074050 |
| Cidade / Bairro | Colunas 'Cidade' e 'Bairro' | BELO HORIZONTE / SANTO ANTONIO |
| Preço mínimo | Coluna 'Preço' | R$ 371.854,97 |
| Valor de avaliação | Coluna 'Valor de avaliação' | R$ 870.000,00 |
| Tipo do imóvel | Extraído da primeira palavra da 'Descrição' | Apartamento, Casa, Terreno |
| Área (m²) | Extraído da 'Descrição' via regex | 64.00 de área privativa |
| Modalidade | Coluna 'Modalidade de venda' | Venda Direta Online, Leilão SFI |
| Link detalhe | Coluna 'Link de acesso' | URL completa para página de detalhe |
URL: venda-imoveis.caixa.gov.br/listaweb/Lista_imoveis_MG.csv
2.2 Caixa — Página de Detalhe (Scraping)
Cada imóvel possui uma página de detalhe no site da Caixa com informações adicionais não disponíveis no CSV. Usamos Playwright (navegador headless) para acessar essas páginas, com intervalo de 4 segundos entre requisições.
| Campo | Como é extraído |
|---|---|
| Aceita financiamento | Texto 'permite financiamento' na página |
| Aceita FGTS | Menção a 'FGTS' na página |
| Data do leilão | Regex: 'Data do 1º Leilão - DD/MM/YYYY - HHhMM' |
| Data do 2º leilão | Regex: 'Data do 2º Leilão - DD/MM/YYYY' |
| Leiloeiro | Regex: 'Leiloeiro(a): NOME' |
| Edital | Regex: 'Edital: NÚMERO' |
| CEP | Regex: 'CEP: XXXXX-XXX' |
| Matrícula | Regex: 'Matrícula(s): NÚMERO' |
| Responsabilidade condomínio | Texto 'sob responsabilidade' ou '10%' |
Limitação: A Caixa possui proteção anti-bot (Radware CAPTCHA). O scraping funciona com navegador headless real (Playwright + Chromium) mas pode ser bloqueado após muitas requisições seguidas.
2.3 ITBI — Prefeitura de Belo Horizonte
Belo Horizonte é a única grande cidade brasileira que publica dados abertos de transações ITBI com granularidade por bairro e tipo de imóvel. Isso permite calcular o preço real de mercado por m², ao invés de usar preços de anúncio (que são 18-25% maiores).
| Campo | Descrição |
|---|---|
| Bairro | Bairro da transação (ex: SAVASSI, BURITIS) |
| Tipo construtivo | AP=Apartamento, CA=Casa, SL=Sala, GP=Galpão, etc. |
| Valor declarado | Preço real da transação em R$ |
| Área construída | Área construída adquirida em m² |
| Preço/m² | Calculado: valor / área (se área > 20m²) |
| Data quitação | Mês/ano da transação |
Fonte: dados.pbh.gov.br/dataset/itbi-relatorios (API CKAN)
Cobertura: Apenas BH. Contagem, Betim e demais municípios da RMBH não publicam dados ITBI abertos. Verificamos e confirmamos que esses portais não existem.
3. Análise ITBI — Desconto Real vs. Mercado
O cálculo central da plataforma: comparar o preço de leilão com o preço real praticado no bairro, não com o preço de avaliação da Caixa nem com preços de anúncio em portais.
3.1 Cálculo da mediana de R$/m² por bairro
Para cada combinação (bairro + tipo de imóvel), calculamos a mediana do preço/m² usando transações dos últimos 24 meses.
| Filtro | Valor | Motivo |
|---|---|---|
| Mínimo de transações | ≥ 3 | Confiança estatística mínima |
| Área construída mínima | > 20 m² | Excluir vagas de garagem |
| Preço/m² mínimo | R$ 500/m² | Excluir anomalias (doações, permutas) |
| Preço/m² máximo | R$ 30.000/m² | Excluir outliers comerciais |
3.2 Cálculo do desconto real
Para cada imóvel em BH com área privativa conhecida:
valor_mercado_itbi = mediana_preco_m2_bairro × area_privativa
desconto_real = 1 - (preco_leilao / valor_mercado_itbi)Exemplo: Apartamento no Buritis, 60m², preço de leilão R$ 150.000. Mediana ITBI do Buritis para apartamentos = R$ 4.856/m². Valor de mercado = 60 × R$ 4.856 = R$ 291.360. Desconto real = 1 - (150.000 / 291.360) = 48,5%.
Compare com o desconto vs. avaliação da Caixa, que seria baseado no valor de avaliação (geralmente mais próximo do preço de anúncio). O desconto real ITBI é mais confiável.
3.3 Mapeamento de tipos de imóvel
| Tipo Caixa | Tipo ITBI |
|---|---|
| Apartamento | Apartamento (AP) |
| Casa | Casa (CA) |
| Sala / Comercial | Sala (SL) |
| Terreno | Sem comparação (sem área construída) |
| Galpão | Sem comparação |
4. Cálculo de Custos de Aquisição
O custo total de compra de um imóvel em leilão vai muito além do preço de arrematação. Calculamos todos os custos obrigatórios.
4.1 ITBI (Imposto de Transmissão)
| Município | Alíquota |
|---|---|
| Belo Horizonte | 3,0% (base: avaliação × 1,2) |
| Nova Lima | 3,0% |
| Contagem | 2,75% |
| Sabará | 2,5% |
| Betim, Santa Luzia, Rib. Neves, Esmeraldas, Vespasiano, Lagoa Santa, Ibirité, Matozinhos | 2,0% |
| Demais municípios | 2,0% (padrão) |
Particularidade BH: A PBH aplica uma majoração de 20% sobre a base de cálculo do ITBI. Ou seja, se a avaliação é R$ 100.000, a base para o ITBI é R$ 120.000. Isso resulta em ITBI = R$ 120.000 × 3% = R$ 3.600.
4.2 Cartório e Escritura
| Situação | Custo estimado |
|---|---|
| Compra financiada | ~1,1% do valor de compra (apenas registro) |
| Compra à vista | ~3,1% do valor de compra (registro + escritura pública) |
Valores baseados na tabela de emolumentos do TJMG. Valores reais variam conforme a faixa de preço.
4.3 Comissão do Leiloeiro
| Modalidade | Comissão |
|---|---|
| Leilão SFI | 5% do valor de arrematação (pago pelo comprador) |
| Venda Direta | 0% (sem leiloeiro) |
| Venda Online | 0% |
| Licitação Aberta | 0% |
4.4 Outros custos
| Item | Valor padrão | Nota |
|---|---|---|
| Honorários advocatícios | R$ 5.000 (estimativa) | Varia conforme complexidade |
| Condomínio atrasado | Variável | Responsabilidade do comprador (leilão) ou Caixa paga acima de 10% da avaliação (venda direta) |
| IPTU atrasado | Variável | Geralmente responsabilidade do comprador |
| Reforma | Variável | Imóveis vendidos 'no estado' — sem garantia |
5. Simulação de Financiamento (SAC)
O sistema SAC (Sistema de Amortização Constante) é o padrão da Caixa para financiamento imobiliário. A parcela diminui ao longo do tempo porque o valor de amortização é fixo e os juros incidem sobre o saldo devedor.
amortização_mensal = principal / prazo_meses
juros_do_mês = saldo_devedor × taxa_mensal
parcela = amortização_mensal + juros_do_mês
saldo_devedor = saldo_devedor - amortização_mensalTaxa padrão: 1,6% a.m. (SBPE Caixa, conforme simulação 2025). A maioria dos imóveis de leilão Caixa aceita financiamento SBPE com entrada mínima de 20%.
6. Cálculo de Retorno do Investimento
6.1 Retorno simples
corretagem = valor_venda × 6%
custos_fixos_total = custos_mensais × meses
lucro_bruto = valor_venda - investimento_total - corretagem - custos_fixos - financiamento_pago
IR = lucro_bruto × 15% (se positivo)
lucro_liquido = lucro_bruto - IR
retorno_total = lucro_liquido / investimento_total
retorno_mensal = retorno_total / meses6.2 Premissas padrão
| Premissa | Valor | Nota |
|---|---|---|
| Corretagem de venda | 6% | Padrão de mercado MG |
| Imposto de Renda | 15% | Ganho de capital para pessoa física |
| Custos fixos mensais | Variável | IPTU + condomínio + água + luz + gás |
| Prazo de venda | 6 meses (padrão) | Ajustável pelo usuário |
6.3 Fluxo de caixa mensal
O simulador gera um fluxo de caixa mês a mês:
| Mês | Entradas | Saídas |
|---|---|---|
| 0 (compra) | — | Investimento total (entrada + ITBI + cartório + comissão + dívidas + reforma) |
| 1 a N-1 | — | Custos fixos + parcela financiamento |
| N (venda) | Valor de venda líquido | Custos fixos + parcela + quitação financiamento |
7. Algoritmo de Deal Score (0-100)
Cada imóvel recebe uma nota de 0 a 100 que indica a qualidade da oportunidade. A nota v2 é composta por 7 fatores, incluindo penalidades por risco jurídico:
| Fator | Peso | Critérios |
|---|---|---|
| Desconto | 35 pts | ≥50%→35, ≥40%→30, ≥30%→24, ≥20%→18, ≥10%→10, >0%→4 |
| Ocupação | 20 pts | Desocupado→20, Não informado→8, Ocupado→0 |
| Modalidade | 15 pts | V.Direta→15, V.Online→13, Licitação→10, Leilão→5 |
| Pagamento | 10 pts | SBPE+FGTS→10, SBPE→7, FGTS→5, À vista→2 |
| Confiança dados | 10 pts | ≥20 transações ITBI→10, ≥10→7, ≥5→5, ≥3→3 |
| Averbação | 5 pts | Averbado→5, Não se aplica→3, Em tratamento→0 |
| Risco matrícula | -15/-5 pts | Gravame/penhora→-15, Regularização adquirente→-5 |
Desconto: Usa o desconto real ITBI quando disponível (BH). Para demais cidades, usa o desconto vs. avaliação da Caixa.
Pagamento: SBPE+FGTS é o melhor (financiamento bancário + FGTS). 71% dos imóveis aceitam apenas FGTS sem financiamento bancário. 19% são exclusivamente à vista.
Classificação: Excelente (70+), Bom (50-69), Regular (30-49), Baixo (<30).
8. Seu Score (Personalizado)
Além do Deal Score padrão, o usuário pode criar um perfil de investidor respondendo 6 perguntas. O sistema recalcula um "Seu Score" com pesos personalizados baseados no perfil.
| Pergunta | Opções | Impacto nos pesos |
|---|---|---|
| Orçamento | Até R$100K / R$200K / R$500K / Sem limite | Filtra imóveis fora do alcance |
| Pagamento | À vista / FGTS / Financ. bancário | À vista: peso financiamento=0. Financ.: peso=20 |
| Objetivo | Flip / Moradia / Aluguel | Flip: desconto=45. Moradia: ocupação=30, localização=10 |
| Aceita ocupado? | Sim / Depende / Não | Sim: ocupação=0. Não: ocupação=35 |
| Prazo revenda | 3 / 6 / 12 / 24 meses | Afeta premissas do simulador |
| Risco jurídico | Baixo / Médio / Alto | Baixo: penalidade gravame=-25. Alto: -5 |
Perfil salvo em localStorage (navegador). Não é enviado a nenhum servidor. O "Seu Score" aparece como coluna adicional na tabela de imóveis.
9. Lance Máximo
Na página de detalhe de cada imóvel, o calculador de Lance Máximo responde: "Qual o máximo que devo dar de lance para atingir X% de retorno mensal?"
Dado: meta de retorno mensal, prazo, preço de venda estimado
Busca binária: encontra o preço de compra máximo que atinge a meta
Para cada candidato de preço:
total_investimento = preço + ITBI + cartório + comissão + honorários
lucro = venda - investimento - corretagem - IR - custos_fixos
retorno = lucro / investimento / meses
Premissas: corretagem 6%, IR 15%, custos fixos R$750/mês, à vista.O preço de venda estimado usa o valor de mercado ITBI quando disponível (BH). Para outros municípios, usa 90% da avaliação Caixa.
10. Integrações Google Maps
8.1 Street View
Cada imóvel com coordenadas exibe uma imagem do Street View do Google na página de detalhe. Permite visualizar a rua e vizinhança sem sair do app.
API: Street View Static API — custo: $7/1000 imagens (primeiros $200/mês grátis).
8.2 Locais Próximos
Para cada imóvel, buscamos estabelecimentos num raio de 1,5km:
| Categoria | Ícone |
|---|---|
| Escolas | 🏫 |
| Saúde (hospitais/clínicas) | 🏥 |
| Transporte público | 🚇 |
| Supermercados | 🛒 |
| Bancos | 🏦 |
| Farmácias | 💊 |
API: Google Places Nearby Search — retorna nome, nota, distância.
8.3 Tempo de Deslocamento
Calculamos o tempo de carro de cada imóvel até 5 pontos de referência em BH:
| Destino | Coordenadas |
|---|---|
| Centro BH (Praça Sete) | -19.9191, -43.9386 |
| Savassi | -19.9352, -43.9345 |
| Aeroporto de Confins | -19.6244, -43.9719 |
| Rodoviária de BH | -19.9129, -43.9283 |
| Anel Rodoviário (BR-040) | -19.9653, -43.9679 |
API: Google Distance Matrix API — custo: $5/1000 cálculos.
11. Regiões de Minas Gerais
Os imóveis são agrupados em regiões para facilitar a filtragem:
| Região | Principais cidades |
|---|---|
| RMBH (34 municípios) | BH, Contagem, Betim, Ribeirão das Neves, Esmeraldas, Santa Luzia, Nova Lima, Vespasiano... |
| Triângulo Mineiro | Uberlândia, Uberaba, Araguari, Ituiutaba, Patos de Minas, Iturama... |
| Zona da Mata | Juiz de Fora, Muriaé, Ubá, Cataguases, Leopoldina... |
| Sul de Minas | Varginha, Poços de Caldas, Pouso Alegre, Alfenas, Lavras... |
| Centro-Oeste | Divinópolis, Nova Serrana, Formiga, Itaúna, Pará de Minas... |
| Norte de Minas | Montes Claros, Janaúba, Januária, Pirapora... |
| Outras | Cidades não mapeadas nas regiões acima |
12. Pipeline de Dados
O fluxo de dados desde a fonte até a visualização no app:
2. Parse e upsert no DuckDB (detecção de novos/alterados/removidos)
3. Scraping das páginas de detalhe via Playwright (financiamento, datas, CEP)
4. Download dados ITBI de dados.pbh.gov.br (217 meses, ~497K transações)
5. Matching ITBI: cruzamento bairro × tipo → mediana R$/m² → desconto real
6. Geocoding: Nominatim + Google para coordenadas de mapa
7. Google Distance Matrix: tempo de deslocamento para 5 destinos
8. Deal Score: cálculo do score 0-100 para cada imóvel
9. Export: DuckDB → JSON estático para Next.js
10. Deploy: Vercel (build estático com 1.184 páginas de imóveis)
10.1 Comandos do pipeline
python -m src.ingest.caixa_csv
python -m src.ingest.caixa_detail_playwright 100
python -m src.ingest.itbi
python -m src.analyze.market_comparison
python -m src.analyze.deal_score
python -m src.enrich.commute_times
python -m src.export
vercel --prod13. Tendências de Bairro (ITBI Histórico)
Com 497K+ transações ITBI de 2008 a 2026, calculamos a evolução do R$/m² por bairro ao longo dos anos. Isso permite visualizar se um bairro está valorizando ou estagnando — informação crucial para decisões de investimento.
11.1 Metodologia
Para cada combinação (bairro + tipo de imóvel + ano):
mediana_anual = MEDIAN(preço_por_m²) para transações daquele ano
variação_anual = (mediana_atual - mediana_anterior) / mediana_anterior
tendência = série de medianas anuais (mínimo 5 anos de dados)Regra: Dados históricos são usados APENAS para tendências visuais (sparkline). O desconto real ITBI sempre usa apenas os últimos 24 meses — nunca misturamos períodos na comparação de preço.
11.2 Cobertura
| Métrica | Valor |
|---|---|
| Bairros com tendência (5+ anos) | 208 |
| Combinações bairro+tipo | 328 |
| Período coberto | 2008–2026 |
| Filtros aplicados | Mesmos da análise ITBI (área > 20m², preço R$500-30K/m²) |
14. Benchmark CDI
O simulador compara o retorno do investimento em leilão com o rendimento equivalente em CDI (Certificado de Depósito Interbancário), que é a referência para investimentos de renda fixa no Brasil.
cdi_mensal = (1 + SELIC_anual)^(1/12) - 1
rendimento_cdi = investimento_total × ((1 + cdi_mensal)^meses - 1)
Exemplo: R$ 131.657 investidos por 6 meses a SELIC 13.25% a.a.:
CDI mensal = 1,044% → Rendimento = R$ 8.332SELIC referência: 13,25% a.a. (Março/2026). Atualizar conforme decisões do COPOM. Se o retorno do leilão supera o CDI equivalente, o investimento está gerando alpha.
15. Cenários de Simulação
O simulador oferece 3 cenários pré-configurados que ajustam automaticamente o preço de venda e prazo, baseados em premissas do mercado de leilões RMBH:
| Cenário | Preço de Venda | Prazo | Premissa |
|---|---|---|---|
| Otimista | 105% da avaliação Caixa | 4 meses | Imóvel desocupado, bom estado, mercado aquecido |
| Realista | 90% da avaliação Caixa | 6 meses | Cenário base — venda abaixo da avaliação com prazo normal |
| Conservador | 75% da avaliação Caixa | 12 meses | Imóvel ocupado ou com problemas, mercado frio |
Nota: A avaliação da Caixa tende a ser 10-25% acima do preço real de mercado (ITBI). Portanto, vender a 90% da avaliação pode significar vender próximo ao preço real.
16. Limitações Conhecidas
| Limitação | Impacto | Mitigação |
|---|---|---|
| ITBI apenas para BH | Sem comparação de mercado real para 95% dos imóveis (fora de BH) | Usar desconto vs. avaliação Caixa como proxy. FipeZAP como alternativa futura. |
| Status de ocupação indisponível | 0% dos imóveis têm dado de ocupação | Caixa não informa explicitamente. Pesquisa no TJMG por matrícula é alternativa futura. |
| Proteção anti-bot da Caixa | Scraping pode ser bloqueado após muitas requisições | Playwright com sessão de navegador real + rate limiting (4s entre requisições) |
| Dívida de condomínio desconhecida | Valor exato não disponível — apenas indicação de responsabilidade | Estimativas baseadas em % do valor de avaliação. Verificar diretamente com a administradora. |
| Dados ITBI com defasagem | Última atualização pode ter 30-60 dias de atraso | Usar janela de 24 meses para mediana. Acompanhar dados.pbh.gov.br mensalmente. |
| Geocoding aproximado | ~800 imóveis com coordenadas em centróide de bairro/cidade | Google Geocoding API para refinar. Street View valida visualmente. |
17. Changelog
- Financiamento granular: SBPE+FGTS (10%), FGTS (71%), À vista (19%)
- Sinais de risco: gravame/penhora/indisponibilidade (57 imóveis)
- Deal Score v2 com averbação (+5) e risco (-15)
- Perfil de investidor: 6 perguntas → Seu Score personalizado
- Lance Máximo: busca binária para meta de retorno
- Filtro por bairro (527 bairros) e financiamento
- Todas as páginas auditadas e reformuladas
- 9 páginas: +Perfil
- 497K transações ITBI (era 46K) — 16 anos de dados históricos
- Tendências de bairro com sparkline (208 bairros, 2015-2026)
- P-tier (padrão construtivo) para comparações mais precisas
- Benchmark CDI no simulador (SELIC 13.25% a.a.)
- Cenários Otimista / Realista / Conservador no simulador
- Veredicto de negócio ("Viável" / "Arriscado")
- Anotações de fonte de dados em todas as páginas
- Dashboard interativo com filtros clicáveis
- Comparação com Street View, custos estimados, localização
- Mapa com marcadores por Deal Score + legenda + sidebar
- 1.184 imóveis de MG (Caixa CSV)
- 100% enriquecidos via Playwright (financiamento, CEP, leiloeiro)
- 46K transações ITBI (20 meses)
- Deal Score 0-100 em todos os imóveis
- Google Maps: Street View, Places, Distance Matrix
- Simulador financeiro com SAC e fluxo de caixa
- 7 páginas: Painel, Imóveis, Mapa, Comparar, Simulador, Docs, Detalhe