{"openapi":"3.0.0","paths":{"/v1/demo/kondos":{"get":{"operationId":"demo_list","summary":"Lista kondos publicados (resumo)","description":"Exige `uf`, `city`, `near`, `cep` ou `registry_id` (mesmos filtros de /v1/kondos). Até 10 itens por página e 2 páginas. Cada chamada consome 1 das 5 consultas diárias por IP.","parameters":[{"name":"x-api-key","in":"header","description":"Somente para o servidor do site da Kondomino: com a chave interna, o X-Forwarded-For é aceito como IP do visitante.","required":false,"schema":{"type":"string"}},{"name":"uf","required":false,"in":"query","description":"UF (sigla do estado), ex.: MG. Informe `uf`, `city`, `near`, `cep` ou `registry_id`.","schema":{"example":"MG","type":"string"}},{"name":"city","required":false,"in":"query","description":"Cidade, como slug de `/v1/cities` (sem acentos, hífen no lugar de espaço), ex.: nova-lima.","schema":{"example":"nova-lima","type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Bairro; comparado sem acentos, caixa e pontuação, ex.: vila-nova-conceicao.","schema":{"example":"vale-do-sereno","type":"string"}},{"name":"near","required":false,"in":"query","description":"Kondos a até `radius_km` deste ponto, `lat,lng` em graus decimais. Substitui `uf`/`city` como filtro geográfico. A ordem continua sendo a do catálogo, não a distância.","schema":{"example":"-23.5505,-46.6333","type":"string"}},{"name":"radius_km","required":false,"in":"query","description":"Raio de `near`, em km. Padrão 10, máximo 50.","schema":{"example":10,"type":"number"}},{"name":"cep","required":false,"in":"query","description":"CEP do kondo, 8 dígitos com ou sem hífen. Devolve os kondos nesse CEP (um CEP pode ter vários). Dispensa `uf`, `city` e `near`.","schema":{"example":"30140-071","type":"string"}},{"name":"registry_id","required":false,"in":"query","description":"CNPJ do condomínio no registro público (o `provenance.registry_id` do registro por slug), com ou sem pontuação. Dispensa `uf`, `city` e `near`.","schema":{"example":"02.644.049/0001-02","type":"string"}},{"name":"amenity","required":false,"in":"query","description":"Chave pública de comodidade (`/v1/amenities`), ex.: pool.","schema":{"enum":["lobby_24h","security_team","perimeter_wall","sports_court","barbecue_area","pool","social_area","pet_area","kids_area","lagoon","electricity","water_supply","sidewalks","internet","own_power_generation","lawn_area","woods","vegetable_garden","nature_trail","gourmet_area","parking_lot","heliport","gym","gardens","virtual_concierge","home_office","lounge_bar","party_room","market_nearby","elevator","wheelchair_accessible","ramp_access","cctv","biometric_access","intercom","alarm_system","gated_entrance","electric_fence","sauna","steam_room","spa","indoor_pool","heated_pool","hot_tub","yoga_room","tennis_court","soccer_field","running_track","squash_court","playground","daycare","baby_care_room","teen_area","toy_library","pet_washing_station","home_theater","game_room","billiards_room","library","music_room","wine_cellar","coworking_space","meeting_room","karaoke_room","rooftop","solarium","fire_pit","beach_access","lake_access","visitor_parking","ev_charging","bike_parking","motorcycle_parking","valet_parking","car_wash","storage_locker","laundry_room","restaurant","concierge","package_room","solar_panels","rainwater_harvesting","greywater_reuse","green_roof"],"type":"string"}},{"name":"q","required":false,"in":"query","description":"Parte do nome do kondo (ignora acentos e caixa).","schema":{"example":"reserva","type":"string"}},{"name":"type","required":false,"in":"query","description":"Tipo do kondo.","schema":{"enum":["bairro","casas","chacatas","predios","comercial","industrial"],"type":"string"}},{"name":"property_status","required":false,"in":"query","description":"Fase do empreendimento.","schema":{"enum":["launching","under_construction","existing","unknown"],"type":"string"}},{"name":"updated_since","required":false,"in":"query","description":"Só kondos atualizados a partir deste instante (ISO 8601: data ou data e hora), ex.: 2026-10-01.","schema":{"example":"2026-10-01","type":"string"}},{"name":"price_min","required":false,"in":"query","description":"Preço de referência (`reference_price`) mínimo, em R$. Exclui kondos sem preço.","schema":{"example":300000,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Preço de referência (`reference_price`) máximo, em R$. Exclui kondos sem preço.","schema":{"example":900000,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Itens por página. Máximo por tier — demo 10, free 20, pro 50; valores maiores são truncados.","schema":{"example":10,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco devolvido em `page.next_cursor`. Válido por 10 minutos, só para a mesma chave.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de resumos.","headers":{"X-Quota-Limit":{"description":"Consultas por dia na demonstração (5).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KondoPage"},"example":{"data":[{"slug":"alive","name":"Alive","city":"São Paulo","uf":"SP","neighborhood":"Vila Prudente","type":"predios","property_status":"unknown","updated_at":"2026-09-15T16:57:25.986Z"},{"slug":"boulevard-lapa","name":"Boulevard Lapa","city":"São Paulo","uf":"SP","neighborhood":"Lapa","type":"predios","property_status":"unknown","updated_at":"2026-09-15T16:58:53.233Z"}],"page":{"number":1,"limit":2,"has_more":true,"next_cursor":"eyJmIjp7InVmIjoiU1AifSwiYSI6MiwicCI6MX0.c2lnbmF0dXJl"}}}}},"400":{"description":"validation_error ou invalid_cursor. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"quota_exceeded (cota diária) ou rate_limited (30/min). Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","headers":{"X-Quota-Limit":{"description":"Consultas por dia na demonstração (5).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["demo"]}},"/v1/demo/kondos/{slug}":{"get":{"operationId":"demo_detail","summary":"Registro público completo de um kondo","description":"Cada chamada consome 1 das 5 consultas diárias por IP. Mídia: apenas URLs de origem.","parameters":[{"name":"x-api-key","in":"header","description":"Somente para o servidor do site da Kondomino: com a chave interna, o X-Forwarded-For é aceito como IP do visitante.","required":false,"schema":{"type":"string"}},{"name":"slug","required":true,"in":"path","schema":{"example":"reserva-do-lago","type":"string"}}],"responses":{"200":{"description":"Registro do kondo.","headers":{"X-Quota-Limit":{"description":"Consultas por dia na demonstração (5).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KondoDetail"},"example":{"slug":"nova-zelandia-ii","name":"Nova Zelandia Ii","city":"Cotia","uf":"SP","neighborhood":"Centreville","type":"predios","property_status":"unknown","updated_at":"2026-09-21T14:20:53.153Z","address_street":"R N Zelândia, S/N","cep":"06700-410","lat":-23.603889,"lng":-46.918889,"reference_price":150193,"price_collected_at":"2026-09-19T21:00:39.085Z","condo_fee":null,"construction_year":null,"builder":null,"amenities":["security_team","perimeter_wall","barbecue_area","parking_lot","party_room","wheelchair_accessible","gated_entrance","playground"],"description":"Conheça o Residencial Nova Zelândia II. Localizado em uma das regiões que mais se desenvolvem na cidade de Cotia. Aqui você encontra tranquilidade, conforto e toda a infraestrutura que precisa para viver bem.","media":[],"provenance":{"source_url":"https://tenda.com/apartamentos-a-venda/sp/cotia/nova-zelandia-ii","source_type":"B","source_name":"Tenda","registry_id":null,"registered_since":null,"collected_at":"2026-09-19T21:00:39.085Z","data_updated_at":"2026-09-21T14:20:53.153Z","confidence":0.87,"extraction_method":"deterministic"}}}}},"404":{"description":"not_found — inexistente ou não publicado. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"quota_exceeded ou rate_limited. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","headers":{"X-Quota-Limit":{"description":"Consultas por dia na demonstração (5).","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["demo"]}},"/v1/states":{"get":{"operationId":"reference_states","summary":"UFs com ao menos um kondo publicado","description":"Ordem: `kondo_count` decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.","parameters":[],"responses":{"200":{"description":"{ data: [{ uf, name, kondo_count }] }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateList"}}}},"429":{"description":"rate_limited. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["reference"]}},"/v1/cities":{"get":{"operationId":"reference_cities","summary":"Cidades com ao menos um kondo publicado","description":"O `slug` é o valor aceito por `/v1/kondos?city=` (e pela demo). `lat`/`lng`: média das coordenadas dos kondos publicados da cidade, ou null. Ordem: `kondo_count` decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.","parameters":[{"name":"uf","required":false,"in":"query","description":"UF (sigla do estado), ex.: SP. Sem ela, todas as cidades.","schema":{"example":"SP","type":"string"}}],"responses":{"200":{"description":"{ data: [{ slug, name, uf, kondo_count, unit_count, lat, lng }] }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityList"}}}},"400":{"description":"validation_error — `uf` inválida. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"rate_limited. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["reference"]}},"/v1/amenities":{"get":{"operationId":"reference_amenities","summary":"Comodidades e quantos kondos publicados têm cada uma","description":"A `key` é o valor aceito por `/v1/demo/kondos?amenity=`. Ordem: `kondo_count` decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.","parameters":[],"responses":{"200":{"description":"{ data: [{ key, label, kondo_count }] }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AmenityList"}}}},"429":{"description":"rate_limited. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["reference"]}},"/v1/builders":{"get":{"operationId":"reference_builders","summary":"Construtoras com kondos publicados","description":"Construtora = fonte primária do kondo é o site de uma construtora. Ordem: `kondo_count` decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.","parameters":[],"responses":{"200":{"description":"{ data: [{ name, website, kondo_count }] }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuilderList"}}}},"429":{"description":"rate_limited. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["reference"]}},"/v1/me":{"get":{"operationId":"me_me","summary":"A chave usada nesta chamada e o tier da conta. Não consome consultas.","parameters":[],"responses":{"200":{"description":"{ api_key: { prefix, name }, tier: \"free\" | \"pro\" }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"},"example":{"api_key":{"prefix":"a1b2c3d4","name":"produção"},"tier":"free"}}}},"401":{"description":"missing_api_key, invalid_api_key ou revoked_api_key. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"rate_limited (requisições por minuto da chave). Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["me"],"security":[{"ApiKey":[]}]}},"/v1/kondos":{"get":{"operationId":"kondos_list","summary":"Lista kondos publicados (resumo)","description":"Exige um filtro que localize: `uf`, `city`, `near`, `cep` ou `registry_id` (o CNPJ). Resumo por item: slug, name, city, uf, neighborhood, type, property_status, updated_at. Até 20 itens por página no free e 50 no pro; pagine com `page.next_cursor` (válido por 10 minutos, só para a mesma chave). Cada chamada consome 1 consulta da cota diária da chave (free 50, pro 100; renova à meia-noite de São Paulo). Um pedido inválido (400) não consome.","parameters":[{"name":"uf","required":false,"in":"query","description":"UF (sigla do estado), ex.: MG. Informe `uf`, `city`, `near`, `cep` ou `registry_id`.","schema":{"example":"MG","type":"string"}},{"name":"city","required":false,"in":"query","description":"Cidade, como slug de `/v1/cities` (sem acentos, hífen no lugar de espaço), ex.: nova-lima.","schema":{"example":"nova-lima","type":"string"}},{"name":"neighborhood","required":false,"in":"query","description":"Bairro; comparado sem acentos, caixa e pontuação, ex.: vila-nova-conceicao.","schema":{"example":"vale-do-sereno","type":"string"}},{"name":"near","required":false,"in":"query","description":"Kondos a até `radius_km` deste ponto, `lat,lng` em graus decimais. Substitui `uf`/`city` como filtro geográfico. A ordem continua sendo a do catálogo, não a distância.","schema":{"example":"-23.5505,-46.6333","type":"string"}},{"name":"radius_km","required":false,"in":"query","description":"Raio de `near`, em km. Padrão 10, máximo 50.","schema":{"example":10,"type":"number"}},{"name":"cep","required":false,"in":"query","description":"CEP do kondo, 8 dígitos com ou sem hífen. Devolve os kondos nesse CEP (um CEP pode ter vários). Dispensa `uf`, `city` e `near`.","schema":{"example":"30140-071","type":"string"}},{"name":"registry_id","required":false,"in":"query","description":"CNPJ do condomínio no registro público (o `provenance.registry_id` do registro por slug), com ou sem pontuação. Dispensa `uf`, `city` e `near`.","schema":{"example":"02.644.049/0001-02","type":"string"}},{"name":"amenity","required":false,"in":"query","description":"Chave pública de comodidade (`/v1/amenities`), ex.: pool.","schema":{"enum":["lobby_24h","security_team","perimeter_wall","sports_court","barbecue_area","pool","social_area","pet_area","kids_area","lagoon","electricity","water_supply","sidewalks","internet","own_power_generation","lawn_area","woods","vegetable_garden","nature_trail","gourmet_area","parking_lot","heliport","gym","gardens","virtual_concierge","home_office","lounge_bar","party_room","market_nearby","elevator","wheelchair_accessible","ramp_access","cctv","biometric_access","intercom","alarm_system","gated_entrance","electric_fence","sauna","steam_room","spa","indoor_pool","heated_pool","hot_tub","yoga_room","tennis_court","soccer_field","running_track","squash_court","playground","daycare","baby_care_room","teen_area","toy_library","pet_washing_station","home_theater","game_room","billiards_room","library","music_room","wine_cellar","coworking_space","meeting_room","karaoke_room","rooftop","solarium","fire_pit","beach_access","lake_access","visitor_parking","ev_charging","bike_parking","motorcycle_parking","valet_parking","car_wash","storage_locker","laundry_room","restaurant","concierge","package_room","solar_panels","rainwater_harvesting","greywater_reuse","green_roof"],"type":"string"}},{"name":"q","required":false,"in":"query","description":"Parte do nome do kondo (ignora acentos e caixa).","schema":{"example":"reserva","type":"string"}},{"name":"type","required":false,"in":"query","description":"Tipo do kondo.","schema":{"enum":["bairro","casas","chacatas","predios","comercial","industrial"],"type":"string"}},{"name":"property_status","required":false,"in":"query","description":"Fase do empreendimento.","schema":{"enum":["launching","under_construction","existing","unknown"],"type":"string"}},{"name":"updated_since","required":false,"in":"query","description":"Só kondos atualizados a partir deste instante (ISO 8601: data ou data e hora), ex.: 2026-10-01.","schema":{"example":"2026-10-01","type":"string"}},{"name":"price_min","required":false,"in":"query","description":"Preço de referência (`reference_price`) mínimo, em R$. Exclui kondos sem preço.","schema":{"example":300000,"type":"number"}},{"name":"price_max","required":false,"in":"query","description":"Preço de referência (`reference_price`) máximo, em R$. Exclui kondos sem preço.","schema":{"example":900000,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Itens por página. Máximo por tier — demo 10, free 20, pro 50; valores maiores são truncados.","schema":{"example":10,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor opaco devolvido em `page.next_cursor`. Válido por 10 minutos, só para a mesma chave.","schema":{"type":"string"}}],"responses":{"200":{"description":"{ data: [resumo], page: { number, limit, has_more, next_cursor } }","headers":{"X-Quota-Limit":{"description":"Consultas por dia do seu tier.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KondoPage"},"example":{"data":[{"slug":"alive","name":"Alive","city":"São Paulo","uf":"SP","neighborhood":"Vila Prudente","type":"predios","property_status":"unknown","updated_at":"2026-09-15T16:57:25.986Z"},{"slug":"boulevard-lapa","name":"Boulevard Lapa","city":"São Paulo","uf":"SP","neighborhood":"Lapa","type":"predios","property_status":"unknown","updated_at":"2026-09-15T16:58:53.233Z"}],"page":{"number":1,"limit":2,"has_more":true,"next_cursor":"eyJmIjp7InVmIjoiU1AifSwiYSI6MiwicCI6MX0.c2lnbmF0dXJl"}}}}},"400":{"description":"validation_error ou invalid_cursor. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"missing_api_key, invalid_api_key ou revoked_api_key. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"quota_exceeded (cota diária da chave) ou rate_limited (requisições por minuto). Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","headers":{"X-Quota-Limit":{"description":"Consultas por dia do seu tier.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["kondos"],"security":[{"ApiKey":[]}]}},"/v1/kondos/{slug}":{"get":{"operationId":"kondos_detail","summary":"Registro público completo de um kondo","description":"Endereço, coordenadas, preço de referência, comodidades, mídia (somente URLs de origem) e procedência. Cada chamada consome 1 consulta da cota diária da chave (free 50, pro 100; renova à meia-noite de São Paulo). Um pedido inválido (400) não consome.","parameters":[{"name":"slug","required":true,"in":"path","schema":{"example":"reserva-do-lago","type":"string"}}],"responses":{"200":{"description":"Registro do kondo.","headers":{"X-Quota-Limit":{"description":"Consultas por dia do seu tier.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KondoDetail"},"example":{"slug":"nova-zelandia-ii","name":"Nova Zelandia Ii","city":"Cotia","uf":"SP","neighborhood":"Centreville","type":"predios","property_status":"unknown","updated_at":"2026-09-21T14:20:53.153Z","address_street":"R N Zelândia, S/N","cep":"06700-410","lat":-23.603889,"lng":-46.918889,"reference_price":150193,"price_collected_at":"2026-09-19T21:00:39.085Z","condo_fee":null,"construction_year":null,"builder":null,"amenities":["security_team","perimeter_wall","barbecue_area","parking_lot","party_room","wheelchair_accessible","gated_entrance","playground"],"description":"Conheça o Residencial Nova Zelândia II. Localizado em uma das regiões que mais se desenvolvem na cidade de Cotia. Aqui você encontra tranquilidade, conforto e toda a infraestrutura que precisa para viver bem.","media":[],"provenance":{"source_url":"https://tenda.com/apartamentos-a-venda/sp/cotia/nova-zelandia-ii","source_type":"B","source_name":"Tenda","registry_id":null,"registered_since":null,"collected_at":"2026-09-19T21:00:39.085Z","data_updated_at":"2026-09-21T14:20:53.153Z","confidence":0.87,"extraction_method":"deterministic"}}}}},"401":{"description":"missing_api_key, invalid_api_key ou revoked_api_key. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"not_found — inexistente ou não publicado. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"quota_exceeded (cota diária da chave) ou rate_limited (requisições por minuto). Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","headers":{"X-Quota-Limit":{"description":"Consultas por dia do seu tier.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Consultas restantes hoje.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.","schema":{"type":"string","format":"date-time"}},"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["kondos"],"security":[{"ApiKey":[]}]}},"/v1/leads":{"post":{"operationId":"leads_create","summary":"Registra interesse no catálogo completo","description":"Sem chave. Limite de 5 envios por hora por IP. O campo `website` é um honeypot e deve vir vazio. A equipe comercial é avisada por e-mail.","parameters":[{"name":"x-api-key","in":"header","description":"Somente para o servidor do site da Kondomino: com a chave interna, o X-Forwarded-For é aceito como IP do visitante.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadDto"}}}},"responses":{"201":{"description":"{ id, status: \"received\" }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadReceipt"},"example":{"id":"6f1c2b1e-8a4e-4c1f-9d55-0c9b1f7e2a10","status":"received"}}}},"400":{"description":"validation_error, com `errors: [{ field, message }]`. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"rate_limited, com Retry-After. Erro no formato RFC 9457 (application/problem+json): { type, title, status, detail, code }.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"Retry-After":{"description":"Segundos até poder tentar de novo.","schema":{"type":"integer"}}}},"500":{"description":"internal_error — falha nossa; nenhum detalhe interno é exposto.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"tags":["leads"]}}},"info":{"title":"Kondomino Data API","description":"Dados estruturados de condomínios (kondos) brasileiros publicados pela Kondomino. Autentique com `Authorization: Bearer kd_live_…` (crie a chave em /console). Cada consulta sobre kondos consome a cota diária do tier (cabeçalhos `X-Quota-*`); todo erro é `application/problem+json` (schema `Problem`) com um `code` estável. Versionamento pelo prefixo: campos novos mantêm `/v1`.","version":"1","contact":{}},"tags":[{"name":"kondos","description":"Kondos publicados: listagem (resumo) e registro completo. Com chave; cada chamada é uma consulta."},{"name":"demo","description":"A mesma consulta sem chave: 5 por dia por IP, 10 por página, 2 páginas."},{"name":"reference","description":"Vocabulário dos filtros (UFs, cidades, comodidades, construtoras). Sem chave e sem custo."},{"name":"me","description":"Qual chave é esta e em que tier ela é medida. Não consome consultas."},{"name":"leads","description":"Interesse no catálogo completo, vendido por contrato."}],"servers":[{"url":"https://api.kondomino.com.br"}],"components":{"securitySchemes":{"ApiKey":{"scheme":"bearer","bearerFormat":"kd_live_…","type":"http","description":"Chave da API de dados: `Authorization: Bearer kd_live_…` (crie em /console)."}},"schemas":{"CreateLeadDto":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"example":"Ana Souza"},"company":{"type":"string","maxLength":160,"example":"Construtora Exemplo"},"email":{"type":"string","maxLength":254,"example":"ana@exemplo.com.br"},"phone":{"type":"string","maxLength":30,"example":"+55 11 99999-0000"},"role":{"type":"string","maxLength":120,"example":"Diretora de dados"},"intendedUse":{"type":"string","enum":["own_product","market_analysis","credit_insurance","other"]},"intendedUseOther":{"type":"string","maxLength":200,"description":"Obrigatório quando intendedUse = other."},"ufs":{"example":["SP","MG"],"description":"UFs (siglas) de interesse; ao menos uma.","type":"array","items":{"type":"string"}},"message":{"type":"string","maxLength":2000},"website":{"type":"string","description":"Honeypot: deve vir vazio."}},"required":["name","company","email","intendedUse","ufs"]},"Problem":{"type":"object","description":"RFC 9457 problem details. Ramifique pelo `code`, que é estável; `detail` é texto em pt-BR.","required":["type","title","status","detail","code"],"properties":{"type":{"type":"string","format":"uri","example":"https://kondomino.com.br/docs/api/errors/validation_error"},"title":{"type":"string","example":"Invalid request"},"status":{"type":"integer","example":400},"detail":{"type":"string","example":"Parâmetros inválidos."},"code":{"type":"string","enum":["validation_error","invalid_cursor","not_found","quota_exceeded","rate_limited","unauthorized","missing_api_key","invalid_api_key","revoked_api_key","forbidden","key_limit_reached","key_not_active","internal_error"]},"errors":{"type":"array","description":"Somente em `validation_error`: o que está errado no pedido.","items":{"oneOf":[{"type":"string"},{"type":"object","required":["field","message"],"properties":{"field":{"type":"string"},"message":{"type":"string"}}}]}}}},"KondoSummary":{"type":"object","required":["slug","name","city","uf","neighborhood","type","property_status","updated_at"],"properties":{"slug":{"type":"string","example":"nova-zelandia-ii"},"name":{"type":"string"},"city":{"type":"string","nullable":true},"uf":{"type":"string","enum":["AC","AL","AP","AM","BA","CE","DF","ES","GO","MA","MT","MS","MG","PA","PB","PR","PE","PI","RJ","RN","RS","RO","RR","SC","SP","SE","TO"],"nullable":true},"neighborhood":{"type":"string","nullable":true},"type":{"type":"string","enum":["bairro","casas","chacatas","predios","comercial","industrial"],"nullable":true},"property_status":{"type":"string","enum":["launching","under_construction","existing","unknown"],"nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"KondoPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KondoSummary"}},"page":{"type":"object","required":["number","limit","has_more","next_cursor"],"properties":{"number":{"type":"integer","minimum":1},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","description":"Opaco, assinado, válido por 10 minutos.","nullable":true}}},"notice":{"type":"string","description":"Somente na demonstração, na última página que ela percorre."}}},"KondoDetail":{"allOf":[{"$ref":"#/components/schemas/KondoSummary"},{"type":"object","required":["address_street","cep","lat","lng","reference_price","price_collected_at","condo_fee","construction_year","builder","amenities","media","provenance"],"properties":{"address_street":{"type":"string","nullable":true},"cep":{"type":"string","example":"06700-410","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"reference_price":{"type":"number","description":"Preço \"a partir de\" coletado na fonte, em BRL.","nullable":true},"price_collected_at":{"type":"string","format":"date-time","description":"Última leitura da fonte que encontrou o preço de referência, mesmo que igual.","nullable":true},"condo_fee":{"type":"number","description":"Taxa de condomínio mensal, em BRL.","nullable":true},"construction_year":{"type":"integer","example":1989,"description":"Ano de construção do prédio, como a página de origem informa. Não é `registered_since` (a abertura do CNPJ).","nullable":true},"builder":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri","nullable":true}},"nullable":true},"amenities":{"type":"array","items":{"type":"string","enum":["lobby_24h","security_team","perimeter_wall","sports_court","barbecue_area","pool","social_area","pet_area","kids_area","lagoon","electricity","water_supply","sidewalks","internet","own_power_generation","lawn_area","woods","vegetable_garden","nature_trail","gourmet_area","parking_lot","heliport","gym","gardens","virtual_concierge","home_office","lounge_bar","party_room","market_nearby","elevator","wheelchair_accessible","ramp_access","cctv","biometric_access","intercom","alarm_system","gated_entrance","electric_fence","sauna","steam_room","spa","indoor_pool","heated_pool","hot_tub","yoga_room","tennis_court","soccer_field","running_track","squash_court","playground","daycare","baby_care_room","teen_area","toy_library","pet_washing_station","home_theater","game_room","billiards_room","library","music_room","wine_cellar","coworking_space","meeting_room","karaoke_room","rooftop","solarium","fire_pit","beach_access","lake_access","visitor_parking","ev_charging","bike_parking","motorcycle_parking","valet_parking","car_wash","storage_locker","laundry_room","restaurant","concierge","package_room","solar_panels","rainwater_harvesting","greywater_reuse","green_roof"]}},"media":{"type":"array","description":"URLs originais das imagens na fonte — nunca cópias nossas.","items":{"type":"string","format":"uri"}},"provenance":{"type":"object","required":["source_url","source_type","source_name","registry_id","registered_since","collected_at","data_updated_at","confidence","extraction_method"],"properties":{"source_url":{"type":"string","format":"uri","nullable":true},"source_type":{"type":"string","enum":["A","B","C","S","R"],"description":"Tipo da fonte: A marketplace, B construtora, C imobiliária, S site próprio do condomínio, R registro público (dataset aberto; sem página de origem).","nullable":true},"source_name":{"type":"string","description":"Nome da fonte (para R, o nome do dataset), quando conhecido.","nullable":true},"registry_id":{"type":"string","description":"Identificador do condomínio num registro público (o CNPJ, só dígitos), quando conhecido.","nullable":true},"registered_since":{"type":"string","format":"date","description":"Para R: data em que o condomínio foi registrado (abertura do CNPJ). Não é a idade do prédio; prédios anteriores a ~1990 receberam o CNPJ depois de construídos.","nullable":true},"collected_at":{"type":"string","format":"date-time","description":"Última leitura bem-sucedida da página de origem, mesmo sem mudança (para R, a data da edição do dataset).","nullable":true},"data_updated_at":{"type":"string","format":"date-time","description":"Última mudança de qualquer campo do registro (o mesmo instante de `updated_at`).","nullable":true},"confidence":{"type":"number","minimum":0,"maximum":1,"nullable":true},"extraction_method":{"type":"string","example":"llm","nullable":true}}}}}]},"Me":{"type":"object","required":["api_key","tier"],"properties":{"api_key":{"type":"object","required":["prefix","name"],"properties":{"prefix":{"type":"string","example":"a1b2c3d4"},"name":{"type":"string","example":"produção"}}},"tier":{"type":"string","enum":["free","pro"]}}},"StateRef":{"type":"object","required":["uf","name","kondo_count"],"properties":{"uf":{"type":"string","enum":["AC","AL","AP","AM","BA","CE","DF","ES","GO","MA","MT","MS","MG","PA","PB","PR","PE","PI","RJ","RN","RS","RO","RR","SC","SP","SE","TO"]},"name":{"type":"string"},"kondo_count":{"type":"integer"}}},"CityRef":{"type":"object","required":["slug","name","uf","kondo_count","unit_count","lat","lng"],"properties":{"slug":{"type":"string","example":"sao-paulo"},"name":{"type":"string"},"uf":{"type":"string","enum":["AC","AL","AP","AM","BA","CE","DF","ES","GO","MA","MT","MS","MG","PA","PB","PR","PE","PI","RJ","RN","RS","RO","RR","SC","SP","SE","TO"]},"kondo_count":{"type":"integer"},"unit_count":{"type":"integer"},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true}}},"AmenityRef":{"type":"object","required":["key","label","kondo_count"],"properties":{"key":{"type":"string","enum":["lobby_24h","security_team","perimeter_wall","sports_court","barbecue_area","pool","social_area","pet_area","kids_area","lagoon","electricity","water_supply","sidewalks","internet","own_power_generation","lawn_area","woods","vegetable_garden","nature_trail","gourmet_area","parking_lot","heliport","gym","gardens","virtual_concierge","home_office","lounge_bar","party_room","market_nearby","elevator","wheelchair_accessible","ramp_access","cctv","biometric_access","intercom","alarm_system","gated_entrance","electric_fence","sauna","steam_room","spa","indoor_pool","heated_pool","hot_tub","yoga_room","tennis_court","soccer_field","running_track","squash_court","playground","daycare","baby_care_room","teen_area","toy_library","pet_washing_station","home_theater","game_room","billiards_room","library","music_room","wine_cellar","coworking_space","meeting_room","karaoke_room","rooftop","solarium","fire_pit","beach_access","lake_access","visitor_parking","ev_charging","bike_parking","motorcycle_parking","valet_parking","car_wash","storage_locker","laundry_room","restaurant","concierge","package_room","solar_panels","rainwater_harvesting","greywater_reuse","green_roof"]},"label":{"type":"string"},"kondo_count":{"type":"integer"}}},"BuilderRef":{"type":"object","required":["name","website","kondo_count"],"properties":{"name":{"type":"string"},"website":{"type":"string","nullable":true},"kondo_count":{"type":"integer"}}},"StateList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StateRef"}}}},"CityList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CityRef"}}}},"AmenityList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AmenityRef"}}}},"BuilderList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BuilderRef"}}}},"LeadReceipt":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["received"]}}}}}}