{ "openapi": "3.1.0", "info": { "title": "Estima Bem API", "version": "1.1.0", "description": "Estimativas exploratórias rastreáveis para integração entre servidores. Escopo inicial: apartamentos no distrito do Morumbi, área construída do IPTU. Referência fixa em julho/2026. Não grava histórico de solicitações." }, "servers": [ { "url": "/", "description": "Mesmo domínio do projeto" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/health": { "get": { "operationId": "health", "summary": "Disponibilidade e versões", "security": [], "responses": { "200": { "description": "Disponível", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "apiVersion", "modelVersion", "datasetId", "referenceDate", "trainingEnd" ], "properties": { "status": { "const": "ok" }, "apiVersion": { "const": "v1" }, "modelVersion": { "type": "string" }, "datasetId": { "type": "string" }, "referenceDate": { "type": "string", "format": "date" }, "trainingEnd": { "type": "string", "format": "date" } } } } } } } } }, "/api/v1/datasets": { "get": { "operationId": "listDatasets", "summary": "Bases, cobertura, fontes e qualidade", "responses": { "200": { "description": "Bases publicadas", "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "items" ], "properties": { "requestId": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } } } } } } }, "401": { "description": "Chave ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método não permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "API sem configuração de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/buildings": { "get": { "operationId": "listBuildings", "summary": "Pesquisar endereços disponíveis", "parameters": [ { "name": "datasetId", "in": "query", "schema": { "type": "string", "default": "sp-morumbi-2026-07-v1" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Busca em logradouro e número; ignora acentos." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Página do catálogo", "content": { "application/json": { "schema": { "type": "object", "required": [ "requestId", "items", "pagination", "datasetId" ], "properties": { "requestId": { "type": "string" }, "datasetId": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Building" } }, "pagination": { "type": "object", "required": [ "total", "limit", "offset", "nextOffset" ], "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } } } } } } } }, "400": { "description": "Paginação ou busca inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Base não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método não permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "API sem configuração de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/estimates": { "post": { "operationId": "createEstimate", "summary": "Calcular um cenário de valor", "description": "Retorna 200 tanto para estimated quanto para insufficient_data. O consumidor deve verificar status antes de usar estimate. O identificador retornado não é um registro persistido. Campos não suportados são rejeitados. Informe exatamente um: buildingId, addressId ou address. Endereço parcial/ambíguo retorna 422 ADDRESS_NEEDS_CONFIRMATION, com candidatos em error.details; fora do perímetro retorna 422 OUTSIDE_COVERAGE. Endereços de outros municípios retornam 422 ADDRESS_OUTSIDE_COVERAGE; ausentes no índice retornam 404 ADDRESS_NOT_FOUND. Nenhum desses erros contém estimativa.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateInput" }, "example": { "datasetId": "sp-morumbi-2026-07-v1", "address": { "street": "Avenida Professor Francisco Morato", "number": 2203, "municipality": "São Paulo", "state": "SP" }, "propertyType": "apartment", "areaM2": 119, "areaBasis": "iptu_built", "correctedConstructionYear": 1975, "standardCode": 22 } } } }, "responses": { "200": { "description": "Estimativa ou abstenção por insuficiência de dados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResult" }, "example": { "requestId": "example-request", "id": "example-estimate", "calculatedAt": "2026-09-05T12:00:00.000Z", "apiVersion": "v1", "modelVersion": "comparables-0.1.0", "datasetId": "sp-morumbi-2026-07-v1", "referenceDate": "2026-07-31", "trainingEnd": "2026-03-31", "addressDatasetId": "geosampa-morumbi-addresses-2026-09-v1", "resolvedAddress": { "street": "AV PROF FRANCISCO MORATO", "number": 2203, "complement": "", "municipality": "São Paulo", "state": "SP", "district": "MORUMBI", "districtCode": "54" }, "coverage": "covered", "status": "estimated", "currency": "BRL", "areaBasis": "iptu_built", "input": { "datasetId": "sp-morumbi-2026-07-v1", "address": { "street": "Avenida Professor Francisco Morato", "number": 2203, "municipality": "São Paulo", "state": "SP" }, "propertyType": "apartment", "areaM2": 119, "areaBasis": "iptu_built", "correctedConstructionYear": 1975, "standardCode": 22, "referenceDate": "2026-07-31" }, "location": { "longitude": -46.71973118402003, "latitude": -23.58576263849579, "precision": "condominium_lot_centroid" }, "limitations": [ { "code": "IPTU_AREA_ONLY", "message": "A área construída do IPTU inclui quota de áreas comuns e não equivale à área privativa." }, { "code": "FROZEN_REFERENCE", "message": "Referência em julho/2026, com comparáveis até março/2026. Não é uma atualização para a data da requisição." }, { "code": "EXPLORATORY_MODEL", "message": "Modelo exploratório; faixa ampla e validação retrospectiva em amostra pequena." }, { "code": "MISSING_UNIT_ATTRIBUTES", "message": "Conservação, condomínio mensal, andar, vista e vagas não são avaliados." }, { "code": "DECLARED_PRICE", "message": "Os preços são declarados no ITBI, sem confirmação independente de cada negociação." }, { "code": "LOT_LOCATION", "message": "Localização pelo centro do lote condominial. Perímetro de busca em linha reta, limitado à amostra do distrito do Morumbi." }, { "code": "SCENARIO_WITHOUT_UNIT_ID", "message": "Cenário sem identificação da unidade; seu histórico específico não foi excluído. Informe unitSql para excluí-lo." } ], "estimate": { "value": 480000, "pricePerM2": 4033.61, "interval": { "lower": 239451.53, "upper": 962198.91, "type": "exploratory_calibrated", "nominalCoverage": 0.8, "observedTestCoverage": 0.8571428571428571 } }, "evidence": { "comparables": 7, "buildings": 4, "searchRadiusMeters": 500, "effectiveSampleSize": 4.822699181875124 }, "comparables": [ { "id": "2025:DEZ-2025:14936", "unitSql": "10139908772", "buildingId": "4697491", "address": { "street": "AV PROF FRANCISCO MORATO", "number": 2203 }, "transactionDate": "2025-12-18", "declaredPrice": 480000, "areaM2": 119, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1975, "pricePerM2": 4033.61, "distanceMeters": 0, "weight": 0.5398638201342368, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "DEZ-2025", "row": 14936 } }, { "id": "2025:DEZ-2025:10009", "unitSql": "10139910191", "buildingId": "4697491", "address": { "street": "AV PROF FRANCISCO MORATO", "number": 2203 }, "transactionDate": "2025-12-15", "declaredPrice": 460000, "areaM2": 119, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1975, "pricePerM2": 3865.55, "distanceMeters": 0, "weight": 0.5354447686194481, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "DEZ-2025", "row": 10009 } }, { "id": "2025:NOV-2025:13236", "unitSql": "10139905188", "buildingId": "4697491", "address": { "street": "AV PROF FRANCISCO MORATO", "number": 2203 }, "transactionDate": "2025-11-25", "declaredPrice": 600000, "areaM2": 119, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1975, "pricePerM2": 5042.02, "distanceMeters": 0, "weight": 0.5068946667858069, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "NOV-2025", "row": 13236 } }, { "id": "2025:DEZ-2025:17263", "unitSql": "10138200751", "buildingId": "4766661", "address": { "street": "R DOM ARMANDO LOMBARDI", "number": 390 }, "transactionDate": "2025-12-18", "declaredPrice": 350000, "areaM2": 122, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1985, "pricePerM2": 2868.85, "distanceMeters": 350, "weight": 0.17978353307759354, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "DEZ-2025", "row": 17263 } }, { "id": "2025:SET-2025:3433", "unitSql": "10140105963", "buildingId": "4657871", "address": { "street": "R JOSE JANNARELLI", "number": 302 }, "transactionDate": "2025-08-26", "declaredPrice": 545000, "areaM2": 106, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1979, "pricePerM2": 5141.51, "distanceMeters": 222, "weight": 0.16479086787875422, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "SET-2025", "row": 3433 } }, { "id": "2025:MAI-2025:1878", "unitSql": "10140105939", "buildingId": "4657871", "address": { "street": "R JOSE JANNARELLI", "number": 302 }, "transactionDate": "2025-04-30", "declaredPrice": 580000, "areaM2": 106, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1979, "pricePerM2": 5471.7, "distanceMeters": 222, "weight": 0.11926996430958685, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "MAI-2025", "row": 1878 } }, { "id": "2025:MAI-2025:16284", "unitSql": "10163000531", "buildingId": "4669519", "address": { "street": "R ENG AFFONSO BAUER", "number": 199 }, "transactionDate": "2025-05-20", "declaredPrice": 594000, "areaM2": 140, "areaBasis": "iptu_built", "standardCode": 22, "correctedConstructionYear": 1988, "pricePerM2": 4242.86, "distanceMeters": 382, "weight": 0.05040687177867449, "source": { "type": "ITBI_DECLARATION", "year": 2025, "sheet": "MAI-2025", "row": 16284 } } ] } } } }, "400": { "description": "JSON malformado ou parâmetros indevidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Base ou endereço não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método não permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo acima de 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type diferente de application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Campo fora do domínio, área privativa ou data não suportada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "API sem configuração de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/addresses": { "post": { "operationId": "resolveAddress", "summary": "Localizar endereço digitado e identificar distrito e cobertura", "description": "Consulta o índice local de condomínios do Morumbi e arredores. resolved significa correspondência única de rua e número; confira também candidates[0].coverage. needs_confirmation exige escolha explícita de um candidato antes de estimar. not_found não prova inexistência do imóvel. Até 10 candidatos por consulta; complete a rua se necessário.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInput" } } } }, "responses": { "200": { "description": "Localização, sugestões ou ausência de cobertura", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressResolution" } } } }, "400": { "description": "JSON malformado ou parâmetros indevidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente ou inválida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Método não permitido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Corpo acima de 16 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Endereço inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro interno.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "API sem configuração de clientes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Chave por projeto consumidor. Envie apenas entre servidores; não inclua em JavaScript público." } }, "schemas": { "Error": { "type": "object", "required": [ "requestId", "error" ], "properties": { "requestId": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } }, "Dataset": { "type": "object", "required": [ "datasetId", "modelVersion", "referenceDate", "areaBasis", "records", "buildings", "validation", "limitations" ], "properties": { "datasetId": { "type": "string" }, "modelVersion": { "type": "string" }, "referenceDate": { "type": "string", "format": "date" }, "trainingEnd": { "type": "string", "format": "date" }, "areaBasis": { "const": "iptu_built" }, "records": { "type": "integer" }, "buildings": { "type": "integer" }, "validation": { "type": "object" }, "limitations": { "type": "array", "items": { "$ref": "#/components/schemas/Limitation" } }, "sources": { "type": "array", "items": { "type": "object" } } } }, "Limitation": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "Building": { "type": "object", "required": [ "id", "address", "location", "sampleRecords", "availableStandards", "exampleProfile" ], "properties": { "id": { "type": "string" }, "address": { "type": "object", "required": [ "street", "number", "municipality", "district" ], "properties": { "street": { "type": "string" }, "number": { "type": "integer" }, "postalCode": { "type": "string" }, "municipality": { "type": "string" }, "district": { "type": "string" } } }, "location": { "$ref": "#/components/schemas/Location" }, "sampleRecords": { "type": "integer" }, "availableStandards": { "type": "array", "items": { "type": "integer" } }, "exampleProfile": { "type": "object" } } }, "Location": { "type": "object", "required": [ "latitude", "longitude", "precision" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "precision": { "const": "condominium_lot_centroid" } } }, "EstimateInput": { "type": "object", "additionalProperties": false, "required": [ "areaM2", "areaBasis", "correctedConstructionYear", "standardCode" ], "properties": { "datasetId": { "type": "string", "default": "sp-morumbi-2026-07-v1" }, "buildingId": { "type": "string", "description": "Identificador obtido no catálogo desta versão da base." }, "areaM2": { "type": "number", "minimum": 30, "maximum": 1000 }, "areaBasis": { "const": "iptu_built", "description": "Área construída cadastral, incluindo quota das áreas comuns." }, "correctedConstructionYear": { "type": "integer", "minimum": 1900, "maximum": 2021 }, "standardCode": { "type": "integer", "minimum": 20, "maximum": 25 }, "unitSql": { "type": "string", "pattern": "^[0-9]{11}$", "description": "Opcional. Exclui o histórico desta unidade dos comparáveis." }, "referenceDate": { "const": "2026-07-31" }, "address": { "$ref": "#/components/schemas/AddressInput" }, "addressId": { "type": "string", "description": "ID de lote retornado em candidates na busca de endereço; use após confirmação do usuário." }, "propertyType": { "const": "apartment", "default": "apartment" } }, "oneOf": [ { "required": [ "buildingId" ] }, { "required": [ "addressId" ] }, { "required": [ "address" ] } ] }, "EstimateResult": { "type": "object", "required": [ "requestId", "id", "calculatedAt", "apiVersion", "modelVersion", "datasetId", "referenceDate", "trainingEnd", "status", "currency", "areaBasis", "input", "location", "estimate", "evidence", "comparables", "limitations" ], "properties": { "requestId": { "type": "string" }, "id": { "type": "string" }, "calculatedAt": { "type": "string", "format": "date-time" }, "apiVersion": { "const": "v1" }, "modelVersion": { "type": "string" }, "datasetId": { "type": "string" }, "referenceDate": { "type": "string", "format": "date" }, "trainingEnd": { "type": "string", "format": "date" }, "status": { "enum": [ "estimated", "insufficient_data" ] }, "currency": { "const": "BRL" }, "areaBasis": { "const": "iptu_built" }, "input": { "$ref": "#/components/schemas/EstimateInput" }, "location": { "$ref": "#/components/schemas/Location" }, "estimate": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "value", "pricePerM2", "interval" ], "properties": { "value": { "type": "number" }, "pricePerM2": { "type": "number" }, "interval": { "type": "object", "required": [ "lower", "upper", "type", "nominalCoverage", "observedTestCoverage" ], "properties": { "lower": { "type": "number" }, "upper": { "type": "number" }, "type": { "const": "exploratory_calibrated" }, "nominalCoverage": { "type": "number" }, "observedTestCoverage": { "type": "number" } } } } } ] }, "reason": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "evidence": { "type": "object", "required": [ "comparables", "buildings" ], "properties": { "comparables": { "type": "integer" }, "buildings": { "type": "integer" }, "searchRadiusMeters": { "type": "number" }, "effectiveSampleSize": { "type": "number" } } }, "comparables": { "type": "array", "items": { "$ref": "#/components/schemas/Comparable" } }, "limitations": { "type": "array", "items": { "$ref": "#/components/schemas/Limitation" } }, "addressDatasetId": { "type": "string" }, "resolvedAddress": { "type": "object" }, "coverage": { "const": "covered" } } }, "Comparable": { "type": "object", "required": [ "id", "unitSql", "buildingId", "address", "transactionDate", "declaredPrice", "areaM2", "areaBasis", "standardCode", "correctedConstructionYear", "pricePerM2", "distanceMeters", "weight", "source" ], "properties": { "id": { "type": "string" }, "unitSql": { "type": "string" }, "buildingId": { "type": "string" }, "address": { "type": "object" }, "transactionDate": { "type": "string", "format": "date" }, "declaredPrice": { "type": "number" }, "areaM2": { "type": "number" }, "areaBasis": { "const": "iptu_built" }, "standardCode": { "type": "integer" }, "correctedConstructionYear": { "type": "integer" }, "pricePerM2": { "type": "number" }, "distanceMeters": { "type": "number" }, "weight": { "type": "number" }, "source": { "type": "object", "required": [ "type", "year", "sheet", "row" ], "properties": { "type": { "const": "ITBI_DECLARATION" }, "year": { "type": "integer" }, "sheet": { "type": "string" }, "row": { "type": "integer" } } } } }, "AddressInput": { "type": "object", "additionalProperties": false, "required": [ "street", "number", "municipality", "state" ], "properties": { "street": { "type": "string", "minLength": 3, "maxLength": 160, "description": "Nome da rua ou avenida, sem número. Aceita abreviações." }, "number": { "type": "integer", "minimum": 1, "maximum": 99999 }, "municipality": { "type": "string", "description": "Cobertura atual: São Paulo." }, "state": { "type": "string", "description": "Cobertura atual: SP." } } }, "AddressCandidate": { "type": "object", "required": [ "id", "address", "location", "coverage" ], "properties": { "id": { "type": "string" }, "address": { "type": "object", "required": [ "street", "number", "district", "municipality", "state" ], "properties": { "street": { "type": "string" }, "number": { "type": "integer" }, "complement": { "type": "string" }, "district": { "type": "string" }, "districtCode": { "type": "string" }, "municipality": { "type": "string" }, "state": { "type": "string" } } }, "location": { "$ref": "#/components/schemas/Location" }, "coverage": { "enum": [ "covered", "outside_coverage" ] } } }, "AddressResolution": { "type": "object", "required": [ "requestId", "status", "message", "candidates", "addressDatasetId", "source", "extractedOn" ], "properties": { "requestId": { "type": "string" }, "status": { "enum": [ "resolved", "needs_confirmation", "not_found", "outside_coverage" ] }, "message": { "type": "string" }, "addressDatasetId": { "type": "string" }, "source": { "type": "string" }, "extractedOn": { "type": "string", "format": "date" }, "match": { "enum": [ "exact_normalized", "multiple_lots", "partial_street" ] }, "totalCandidates": { "type": "integer" }, "candidates": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AddressCandidate" } } } } } } }