Pular para o conteúdo
Kondomino

Documentação

Início rápido

Do primeiro teste, sem cadastro, até a integração com a sua chave. Cada exemplo vem em curl, JavaScript (fetch, Node 18+ ou navegador) e Python (requests). A lista completa de endpoints está na referência.

1. Testar sem chave

A demonstração responde as mesmas buscas da API, sem cadastro: 5 consultas por dia por endereço IP, até 10 condomínios por página e 2 páginas por busca. O jeito mais rápido é o simulador, que mostra o curl e o JSON de cada consulta. Direto na API, use /v1/demo/kondos:

Busca na demonstração — curl
curl -i 'https://api.kondomino.com.br/v1/demo/kondos?uf=SP&limit=3'

Cada item da busca é um resumo. A ficha completa de um condomínio vem pelo slug:

Ficha na demonstração — curl
curl -i 'https://api.kondomino.com.br/v1/demo/kondos/estancia-dourados-i'

2. Criar uma chave

Fora da demonstração, a API pede uma chave. Crie uma conta no console e gere a chave em Chaves de API: ela começa com kd_live_ e aparece uma única vez, então copie e guarde num cofre de segredos. O plano Grátis dá 50 consultas por dia a cada chave.

Nos exemplos, a chave vem da variável de ambiente KONDOMINO_API_KEY: export KONDOMINO_API_KEY=kd_live_…. Nunca coloque a chave em código que roda no navegador do seu usuário.

3. Primeira chamada

Mande a chave no cabeçalho Authorization: Bearer kd_live_…. /v1/me confirma qual chave é e em que plano ela é medida, e não gasta consulta:

Primeira chamada com chave — curl
curl -i 'https://api.kondomino.com.br/v1/me' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

4. Lista e ficha

A busca (/v1/kondos) devolve o resumo de cada condomínio: slug, name, city, uf, neighborhood, type, property_status e updated_at.

Busca com chave (resumo) — curl
curl -i 'https://api.kondomino.com.br/v1/kondos?uf=SP&limit=5' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

Preço de referência, taxa de condomínio, endereço, coordenadas, comodidades, mídia e procedência vêm na ficha, em /v1/kondos/{slug}. Cada busca, cada página e cada ficha contam uma consulta. Todos os campos estão no modelo de dados.

Ficha com chave (registro completo) — curl
curl -i 'https://api.kondomino.com.br/v1/kondos/estancia-dourados-i' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

5. Filtros

Toda busca precisa de um filtro geográfico: uf (sigla), city (slug da cidade) ou near (lat,lng, com radius_km até 50). Sem nenhum deles, a resposta é 400 e não gasta consulta. Os outros filtros refinam: neighborhood, amenity, q (parte do nome), type, property_status, updated_since, price_min e price_max.

Filtros — curl
# Por cidade (slug de /v1/cities) e comodidade (chave de /v1/amenities)
curl -i 'https://api.kondomino.com.br/v1/kondos?city=nova-lima&amenity=pool' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

# Num raio de 5 km de um ponto (lat,lng)
curl -i 'https://api.kondomino.com.br/v1/kondos?near=-23.5505,-46.6333&radius_km=5' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

Os valores aceitos por city e amenity vêm das listas de referência (/v1/states, /v1/cities, /v1/amenities), que não pedem chave e não contam consulta:

Cidades de uma UF — curl
curl -i 'https://api.kondomino.com.br/v1/cities?uf=MG'

Sem filtro geográfico:

Busca sem filtro geográfico — curl
curl -i 'https://api.kondomino.com.br/v1/demo/kondos?q=reserva'

6. Paginação

A resposta traz page.has_more e page.next_cursor. Para a página seguinte, mande só o cursor: ele é assinado, carrega os filtros e a posição, vale 10 minutos e só para a chave que o recebeu. Um cursor alterado, vencido ou de outra chave responde 400 invalid_cursor. O tamanho da página (limit) tem teto por plano: 20 no Grátis; valores maiores são truncados.

Paginação com cursor — curl
# Primeira página: guarde page.next_cursor da resposta
curl -s 'https://api.kondomino.com.br/v1/kondos?uf=MG&limit=20' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

# Página seguinte: só o cursor (ele já carrega os filtros)
curl -s "https://api.kondomino.com.br/v1/kondos?cursor=$CURSOR" \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

7. Cota diária

Cada chave tem uma cota de consultas por dia: 50 no Grátis (veja preços). O dia vira à meia-noite de São Paulo. Toda resposta que conta consulta traz:

  • X-Quota-Limit — consultas por dia do seu plano;
  • X-Quota-Remaining — quantas ainda restam hoje;
  • X-Quota-Reset — quando a cota renova (ISO 8601, a próxima meia-noite de São Paulo).

Quando acaba, a resposta é 429 quota_exceeded, com Retry-After em segundos até a meia-noite. Não há cobrança extra. /v1/me, as listas de referência e o próprio openapi.json não contam; um pedido que responde 400 ou 401 também não. O seu uso por dia aparece no console.

8. Limite por minuto

Separado da cota, todo plano tem um freio de 30 requisições por minuto (por chave, ou por IP na demonstração). Passou disso, a resposta é 429 rate_limited com Retry-After; isso não gasta cota. Espere e tente de novo, mas não insista num quota_exceeded: ele só passa no dia seguinte.

Respeitar Retry-After — curl
# curl repete em 429 e espera o Retry-After
curl -i --retry 3 --retry-max-time 120 'https://api.kondomino.com.br/v1/states'

9. Erros

Todo erro é application/problem+json (RFC 9457): type, title, status, detail (texto em português, para pessoas) e code (estável, para o seu código). Decida pelo code. A lista completa está na referência de erros.

Tratar erros pelo code — curl
# Sem a chave: 401 missing_api_key, em application/problem+json
curl -i 'https://api.kondomino.com.br/v1/me'

10. Cache

As listas de referência e o openapi.json respondem Cache-Control: public, max-age=600: guarde por até 10 minutos. Consultas e /v1/me respondem private, no-store, porque carregam a cota da sua chave; erros respondem no-store. Para não gastar consultas repetindo a mesma busca, guarde as fichas do seu lado e use updated_since para buscar só o que mudou.

Cabeçalhos de cache — curl
# Listas de referência: Cache-Control: public, max-age=600
curl -i 'https://api.kondomino.com.br/v1/amenities'