openapi: 3.1.0
info:
  title: API de Imóveis — Independence Negócios Imobiliários
  version: "1.0.0"
  summary: Leitura dos imóveis anunciados pela Independence, para portais parceiros.
  description: |
    API **somente leitura**. Devolve apenas os imóveis anunciados (publicados no
    site e com status Disponível, Reservado ou Em negociação) e **nenhum dado
    pessoal**.

    A credencial é emitida pela Independence e enviada no header
    `Authorization: Bearer <token>`. Guias, fluxo de sincronização e exemplos:
    https://docs.independenceimoveis.com.br
  contact:
    name: Independence Negócios Imobiliários
    url: https://www.independenceimoveis.com.br
servers:
  - url: https://admin.independenceimoveis.com.br/api/v1
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Imóveis
paths:
  /imoveis:
    get:
      tags: [Imóveis]
      operationId: listarImoveis
      summary: Listar imóveis anunciados
      description: |
        Lista paginada por **cursor**, em ordem estável por `id`.

        - **Varredura completa** (sem `alterados_desde`): só imóveis anunciados.
          Um imóvel que estava na cópia do portal e não aparece na varredura
          completa saiu do ar.
        - **Incremental** (`alterados_desde`): tudo o que foi criado ou
          alterado desde o instante, **inclusive** os que deixaram de ser
          anunciados — esses vêm como `{ "publicado": false }`.

        `proximo_cursor` só vem preenchido quando existe outra página com
        dados; `null` significa fim. Uma página intermediária nunca vem vazia.
      parameters:
        - name: por_pagina
          in: query
          description: Itens por página.
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: cursor
          in: query
          description: Valor de `proximo_cursor` da página anterior.
          schema: { type: string, format: uuid }
        - name: alterados_desde
          in: query
          description: |
            ISO 8601 **com fuso**. Ex.: `2026-10-15T14:30:00-03:00` ou
            `2026-10-15T17:30:00Z`. Em URLs, o `+` de fuso precisa ir como
            `%2B` — prefira `Z` ou `-03:00`.
          schema: { type: string, format: date-time }
      responses:
        "200":
          description: Página de imóveis.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ListagemImoveis" }
        "400": { $ref: "#/components/responses/ParametroInvalido" }
        "401": { $ref: "#/components/responses/NaoAutenticado" }
        "429": { $ref: "#/components/responses/LimiteExcedido" }
        "500": { $ref: "#/components/responses/FalhaTemporaria" }
  /imoveis/{id}:
    get:
      tags: [Imóveis]
      operationId: obterImovel
      summary: Detalhe de um imóvel
      description: Mesmos campos da listagem. `404` se o imóvel não existe ou não está anunciado.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: O imóvel.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Imovel" }
        "400": { $ref: "#/components/responses/ParametroInvalido" }
        "401": { $ref: "#/components/responses/NaoAutenticado" }
        "404":
          description: Imóvel inexistente ou não anunciado.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Erro" }
        "429": { $ref: "#/components/responses/LimiteExcedido" }
  /imoveis/removidos:
    get:
      tags: [Imóveis]
      operationId: listarRemovidos
      summary: Imóveis excluídos do cadastro
      description: |
        Exclusões físicas desde o instante. Despublicar ou inativar **não** é
        exclusão — esses aparecem no incremental de `/imoveis` com
        `publicado: false`. Exclusão é rara.
      parameters:
        - name: desde
          in: query
          required: true
          description: ISO 8601 com fuso.
          schema: { type: string, format: date-time }
      responses:
        "200":
          description: Exclusões no período.
          content:
            application/json:
              schema:
                type: object
                required: [dados]
                properties:
                  dados:
                    type: array
                    items:
                      type: object
                      required: [id, codigo, removido_em]
                      properties:
                        id: { type: string, format: uuid }
                        codigo: { type: string, example: AP0042 }
                        removido_em: { type: string, format: date-time }
        "400": { $ref: "#/components/responses/ParametroInvalido" }
        "401": { $ref: "#/components/responses/NaoAutenticado" }
        "429": { $ref: "#/components/responses/LimiteExcedido" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Credencial emitida pela Independence. Nunca envie o token na URL.
  responses:
    ParametroInvalido:
      description: Parâmetro inválido.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Erro" }
          example: { mensagem: "Parâmetro inválido: por_pagina." }
    NaoAutenticado:
      description: Credencial ausente, inválida ou revogada.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Erro" }
          example: { mensagem: "Credencial inválida." }
    LimiteExcedido:
      description: Mais de 120 requisições por minuto nesta credencial.
      headers:
        Retry-After:
          description: Segundos até poder tentar de novo.
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Erro" }
    FalhaTemporaria:
      description: Falha temporária. Tente novamente.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Erro" }
  schemas:
    Erro:
      type: object
      required: [mensagem]
      properties:
        mensagem: { type: string }
    ListagemImoveis:
      type: object
      required: [dados, por_pagina, proximo_cursor, total]
      properties:
        dados:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/Imovel"
              - $ref: "#/components/schemas/ImovelRetirado"
        por_pagina: { type: integer, example: 50 }
        proximo_cursor:
          type: [string, "null"]
          format: uuid
          description: Envie em `cursor` para a próxima página. `null` = fim.
        total:
          type: [integer, "null"]
          description: Total do filtro inteiro (não só desta página).
          example: 1526
    ImovelRetirado:
      type: object
      description: Só no incremental — imóvel que deixou de ser anunciado.
      required: [id, codigo, publicado, atualizado_em]
      properties:
        id: { type: string, format: uuid }
        codigo: { type: string, example: AP0042 }
        publicado: { const: false }
        atualizado_em: { type: [string, "null"], format: date-time }
    Foto:
      type: object
      required: [url, ordem, principal]
      properties:
        url:
          type: string
          format: uri
          description: HTTPS público, estável, com marca d'água.
          example: https://img.independenceimoveis.com.br/properties/AP0042/wm/a.webp
        ordem: { type: integer, minimum: 1 }
        principal: { type: boolean, description: Exatamente uma por imóvel. }
    Imovel:
      type: object
      description: Todos os campos estão sempre presentes; `null` = não informado ou não se aplica.
      required:
        - id
        - codigo
        - publicado
        - tipo
        - categoria
        - finalidade
        - status_comercial
        - lancamento
        - titulo
        - descricao
        - logradouro
        - numero
        - complemento
        - bairro
        - cidade
        - uf
        - cep
        - latitude
        - longitude
        - exibir_endereco
        - valor_venda
        - valor_aluguel
        - valor_condominio
        - valor_iptu
        - periodicidade_iptu
        - ocultar_preco
        - aceita_financiamento
        - aceita_permuta
        - mobiliado
        - quartos
        - suites
        - banheiros
        - vagas
        - area_util
        - area_total
        - nome_condominio
        - caracteristicas
        - fotos
        - video_url
        - tour_virtual_url
        - criado_em
        - atualizado_em
      properties:
        id: { type: string, format: uuid, description: Imutável, nunca reutilizado. }
        codigo: { type: string, example: AP0042, description: Código comercial do imóvel. }
        publicado: { const: true }
        tipo:
          type: [string, "null"]
          description: Ver valores em "Campos e valores".
          example: Apartamento
        categoria: { type: [string, "null"], enum: [Residencial, Comercial, null] }
        finalidade: { type: [string, "null"], enum: [Venda, Locação, Venda e Locação, null] }
        status_comercial: { type: [string, "null"], enum: [Disponível, Reservado, Em negociação, null] }
        lancamento: { type: boolean }
        titulo: { type: string }
        descricao: { type: [string, "null"], description: Texto puro (sem HTML), com quebras de linha. }
        logradouro: { type: [string, "null"], description: "`null` quando a imobiliária oculta o endereço." }
        numero: { type: "null", description: Sempre `null` — o número do imóvel não é divulgado. }
        complemento: { type: "null", description: Sempre `null`. }
        bairro: { type: [string, "null"] }
        cidade: { type: [string, "null"] }
        uf: { type: [string, "null"], example: SP }
        cep: { type: [string, "null"], description: 8 dígitos; `null` quando o endereço é ocultado. }
        latitude: { type: [number, "null"] }
        longitude: { type: [number, "null"] }
        exibir_endereco:
          type: string
          enum: [rua, bairro]
          description: "`rua` = pode mostrar rua e bairro; `bairro` = só bairro e cidade."
        valor_venda: { type: [number, "null"], description: Só em Venda / Venda e Locação. }
        valor_aluguel: { type: [number, "null"], description: Mensal; só em Locação / Venda e Locação. }
        valor_condominio: { type: [number, "null"] }
        valor_iptu: { type: [number, "null"] }
        periodicidade_iptu: { type: [string, "null"], enum: [Mensal, Anual, null] }
        ocultar_preco: { type: boolean, description: "`true` = preço sob consulta (valores vêm `null`)." }
        aceita_financiamento: { type: [boolean, "null"] }
        aceita_permuta: { type: [boolean, "null"] }
        mobiliado: { type: [string, "null"], enum: [Mobiliado, Não, null] }
        quartos: { type: [integer, "null"], description: "`0` = nenhum; `null` = não informado." }
        suites: { type: [integer, "null"] }
        banheiros: { type: [integer, "null"] }
        vagas: { type: [integer, "null"] }
        area_util: { type: [number, "null"], description: m² }
        area_total: { type: [number, "null"], description: m² }
        nome_condominio: { type: [string, "null"] }
        caracteristicas:
          type: array
          items: { type: string }
          description: Lista aberta do cadastro, sem repetição.
        fotos:
          type: array
          items: { $ref: "#/components/schemas/Foto" }
        video_url: { type: [string, "null"], format: uri, description: YouTube (`watch?v=`) do vídeo do imóvel. }
        tour_virtual_url: { type: [string, "null"] }
        criado_em: { type: [string, "null"], format: date-time }
        atualizado_em:
          type: [string, "null"]
          format: date-time
          description: Muda com qualquer alteração do imóvel (preço, status, fotos, texto…).