{
  "openapi": "3.1.0",
  "info": {
    "title": "Imobz Public Property Search API",
    "version": "1.0.0",
    "description": "Consulta somente leitura do catálogo público da Imobz no Panamby e em São Paulo. Não agenda visitas nem acessa dados de clientes. API v1. Mudanças incompatíveis usam nova versão de rota. Descontinuações serão anunciadas com antecedência mínima de 90 dias; nenhuma programada. Alias legado /api/search permanece compatível."
  },
  "servers": [
    {
      "url": "https://www.imobz.com.br"
    }
  ],
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "searchImobzProperties",
        "summary": "Buscar imóveis públicos da Imobz",
        "description": "Use bairro, condomínio, endereço ou código do anúncio. Retorna anúncios públicos paginados. Sem autenticação. Use os canais de atendimento para visitas e propostas.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Termo de busca; use * para listar imóveis.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Página dos resultados.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Quantidade de anúncios por página.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados públicos da busca.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "found",
                    "hits"
                  ],
                  "properties": {
                    "found": {
                      "type": "integer"
                    },
                    "hits": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "document": {
                            "type": "object",
                            "description": "Campos públicos do anúncio: listing_id, title, address, neighborhood, city, price, bedrooms, living_area e primary_image.",
                            "additionalProperties": false,
                            "properties": {
                              "listing_id": {
                                "description": "Campo público do anúncio: listing_id. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "id": {
                                "description": "Campo público do anúncio: id. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "title": {
                                "description": "Campo público do anúncio: title. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "address": {
                                "description": "Campo público do anúncio: address. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "street_number": {
                                "description": "Campo público do anúncio: street_number. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "neighborhood": {
                                "description": "Campo público do anúncio: neighborhood. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "city": {
                                "description": "Campo público do anúncio: city. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "state": {
                                "description": "Campo público do anúncio: state. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "primary_image": {
                                "description": "Campo público do anúncio: primary_image. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "images": {
                                "description": "Campo público do anúncio: images. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  },
                                  {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                ]
                              },
                              "list_price": {
                                "description": "Campo público do anúncio: list_price. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "rental_price": {
                                "description": "Campo público do anúncio: rental_price. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "price": {
                                "description": "Campo público do anúncio: price. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "currency": {
                                "description": "Campo público do anúncio: currency. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "bedrooms": {
                                "description": "Campo público do anúncio: bedrooms. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "bathrooms": {
                                "description": "Campo público do anúncio: bathrooms. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "suites": {
                                "description": "Campo público do anúncio: suites. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "garage_spaces": {
                                "description": "Campo público do anúncio: garage_spaces. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "garage": {
                                "description": "Campo público do anúncio: garage. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "living_area": {
                                "description": "Campo público do anúncio: living_area. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "area_util": {
                                "description": "Campo público do anúncio: area_util. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "property_type": {
                                "description": "Campo público do anúncio: property_type. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "transaction_type": {
                                "description": "Campo público do anúncio: transaction_type. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "latitude": {
                                "description": "Campo público do anúncio: latitude. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "longitude": {
                                "description": "Campo público do anúncio: longitude. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "list_date": {
                                "description": "Campo público do anúncio: list_date. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "publication_type": {
                                "description": "Campo público do anúncio: publication_type. Valores dependem do cadastro.",
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            }
          },
          "405": {
            "description": "Método não permitido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            }
          },
          "429": {
            "description": "Limite de 200 consultas/IP/60s por instância atingido. Controle de melhor esforço, não global.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              },
              "Retry-After": {
                "description": "Segundos para aguardar antes de repetir.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "502": {
            "description": "Busca temporariamente indisponível.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            }
          },
          "504": {
            "description": "Tempo limite da busca.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Limit": {
                "description": "Consultas por IP e janela, nesta instância.",
                "schema": {
                  "type": "integer",
                  "example": 200
                }
              },
              "RateLimit-Remaining": {
                "description": "Consultas restantes nesta janela e instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Segundos até reinício da janela nesta instância.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-API-Version": {
                "description": "Versão da API.",
                "schema": {
                  "type": "string",
                  "example": "1"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}