{"openapi":"3.1.0","info":{"title":"API ITBI Map","version":"1.0.0-pilot","description":"API REST de transações declaradas de ITBI — piloto São Paulo (capital).\n\nFranquia do piloto: 1000 unidades/mês; máx. 20 transações/página; sem excedente automático.\nUma unidade = uma página de busca, um detalhe de transação ou uma consulta de estatísticas bem-sucedida (busca vazia conta; erros, coverage e usage não contam).\n\nValores declarados de ITBI não são preços de anúncio, avaliação (AVM/laudo) nem prova de preço de fechamento. Não há cobertura nacional nem dados em tempo real; sem identificação de partes ou cadeia dominial."},"servers":[{"url":"https://api.itbimap.com.br"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Chave de API do workspace (itbimap_api_live_* ou itbimap_api_test_*). Nunca envie a chave em URL."}},"schemas":{"Error":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unknown_parameter","validation_failed","missing_authorization","invalid_key","key_revoked","key_expired","missing_scope","subscription_required","payment_pending","city_not_supported","unknown_bairro","unknown_logradouro","invalid_cursor","not_found","method_not_allowed","rate_limited","quota_exhausted","product_disabled","service_unavailable","internal_error"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}},"reset_at":{"type":"string","format":"date-time"}}},"request_id":{"type":"string"}}},"Transaction":{"type":"object","description":"Transação declarada de ITBI. Valores BRL como strings decimais; campos ausentes são null.","properties":{"public_id":{"type":"string","description":"Identificador público opaco."},"city":{"type":"string","enum":["sp-sao-paulo"]},"logradouro":{"type":["string","null"]},"numero":{"type":["string","null"]},"complemento":{"type":["string","null"]},"bairro":{"type":["string","null"]},"cep":{"type":["string","null"]},"natureza":{"type":"string","enum":["venda","cessao","heranca_doacao","permuta_outros","nao_informado"]},"natureza_oficial":{"type":["string","null"]},"valor_transacao":{"type":["string","null"],"description":"Valor declarado (BRL, string decimal). Não é preço de anúncio nem avaliação."},"valor_venal_referencia":{"type":["string","null"]},"proporcao_transmitida_pct":{"type":["string","null"]},"data_transacao":{"type":["string","null"],"format":"date"},"year":{"type":["integer","null"]},"area_construida_m2":{"type":["string","null"],"description":"Área construída declarada (IPTU), m²."},"area_terreno_m2":{"type":["string","null"]},"tipologia":{"type":["string","null"],"enum":["apartment","house","commercial","land","garage","unclassified",null]},"uso_iptu_descricao":{"type":["string","null"]},"padrao_iptu_descricao":{"type":["string","null"]}}}}},"paths":{"/v1/coverage":{"get":{"summary":"Cobertura, frescor e limitações verificadas","description":"Não consome unidades. Requer chave válida.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cobertura atual","content":{"application/json":{"example":{"data":{"cities":[{"slug":"sp-sao-paulo","min_year":2022,"max_year":2024,"last_computed_at":"2026-01-01T00:00:00.000Z"}],"methodology":"itbi-declared-v1","disclaimer":"Valores declarados de ITBI não são preços de anúncio, avaliação (AVM/laudo) nem prova de preço de fechamento. Não há cobertura nacional nem dados em tempo real; sem identificação de partes ou cadeia dominial.","limits":{"max_page_size":20,"monthly_allowance":1000,"coverage":["sp-sao-paulo"]},"limitations":["Sem cobertura nacional; piloto restrito a São Paulo (capital).","Sem dados em tempo real; atualização segue a publicação da Prefeitura.","Sem identificação de partes, matrícula ou cadeia dominial."]},"sandbox":true,"request_id":"00000000-0000-4000-8000-000000000000"}}}},"401":{"description":"Chave ausente/inválida/revogada/expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Produto desabilitado ou armazenamento indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions":{"get":{"summary":"Busca paginada de transações (filtro local obrigatório)","description":"Consome 1 unidade por página bem-sucedida (inclusive vazia). Exige `bairro` ou `logradouro`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"city","in":"query","required":true,"schema":{"type":"string","enum":["sp-sao-paulo"]}},{"name":"bairro","in":"query","schema":{"type":"string"}},{"name":"logradouro","in":"query","schema":{"type":"string"}},{"name":"numero","in":"query","schema":{"type":"string"}},{"name":"year","in":"query","schema":{"type":"integer","minimum":2015}},{"name":"tipologia","in":"query","schema":{"type":"string","enum":["apartment","house","commercial","land","garage"]}},{"name":"natureza","in":"query","schema":{"type":"string","enum":["venda","cessao","heranca_doacao","permuta_outros"]}},{"name":"area_min","in":"query","schema":{"type":"number","minimum":0}},{"name":"area_max","in":"query","schema":{"type":"number","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor opaco de paginação (next_cursor da página anterior)."}],"responses":{"200":{"description":"Página de transações","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}}},"request_id":{"type":"string"}}},"example":{"data":[{"public_id":"sbx_000001","city":"sp-sao-paulo","logradouro":"RUA EXEMPLO UM","numero":"100","complemento":"AP 1","bairro":"MOEMA","cep":"01000-000","natureza":"venda","natureza_oficial":"1.Compra e venda","valor_transacao":"250000.00","valor_venal_referencia":"180000.00","proporcao_transmitida_pct":"100.00","data_transacao":"2022-01-01","year":2022,"area_construida_m2":"40.00","area_terreno_m2":null,"tipologia":"apartment","uso_iptu_descricao":"SINTETICO SANDBOX","padrao_iptu_descricao":null}],"pagination":{"limit":20,"next_cursor":null},"sandbox":true,"request_id":"00000000-0000-4000-8000-000000000000"}}}},"400":{"description":"Parâmetro desconhecido, validação, cidade não suportada ou cursor inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente/inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem assinatura ativa, escopo ausente ou pagamento pendente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit ou franquia mensal esgotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Kill switch ou armazenamento indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions/{public_id}":{"get":{"summary":"Detalhe por identificador público opaco","description":"Consome 1 unidade em sucesso; 404 não consome.","security":[{"bearerAuth":[]}],"parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"},"example":"sbx_000001"}],"responses":{"200":{"description":"Transação","content":{"application/json":{"example":{"data":{"public_id":"sbx_000001","city":"sp-sao-paulo","logradouro":"RUA EXEMPLO UM","numero":"100","complemento":"AP 1","bairro":"MOEMA","cep":"01000-000","natureza":"venda","natureza_oficial":"1.Compra e venda","valor_transacao":"250000.00","valor_venal_referencia":"180000.00","proporcao_transmitida_pct":"100.00","data_transacao":"2022-01-01","year":2022,"area_construida_m2":"40.00","area_terreno_m2":null,"tipologia":"apartment","uso_iptu_descricao":"SINTETICO SANDBOX","padrao_iptu_descricao":null},"sandbox":true,"request_id":"00000000-0000-4000-8000-000000000000"}}}},"401":{"description":"Chave ausente/inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem assinatura ativa ou escopo ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transação não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit ou franquia esgotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/market/statistics":{"get":{"summary":"Estatísticas pré-computadas (cidade/bairro/rua × ano)","description":"Consome 1 unidade em sucesso. Amostras < 5 são suprimidas (suppressed=true).","security":[{"bearerAuth":[]}],"parameters":[{"name":"city","in":"query","required":true,"schema":{"type":"string","enum":["sp-sao-paulo"]}},{"name":"bairro","in":"query","schema":{"type":"string"}},{"name":"logradouro","in":"query","schema":{"type":"string"}},{"name":"year","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Estatísticas anuais com metadados de metodologia","content":{"application/json":{"example":{"data":{"scope":"bairro","years":[{"year":2024,"sample_size":6,"suppressed":false,"median_valor":"2162500.00","median_valor_m2_area_construida":null,"min_valor":"1825000.00","max_valor":"2387500.00"}]},"meta":{"methodology":"itbi-declared-v1","source":"ITBI declarado — Prefeitura de São Paulo","area_basis":"median_valor_m2_area_construida usa área construída declarada (IPTU), não área privativa medida.","exclusions":"Anos com amostra menor que 5 transações são suprimidos (suppressed=true).","disclaimer":"Valores declarados de ITBI não são preços de anúncio, avaliação (AVM/laudo) nem prova de preço de fechamento. Não há cobertura nacional nem dados em tempo real; sem identificação de partes ou cadeia dominial."},"sandbox":true,"request_id":"00000000-0000-4000-8000-000000000000"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente/inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sem assinatura ativa ou escopo ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bairro/logradouro desconhecido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit ou franquia esgotada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"summary":"Uso do período corrente (ledger autoritativo)","description":"Não consome unidades.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Contadores do período","content":{"application/json":{"example":{"data":{"period":"2026-09","allowance":1000,"consumed":42,"reserved":0,"remaining":958,"resets_at":"2026-10-01T00:00:00.000Z","subscription":{"state":"active","current_period_end":"2026-10-22T00:00:00.000Z"}},"request_id":"00000000-0000-4000-8000-000000000000"}}}},"401":{"description":"Chave ausente/inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Ledger indisponível (fail closed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}