{ "openapi": "3.1.0", "info": { "title": "Estima Bem · API nacional", "version": "2.2.0", "description": "Estimativa inicial por área × média municipal de anúncios para apartamentos nas 56 cidades cobertas; comparáveis locais opcionais têm prioridade quando elegíveis. Mesma autenticação da v1. Corpo máximo de 16 KiB." }, "servers": [ { "url": "/" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v2/coverage": { "get": { "operationId": "coverage", "summary": "Cobertura e referência municipal", "parameters": [ { "name": "municipalityCode", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{7}$" } } ], "responses": { "200": { "description": "Cobertura, sem promessa de estimativa individual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } } }, "400": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/estimates": { "post": { "operationId": "estimateNational", "summary": "Calcular valor estimado do imóvel", "description": "Com 5 comparáveis elegíveis, usa a mediana local. Caso contrário, apartamentos com base de preço asking recebem aproximação pela média municipal disponível, method=municipal_reference e dispersion=null. Referência temporal é a data da fonte. Sem referência compatível, retorna insufficient_data. Não aplica média de apartamentos a casas ou terrenos. comparables e priceBasis são opcionais; detalhes de endereço são obrigatórios quando há comparáveis.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateInput" } } } }, "responses": { "200": { "description": "Valor estimado, com método e limitações explícitos, ou ausência de cobertura.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResult" } } } }, "400": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/postal": { "get": { "operationId": "postalAddress", "summary": "Consulta pública de CEP", "security": [], "description": "Consulta BrasilAPI com fallback ViaCEP. Apenas CEP é enviado aos provedores. Sucessos podem ser cacheados por até 24h; erros não são cacheados. Não verifica número da porta nem retorna coordenadas.", "parameters": [ { "name": "cep", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{8}$" } } ], "responses": { "200": { "description": "Endereço postal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostalAddress" } } } }, "400": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CEP não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Erro estruturado; consulte error.code e error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v2/property-estimates": { "post": { "operationId": "estimateProperty", "summary": "Estimar a partir dos dados extraídos de um imóvel", "description": "Integração entre servidores com Bearer. Resolve cidade/UF, código IBGE ou CEP (com ou sem hífen). Nomes de cidades são comparados por igualdade, ignorando acentos e caixa; não faz busca aproximada. CEP fornecido é consultado e conferido com município/UF. Dados conflitantes retornam 422 LOCATION_CONFLICT; indisponibilidade de CEP retorna 503 e CEP inexistente retorna 404. Campos ausentes retornam 200 needs_input com requiredFields. Área total nunca é convertida em privativa. estimated e insufficient_data usam o mesmo motor e cobertura de /api/v2/estimates. Nenhum documento é lido, nenhum dado de proprietário é necessário e nenhum cálculo é persistido. Corpo máximo de 16 KiB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyFactsInput" }, "example": { "externalId": "imovel-123", "address": { "city": "São Paulo", "state": "SP", "neighborhood": "Morumbi" }, "property": { "type": "apartment", "privateAreaM2": 100 } } } } }, "responses": { "200": { "description": "estimated: valor com método, fonte e data; needs_input: complete requiredFields; insufficient_data: sem referência compatível. Nos dois últimos casos estimate é null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyFactsResult" } } } }, "400": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CEP não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Erro estruturado em error.code, error.message e, quando disponível, error.details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Address": { "type": "object", "additionalProperties": false, "required": [ "municipalityCode" ], "properties": { "municipalityCode": { "type": "string", "pattern": "^\\d{7}$" }, "street": { "type": "string", "minLength": 3, "maxLength": 160 }, "number": { "type": "integer", "minimum": 1, "maximum": 99999 }, "neighborhood": { "type": "string", "minLength": 2, "maxLength": 160 }, "postalCode": { "type": "string", "pattern": "^\\d{8}$" } } }, "Comparable": { "type": "object", "additionalProperties": false, "required": [ "address", "propertyType", "areaM2", "areaBasis", "priceBasis", "id", "price", "date", "sourceUrl" ], "properties": { "address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "required": [ "street", "number", "neighborhood" ] } ] }, "propertyType": { "enum": [ "apartment", "house", "land" ] }, "areaM2": { "type": "number", "minimum": 15, "maximum": 20000 }, "areaBasis": { "enum": [ "private", "built", "land" ] }, "landAreaM2": { "type": "number", "minimum": 30, "maximum": 20000 }, "priceBasis": { "enum": [ "asking", "transaction" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "price": { "type": "number", "minimum": 1000, "maximum": 1000000000 }, "date": { "type": "string", "format": "date" }, "sourceUrl": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 1000 } }, "allOf": [ { "if": { "properties": { "propertyType": { "const": "apartment" } } }, "then": { "properties": { "areaBasis": { "const": "private" }, "areaM2": { "maximum": 2000 } }, "not": { "required": [ "landAreaM2" ] } } }, { "if": { "properties": { "propertyType": { "const": "house" } } }, "then": { "required": [ "landAreaM2" ], "properties": { "areaBasis": { "const": "built" }, "areaM2": { "maximum": 2000 } } } }, { "if": { "properties": { "propertyType": { "const": "land" } } }, "then": { "properties": { "areaBasis": { "const": "land" }, "areaM2": { "minimum": 30 } }, "not": { "required": [ "landAreaM2" ] } } } ] }, "EstimateInput": { "type": "object", "additionalProperties": false, "required": [ "address", "propertyType", "areaM2", "areaBasis" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "propertyType": { "enum": [ "apartment", "house", "land" ] }, "areaM2": { "type": "number", "minimum": 15, "maximum": 20000 }, "areaBasis": { "enum": [ "private", "built", "land" ] }, "landAreaM2": { "type": "number", "minimum": 30, "maximum": 20000 }, "priceBasis": { "enum": [ "asking", "transaction" ], "default": "asking" }, "comparables": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/Comparable" } } }, "allOf": [ { "if": { "properties": { "propertyType": { "const": "apartment" } } }, "then": { "properties": { "areaBasis": { "const": "private" }, "areaM2": { "maximum": 2000 } }, "not": { "required": [ "landAreaM2" ] } } }, { "if": { "properties": { "propertyType": { "const": "house" } } }, "then": { "required": [ "landAreaM2" ], "properties": { "areaBasis": { "const": "built" }, "areaM2": { "maximum": 2000 } } } }, { "if": { "properties": { "propertyType": { "const": "land" } } }, "then": { "properties": { "areaBasis": { "const": "land" }, "areaM2": { "minimum": 30 } }, "not": { "required": [ "landAreaM2" ] } } }, { "if": { "required": [ "comparables" ], "properties": { "comparables": { "minItems": 1 } } }, "then": { "properties": { "address": { "required": [ "street", "number", "neighborhood" ] } } } } ] }, "EstimateResult": { "type": "object", "required": [ "requestId", "id", "calculatedAt", "apiVersion", "modelVersion", "datasetId", "status", "estimate", "evidence", "comparables", "limitations", "address", "benchmark" ], "properties": { "requestId": { "type": "string" }, "id": { "type": "string" }, "calculatedAt": { "type": "string", "format": "date-time" }, "apiVersion": { "const": "v2" }, "modelVersion": { "type": "string" }, "datasetId": { "type": "string" }, "status": { "enum": [ "estimated", "insufficient_data" ] }, "estimate": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "value", "pricePerM2", "dispersion" ], "properties": { "value": { "type": "number" }, "pricePerM2": { "type": "number" }, "dispersion": { "type": [ "object", "null" ], "required": [ "lower", "upper", "type", "coverageProbability" ], "properties": { "lower": { "type": "number" }, "upper": { "type": "number" }, "type": { "const": "sample_interquartile" }, "coverageProbability": { "type": "null" } } } } } ] }, "benchmark": { "type": [ "object", "null" ] }, "evidence": { "type": "object", "required": [ "provided", "accepted", "minimumRequired", "spatialScope", "searchRadiusMeters", "excluded" ], "properties": { "provided": { "type": "integer" }, "accepted": { "type": "integer" }, "minimumRequired": { "enum": [ 0, 5 ] }, "spatialScope": { "enum": [ "municipality", "same_user_reported_neighborhood" ] }, "searchRadiusMeters": { "type": "null" }, "excluded": { "type": "array", "items": { "type": "object" } } } }, "comparables": { "type": "array", "items": { "type": "object" } }, "limitations": { "type": "array", "items": { "type": "object" } }, "address": { "type": "object", "required": [ "precision", "coordinates", "numberVerified" ], "properties": { "precision": { "enum": [ "municipality", "user_reported_neighborhood" ] }, "coordinates": { "type": "null" }, "numberVerified": { "const": false } } }, "method": { "enum": [ "municipal_reference", "user_supplied_comparables" ] } } }, "Coverage": { "type": "object", "required": [ "requestId", "datasetId", "municipality", "automaticPropertyValuation", "userComparablesSupported", "benchmark" ], "properties": { "requestId": { "type": "string" }, "datasetId": { "type": "string" }, "municipality": { "type": "object" }, "automaticPropertyValuation": { "enum": [ "municipal_reference", "unavailable" ] }, "userComparablesSupported": { "const": true }, "benchmark": { "type": [ "object", "null" ] }, "morumbiModelAvailable": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "requestId", "error" ], "properties": { "requestId": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "PostalAddress": { "type": "object", "required": [ "requestId", "postalCode", "municipalityCode", "municipality", "state", "street", "neighborhood", "source", "precision", "numberVerified" ], "properties": { "requestId": { "type": "string" }, "postalCode": { "type": "string", "pattern": "^\\d{8}$" }, "municipalityCode": { "type": "string" }, "municipality": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "neighborhood": { "type": "string" }, "source": { "enum": [ "brasilapi", "viacep" ] }, "precision": { "const": "postal_address" }, "numberVerified": { "const": false } } }, "PropertyFactsInput": { "type": "object", "additionalProperties": false, "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Identificador do imóvel no projeto consumidor; devolvido sem persistência." }, "address": { "type": "object", "additionalProperties": false, "properties": { "municipalityCode": { "type": "string", "pattern": "^\\d{7}$" }, "city": { "type": "string", "minLength": 2, "maxLength": 160 }, "state": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "postalCode": { "type": "string", "pattern": "^\\d{5}-?\\d{3}$" }, "street": { "type": "string", "minLength": 3, "maxLength": 160 }, "number": { "type": "integer", "minimum": 1, "maximum": 99999 }, "neighborhood": { "type": "string", "minLength": 2, "maxLength": 160 } } }, "property": { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "apartment", "house", "land" ] }, "privateAreaM2": { "type": "number", "exclusiveMinimum": 0, "maximum": 20000, "description": "Área explicitamente identificada no documento, em m²." }, "builtAreaM2": { "type": "number", "exclusiveMinimum": 0, "maximum": 20000, "description": "Área explicitamente identificada no documento, em m²." }, "landAreaM2": { "type": "number", "exclusiveMinimum": 0, "maximum": 20000, "description": "Área explicitamente identificada no documento, em m²." }, "totalAreaM2": { "type": "number", "exclusiveMinimum": 0, "maximum": 20000, "description": "Área total extraída; nunca substitui a área exigida pelo modelo." } }, "allOf": [ { "if": { "required": [ "type" ], "properties": { "type": { "const": "apartment" } } }, "then": { "properties": { "privateAreaM2": { "minimum": 15, "maximum": 2000 } } } }, { "if": { "required": [ "type" ], "properties": { "type": { "const": "house" } } }, "then": { "properties": { "builtAreaM2": { "minimum": 15, "maximum": 2000 }, "landAreaM2": { "minimum": 30 } } } }, { "if": { "required": [ "type" ], "properties": { "type": { "const": "land" } } }, "then": { "properties": { "landAreaM2": { "minimum": 30 } } } } ] }, "comparables": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/Comparable" } }, "priceBasis": { "enum": [ "asking", "transaction" ], "default": "asking" } }, "description": "Dados estruturados extraídos por outro sistema. Campos ausentes devem ser omitidos, nunca preenchidos com null, zero ou uma área diferente. Apartamento usa privateAreaM2 (15–2000), casa builtAreaM2 (15–2000) e landAreaM2 (30–20000), terreno landAreaM2 (30–20000). Não recebe PDF, texto integral, proprietário ou CPF." }, "PropertyResolution": { "type": "object", "required": [ "municipality", "source", "numberVerified", "coordinates" ], "properties": { "municipality": { "type": [ "object", "null" ], "required": [ "code", "name", "state" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" } } }, "source": { "enum": [ "ibge_registry", "brasilapi", "viacep", null ] }, "numberVerified": { "const": false }, "coordinates": { "type": "null" } } }, "RequiredPropertyField": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }, "PropertyFactsResult": { "allOf": [ { "type": "object", "required": [ "externalId", "inputVersion", "resolution", "requiredFields", "normalizedInput" ], "properties": { "externalId": { "type": [ "string", "null" ] }, "inputVersion": { "const": "property-input-1.0.0" }, "resolution": { "$ref": "#/components/schemas/PropertyResolution" }, "requiredFields": { "type": "array", "items": { "$ref": "#/components/schemas/RequiredPropertyField" } } } }, { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/EstimateResult" }, { "type": "object", "properties": { "normalizedInput": { "$ref": "#/components/schemas/EstimateInput" }, "requiredFields": { "maxItems": 0 } } } ] }, { "type": "object", "required": [ "requestId", "id", "calculatedAt", "apiVersion", "status", "currency", "estimate", "limitations" ], "properties": { "requestId": { "type": "string" }, "id": { "type": "string" }, "calculatedAt": { "type": "string", "format": "date-time" }, "apiVersion": { "const": "v2" }, "status": { "const": "needs_input" }, "currency": { "const": "BRL" }, "estimate": { "type": "null" }, "normalizedInput": { "type": "null" }, "requiredFields": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/RequiredPropertyField" } }, "limitations": { "type": "array", "items": { "type": "object" } } } } ] } ] } } } }