# FL Brokers · API de imóveis

Anúncios comerciais da FL Brokers, coletados da API pública da Kenlo (ex-inGaia),
normalizados e servidos em REST **somente leitura**. Sem cadastro, sem token.

Base: https://flbrokers.mukutu.cloud

## Limitações conhecidas

**Cobertura parcial.** O índice da Kenlo é `prd_sites_listings_v1`
(Elasticsearch) e o `max_result_window` padrão limita a paginação profunda a
10.000 registros. A base tem 9.980 dos 11.243 declarados pela origem — 1.263 a
menos, 11,2%. A partir da página 209 a resposta é `HTTP 200` com lista vazia e
sem o campo `count`, sem sinalizar o limite. Ampliar a cobertura exige
particionar a consulta, não aumentar a paginação. `/api/health` expõe essa
diferença.

**Acervo predominantemente comercial.** `OFFICE_FLOOR` representa 78,5% do
total (7.832 de 9.980), contra 339 apartamentos e 638 casas. A base não é
indicada para casos de uso residenciais.

## Rotas

- `GET /api/health` — contagem, `collected_at` mais recente, páginas de payload preservadas e a diferença para o total declarado pela origem. O indicador é de **atualidade do dado**, não de disponibilidade do processo.
- `GET /api/facets` — contagens por cidade, estado, tipo e finalidade, calculadas por `GROUP BY` a cada requisição.
- `GET /api/listings` — busca. Filtros opcionais combinados por AND: `city`, `state`, `neighborhood`, `property_type`, `purpose`, `sale_cents_gte/lte`, `rent_cents_gte/lte`, `area_m2_gte/lte`, `bedrooms_gte`, `parking_spaces_gte`. Ordenação por `ref`, `sale`, `rent`, `area`, `collected_at`, com `desc`. Paginação `limit` (máx. 200) e `offset`.
- `GET /api/listings/{ref}` — um imóvel pela referência da Kenlo. 404 quando não existe.
- `GET /api/listings/{ref}/raw` — o payload original da Kenlo, sem transformação. Permite acessar campos não normalizados sem depender de uma nova versão da API: URLs das fotos, códigos de amenidade, `property_metreage`.
- `POST /api/ingest` — inicia uma coleta em segundo plano e responde **202** imediatamente. Sem fila e sem worker: não há relatório de progresso (consulte `/api/health`), não há reprocessamento automático em caso de falha, e uma coleta em andamento não sobrevive a um reinício do processo. Uma segunda chamada durante a primeira recebe **409**.
- `GET /schema.json` — o contrato do registro.
- `GET /api/openapi.json` e `GET /api/docs` — a superfície HTTP, gerada das próprias rotas.

## Convenções da API

- **`ref` é o identificador público.** É a referência da Kenlo (ex. `CJ23573-FLE`). Não há id sequencial exposto: um segundo identificador criaria duas identidades para o mesmo imóvel.
- **Valores monetários em CENTAVOS, como inteiro.** Nunca ponto flutuante: a origem envia `1700000.01`, e erro de arredondamento em dinheiro só aparece no agregado. A formatação é do consumidor.
- **`collected_at` em toda resposta.** Dado de imóvel envelhece; a data de coleta torna a idade do registro sempre explícita.
- **`source` é um enum aberto.** Hoje 100% dos registros são `kenlo_rest`; um valor não previsto é armazenado como veio, em vez de descartado.
- **`purposes` é um array JSON como string**, e um imóvel frequentemente atende às duas finalidades: `["FOR_SALE", "FOR_RENT"]` em 3.607 registros.

## Inconsistências da origem, documentadas e preservadas

- **15 imóveis com preço de 1 centavo.** É sentinela de "sob consulta", não preço. Ordenação por menor valor sem tratamento coloca esses 15 no topo.
- **Área declarada de 2,5 m² a 5.022.800 m².** O extremo superior equivale a 502 hectares — provavelmente terreno rural ou erro de digitação na origem.
- **Um `OFFICE_FLOOR` a R$ 1,2 bilhão** existe no acervo.
- **`property_metreage` é inconsistente:** apresenta `SQFT` em imóvel cujo título anuncia m². O campo só aparece em `/api/listings/{ref}/raw`.

Nenhum desses valores é corrigido na resposta: a correção silenciosa ocultaria
do integrador a inconsistência da origem. O `schema.json` descreve cada caso.

## Exemplos

```
curl -s https://flbrokers.mukutu.cloud/api/health | jq
curl -s 'https://flbrokers.mukutu.cloud/api/listings?city=Barueri&limit=3' | jq
curl -s 'https://flbrokers.mukutu.cloud/api/listings?purpose=FOR_SALE&sort=sale&desc=true&limit=5' | jq
curl -s https://flbrokers.mukutu.cloud/schema.json | jq '.["x-coverage"]'
```