{
  "openapi": "3.1.0",
  "info": {
    "title": "Estima Bem — imóveis, 24 famílias",
    "version": "3.0.0",
    "description": "Fatos documentais, áreas separadas e referências públicas progressivas: empreendimento, bairro, município, regiões IBGE, UF, grande região e amostra nacional disponível. Valores aproximados informam âmbito, fonte, método e limitações; cobertura de encaminhamento não equivale a precisão individual validada."
  },
  "servers": [
    {
      "url": "https://estimabem.com.br"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v3/property-estimates": {
      "post": {
        "operationId": "estimatePropertyV3",
        "summary": "Avaliar fatos imobiliários",
        "description": "Cálculo síncrono sobre snapshots. Corpo máximo: 16 KiB. Sem dados de proprietários. Envie os fatos disponíveis: campos ausentes não devem ser inventados. Sem medidas comparáveis, pode retornar referência de imóvel típico, identificada por valuationScope=typical_property_reference. Consuma geographicReference e evidence.calculationMode junto ao número.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PropertyInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado com valor ou motivo estruturado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyResult"
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente/inválida"
          },
          "413": {
            "description": "Corpo excede 16 KiB"
          },
          "422": {
            "description": "Campos ou localização inválidos"
          },
          "503": {
            "description": "Integração não configurada"
          }
        }
      }
    },
    "/api/v3/coverage": {
      "get": {
        "operationId": "propertyCoverage",
        "security": [],
        "summary": "Catálogo e disponibilidade de fontes",
        "parameters": [
          {
            "name": "family",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "municipalityCode",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Famílias, áreas, métodos e existência de dados; não é uma garantia de elegibilidade individual."
          }
        }
      }
    },
    "/api/v3/property-offers": {
      "post": {
        "operationId": "propertyOffers",
        "security": [],
        "summary": "Até duas ofertas publicadas para comparação",
        "description": "Consulta pública de capturas revisadas de anúncios. Exige município e área; seleção por família, localização e tamanho. Corpo de até 16 KiB. Não é busca ao vivo nos portais e não altera o valor estimado. Não recebe URLs do visitante nem exige chave.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PropertyOffersInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "De zero a duas ofertas; pouca cobertura não é preço zero.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyOffersResult"
                }
              }
            }
          },
          "400": {
            "description": "JSON ou parâmetros inválidos"
          },
          "413": {
            "description": "Corpo excede 16 KiB"
          },
          "415": {
            "description": "Content-Type deve ser application/json"
          },
          "422": {
            "description": "Localização ou características inválidas"
          },
          "500": {
            "description": "Falha na consulta das ofertas"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "PropertyInput": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Fatos imobiliários · 24 famílias",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "address": {
            "$ref": "#/components/schemas/PropertyInput/$defs/address"
          },
          "property": {
            "$ref": "#/components/schemas/PropertyInput/$defs/property"
          },
          "priceBasis": {
            "enum": [
              "auto",
              "asking",
              "transaction"
            ]
          },
          "comparables": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/PropertyInput/$defs/comparable"
            }
          },
          "income": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "netAnnualRent": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000000000000
              },
              "capitalizationRate": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1
              },
              "source": {
                "$ref": "#/components/schemas/PropertyInput/$defs/source"
              }
            },
            "required": [
              "netAnnualRent",
              "capitalizationRate",
              "source"
            ]
          },
          "cost": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "landValue": {
                "type": "number",
                "minimum": 0,
                "maximum": 100000000000000
              },
              "replacementCost": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000000000000
              },
              "depreciationRate": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "source": {
                "$ref": "#/components/schemas/PropertyInput/$defs/source"
              }
            },
            "required": [
              "landValue",
              "replacementCost",
              "depreciationRate",
              "source"
            ]
          }
        },
        "required": [
          "address",
          "property"
        ],
        "$defs": {
          "address": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "city": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "state": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2
              },
              "municipalityCode": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "postalCode": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "street": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "neighborhood": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "complement": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "condominium": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "development": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "lot": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "block": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "unit": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "tower": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "number": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9999999
                  },
                  {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 30
                  }
                ]
              },
              "district": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              }
            }
          },
          "property": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "family": {
                "enum": [
                  "residencial_apartamento",
                  "residencial_compacto",
                  "flat_residencial",
                  "casa",
                  "casa_condominio",
                  "lote_urbano",
                  "gleba_urbana",
                  "escritorio_pequeno",
                  "escritorio_grande",
                  "loja",
                  "logistica",
                  "industrial",
                  "garagem_unidade",
                  "estacionamento",
                  "edificio_residencial",
                  "edificio_comercial",
                  "misto",
                  "rural_produtivo",
                  "chacara_lazer",
                  "florestal",
                  "hotelaria",
                  "institucional",
                  "infraestrutura",
                  "indeterminado"
                ]
              },
              "originalLabel": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              },
              "territory": {
                "enum": [
                  "urban",
                  "rural",
                  "unknown"
                ]
              },
              "constructionState": {
                "enum": [
                  "ready",
                  "under_construction",
                  "demolished",
                  "unknown"
                ]
              },
              "scope": {
                "enum": [
                  "whole_property",
                  "interest"
                ]
              },
              "unitSql": {
                "type": "string",
                "pattern": "^[0-9]{11}$"
              },
              "registryNumber": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40
              },
              "registryOffice": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "specialUse": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              },
              "privateAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "builtAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "landAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "commonAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "iptuBuiltAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "lettableAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "parkingAreaM2": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 1000000000000
              },
              "parkingSpaces": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100000
              },
              "standardCode": {
                "type": "integer",
                "minimum": 0,
                "maximum": 999
              },
              "correctedConstructionYear": {
                "type": "integer",
                "minimum": 1800,
                "maximum": 2200
              }
            },
            "required": [
              "family"
            ]
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^https://",
                "maxLength": 1500
              },
              "observedAt": {
                "type": "string",
                "format": "date"
              },
              "title": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "file": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "sheet": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              },
              "row": {
                "type": "integer",
                "minimum": 1
              }
            },
            "required": [
              "url",
              "observedAt"
            ]
          },
          "comparable": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "entityId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "buildingId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "address": {
                "$ref": "#/components/schemas/PropertyInput/$defs/address"
              },
              "property": {
                "$ref": "#/components/schemas/PropertyInput/$defs/property"
              },
              "price": {
                "type": "number",
                "exclusiveMinimum": 0,
                "maximum": 100000000000000
              },
              "currency": {
                "const": "BRL"
              },
              "priceBasis": {
                "enum": [
                  "asking",
                  "transaction"
                ]
              },
              "date": {
                "type": "string",
                "format": "date"
              },
              "source": {
                "$ref": "#/components/schemas/PropertyInput/$defs/source"
              }
            },
            "required": [
              "id",
              "entityId",
              "address",
              "property",
              "price",
              "currency",
              "priceBasis",
              "date",
              "source"
            ]
          }
        }
      },
      "PropertyResult": {
        "type": "object",
        "required": [
          "apiVersion",
          "status",
          "estimate",
          "currency",
          "referenceDate",
          "family",
          "modelVersion",
          "datasetId",
          "limitations"
        ],
        "properties": {
          "apiVersion": {
            "const": "v3"
          },
          "status": {
            "enum": [
              "estimated",
              "needs_input",
              "insufficient_data",
              "needs_review",
              "unsupported_profile",
              "processing"
            ]
          },
          "estimate": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "value"
                ],
                "properties": {
                  "value": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "dispersion": {
                    "type": [
                      "object",
                      "null"
                    ]
                  }
                },
                "additionalProperties": true
              }
            ]
          },
          "currency": {
            "const": "BRL"
          },
          "referenceDate": {
            "type": "string",
            "format": "date"
          },
          "family": {
            "enum": [
              "residencial_apartamento",
              "residencial_compacto",
              "flat_residencial",
              "casa",
              "casa_condominio",
              "lote_urbano",
              "gleba_urbana",
              "escritorio_pequeno",
              "escritorio_grande",
              "loja",
              "logistica",
              "industrial",
              "garagem_unidade",
              "estacionamento",
              "edificio_residencial",
              "edificio_comercial",
              "misto",
              "rural_produtivo",
              "chacara_lazer",
              "florestal",
              "hotelaria",
              "institucional",
              "infraestrutura",
              "indeterminado"
            ]
          },
          "modelVersion": {
            "type": "string"
          },
          "datasetId": {
            "type": "string"
          },
          "geographicReference": {
            "type": "object",
            "properties": {
              "scope": {
                "enum": [
                  "development",
                  "neighborhood",
                  "district",
                  "municipality",
                  "immediate_region",
                  "intermediate_region",
                  "state",
                  "region",
                  "national"
                ]
              },
              "label": {
                "type": "string"
              },
              "proximityMethod": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "searchRadiusMeters": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "additionalProperties": true
          },
          "valuationScope": {
            "type": "string",
            "description": "whole_property, interest, matched_property_reference, regional_reference ou typical_property_reference. Paired_area compara terreno e construção conjuntamente, sem decomposição de preço calibrada. Referência regional ou típica não é avaliação individualizada."
          },
          "quality": {
            "enum": [
              "preliminary",
              "municipal_reference",
              "regional_reference",
              "territorial_reference",
              "input_scenario"
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "estimated"
                }
              }
            },
            "then": {
              "properties": {
                "estimate": {
                  "type": "object"
                }
              }
            },
            "else": {
              "properties": {
                "estimate": {
                  "type": "null"
                }
              }
            }
          }
        ],
        "additionalProperties": true
      },
      "PropertyOffersInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "address",
          "property"
        ],
        "properties": {
          "address": {
            "$ref": "#/components/schemas/PropertyInput/properties/address"
          },
          "property": {
            "$ref": "#/components/schemas/PropertyInput/properties/property"
          }
        }
      },
      "PropertyOffersResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "apiVersion",
          "asOf",
          "currency",
          "purpose",
          "affectsEstimate",
          "maximumItems",
          "status",
          "message",
          "note",
          "location",
          "offers"
        ],
        "properties": {
          "requestId": {
            "type": "string"
          },
          "apiVersion": {
            "const": "v3"
          },
          "asOf": {
            "type": "string",
            "format": "date"
          },
          "currency": {
            "const": "BRL"
          },
          "purpose": {
            "const": "published_offer_context"
          },
          "affectsEstimate": {
            "const": false
          },
          "maximumItems": {
            "const": 2
          },
          "status": {
            "enum": [
              "available",
              "limited",
              "no_matches",
              "needs_input"
            ]
          },
          "message": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "location": {
            "type": "object",
            "required": [
              "city",
              "state",
              "neighborhood"
            ],
            "properties": {
              "city": {
                "type": "string"
              },
              "state": {
                "type": "string"
              },
              "neighborhood": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "district": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "development": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "municipalityCode": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "offers": {
            "type": "array",
            "maxItems": 2,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "title",
                "price",
                "priceBasis",
                "url",
                "publisher",
                "observedAt",
                "location",
                "measurements",
                "features",
                "comparison"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "price": {
                  "type": "number",
                  "exclusiveMinimum": 0
                },
                "priceBasis": {
                  "const": "asking"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                },
                "publisher": {
                  "type": "string"
                },
                "observedAt": {
                  "type": "string",
                  "format": "date"
                },
                "location": {
                  "type": "object",
                  "required": [
                    "city",
                    "state",
                    "neighborhood"
                  ],
                  "properties": {
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "neighborhood": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "district": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "development": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "municipalityCode": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                },
                "measurements": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "field",
                      "label",
                      "valueM2"
                    ],
                    "properties": {
                      "field": {
                        "enum": [
                          "privateAreaM2",
                          "builtAreaM2",
                          "landAreaM2",
                          "advertisedUsableAreaM2",
                          "lettableAreaM2"
                        ]
                      },
                      "label": {
                        "type": "string"
                      },
                      "valueM2": {
                        "type": "number",
                        "exclusiveMinimum": 0
                      }
                    }
                  }
                },
                "features": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "bedrooms": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "parkingSpaces": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                },
                "comparison": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "location",
                    "areaBasis",
                    "note"
                  ],
                  "properties": {
                    "location": {
                      "enum": [
                        "same_development",
                        "same_neighborhood",
                        "same_municipality"
                      ]
                    },
                    "areaBasis": {
                      "enum": [
                        "same_reported_basis",
                        "advertised_useful_area"
                      ]
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}