# Fundos Imobiliários (FIIs)
URL: /docs/fiis.mdx

Guia completo para integrar dados de FIIs na brapi: indicadores, relatórios CVM, dividendos, cotações históricas e listagem com filtros.

***

title: Fundos Imobiliários (FIIs)
description: >-
Guia completo para integrar dados de FIIs na brapi: indicadores, relatórios
CVM, dividendos, cotações históricas e listagem com filtros.
full: true
keywords: brapi, api, fii, fundos imobiliários, indicadores, dividendos, relatórios
openGraph:
title: Fundos Imobiliários (FIIs)
description: >-
Guia completo para integrar dados de FIIs na brapi, com fluxo recomendado
e exemplos de uso.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
-----------

import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A API de FIIs foi desenhada para cobrir os principais casos de uso do mercado
de fundos imobiliários brasileiros:

1. **listar** FIIs com filtros por segmento, gestão e setor
2. consultar **indicadores** atuais (P/VP, DY, vacância, patrimônio)
3. acompanhar a **evolução mensal** dos indicadores
4. pegar **cotações históricas** (OHLCV)
5. acessar **relatórios gerenciais** mensais da CVM
6. consultar o **histórico de dividendos** e rendimentos

<Callout title="O que esta API entrega" type="info">
  Indicadores fundamentalistas, relatórios mensais da CVM com composição
  patrimonial, histórico de dividendos/rendimentos, e cotações OHLCV diárias.
</Callout>

<Callout title="Diferença entre cotações básicas e dados detalhados" type="warn">
  Cotações básicas de FIIs (preço, variação) estão disponíveis em todos os
  planos via `/api/quote/MXRF11`. Os endpoints `/api/v2/fii/*` documentados
  aqui trazem **dados detalhados** e são exclusivos do plano **Pro**.
</Callout>

## Cobertura e frequência

* **Indicadores:** atualizados diariamente após o fechamento do pregão.
* **Relatórios CVM:** importados mensalmente conforme publicação pela CVM.
* **Dividendos:** consolidados a partir dos relatórios mensais.
* **Cotações históricas:** OHLCV diário, mesmo formato dos demais ativos.
* **Fuso horário:** `America/Sao_Paulo`. Campos de data em respostas seguem
  formato ISO 8601 ou timestamp Unix.
* **Formato de datas em query params:** `YYYY-MM-DD`.

## Acesso por plano

Dados detalhados de FIIs fazem parte do plano **Pro**. O sandbox permite
experimentação sem token para **MXRF11** e **HGLG11**.

| Plano               | Acesso a FIIs detalhados               |
| ------------------- | -------------------------------------- |
| Sandbox (sem token) | ✅ Apenas MXRF11 e HGLG11               |
| Free                | ❌ (cotações básicas via `/api/quote/`) |
| Startup             | ❌ (cotações básicas via `/api/quote/`) |
| **Pro**             | **✅ Todos os FIIs**                    |

## Termos que você vai ver

* **Segmento (`segmentType`):** classificação patrimonial do FII — `papel`,
  `tijolo`, `híbrido` ou `fof` (fundo de fundos).
* **Segmento de atuação (`segmentoAtuacao`):** setor do mercado imobiliário.
  Ex.: `Logística`, `Shoppings`, `Lajes Corporativas`, `Títulos e Val. Mob.`.
* **Tipo de gestão (`tipoGestao`):** `Ativa` ou `Definida` (passiva).
* **Mandato (`mandate`):** perfil de investimento — `Renda`, `Ganho de Capital`
  ou `Híbrido`.
* **P/VP (`priceToNav`):** preço de mercado dividido pelo valor patrimonial
  por cota. Abaixo de 1 indica desconto.
* **Dividend Yield (`dividendYield12m`):** rendimento dos últimos 12 meses em
  relação ao preço atual.
* **Vacância:** percentual de imóveis desocupados (relevante para FIIs de
  tijolo).
* **Relatório gerencial:** documento mensal enviado à CVM com composição
  patrimonial, rentabilidade e dados operacionais.

## Início rápido

Exemplo completo do fluxo `listagem → indicadores → dividendos` para FIIs.

<Tabs items={['cURL', 'TypeScript', 'Python']}>
  <Tab value="cURL">
    ```bash
    # 1) Liste FIIs de logística
    curl "https://brapi.dev/api/v2/fii/list?segmentoAtuacao=Logística&limit=5"

    # 2) Consulte indicadores de um FII específico
    curl "https://brapi.dev/api/v2/fii/indicators?symbols=MXRF11"

    # 3) Veja o histórico de dividendos
    curl "https://brapi.dev/api/v2/fii/dividends?symbols=MXRF11"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```typescript
    const BASE = 'https://brapi.dev/api/v2/fii';
    const token = process.env.BRAPI_TOKEN; // dispensável para MXRF11/HGLG11

    const headers = token ? { Authorization: `Bearer ${token}` } : undefined;

    // 1) Listagem com filtro por segmento
    const list = await fetch(
      `${BASE}/list?segmentoAtuacao=Logística&limit=5`,
      { headers },
    ).then((r) => r.json());

    // 2) Indicadores atuais
    const indicators = await fetch(
      `${BASE}/indicators?symbols=MXRF11,HGLG11`,
      { headers },
    ).then((r) => r.json());

    // 3) Histórico de dividendos
    const dividends = await fetch(
      `${BASE}/dividends?symbols=MXRF11`,
      { headers },
    ).then((r) => r.json());

    console.log({ list, indicators, dividends });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    BASE = "https://brapi.dev/api/v2/fii"
    token = os.getenv("BRAPI_TOKEN")  # dispensável para MXRF11/HGLG11
    headers = {"Authorization": f"Bearer {token}"} if token else {}

    # 1) Listagem com filtro por segmento
    fii_list = requests.get(
        f"{BASE}/list",
        params={"segmentoAtuacao": "Logística", "limit": 5},
        headers=headers,
    ).json()

    # 2) Indicadores atuais
    indicators = requests.get(
        f"{BASE}/indicators",
        params={"symbols": "MXRF11,HGLG11"},
        headers=headers,
    ).json()

    # 3) Histórico de dividendos
    dividends = requests.get(
        f"{BASE}/dividends",
        params={"symbols": "MXRF11"},
        headers=headers,
    ).json()

    print(fii_list, indicators, dividends)
    ```
  </Tab>
</Tabs>

## Fluxo recomendado

<Steps>
  <Step>
    #### Descubra os FIIs disponíveis

    Comece em [`/api/v2/fii/list`](/docs/fiis/listagem) para explorar FIIs com
    filtros por segmento, setor de atuação, tipo de gestão e mandato.
  </Step>

  <Step>
    #### Consulte os indicadores atuais

    Use [`/api/v2/fii/indicators`](/docs/fiis/indicadores) para ver P/VP,
    dividend yield, patrimônio, número de cotistas e dados do administrador.
  </Step>

  <Step>
    #### Acompanhe a evolução dos indicadores

    Use [`/api/v2/fii/indicators/history`](/docs/fiis/indicadores-historico)
    para montar gráficos de evolução mensal de P/VP, DY, patrimônio e outros
    indicadores.
  </Step>

  <Step>
    #### Consulte cotações históricas

    Use [`/api/v2/fii/historical`](/docs/fiis/historico) para obter OHLCV
    diário. Ideal para gráficos de preço e backtests.
  </Step>

  <Step>
    #### Acesse os relatórios da CVM

    Use [`/api/v2/fii/reports`](/docs/fiis/relatorios) para consultar os
    relatórios gerenciais mensais com composição patrimonial, rentabilidade
    e dados operacionais.
  </Step>

  <Step>
    #### Consulte o histórico de dividendos

    Use [`/api/v2/fii/dividends`](/docs/fiis/dividendos) para ver rendimentos
    e amortizações pagos ao longo do tempo.
  </Step>
</Steps>

## Casos de uso mais comuns

* **Tela de screening de FIIs:** `list` com filtros → exibir indicadores
* **Dashboard de acompanhamento:** `indicators` para dados atuais + `indicators/history` para evolução
* **Análise de dividendos:** `dividends` para histórico de rendimentos
* **Gráfico de preço:** `historical` para OHLCV diário
* **Due diligence:** `reports` para relatórios CVM + `indicators` para snapshot atual
* **Comparação entre FIIs:** `indicators` com múltiplos symbols (até 20 por request)

## Quando você pode pular etapas

* Se você **já sabe o ticker**, pode ir direto para `indicators`, `historical`,
  `dividends` ou `reports`.
* Se você quer **só listar e filtrar**, use `list` sem precisar dos outros endpoints.
* Se você quer **só dividendos**, pode ir direto para `dividends` com o ticker.

## Perguntas frequentes

<AnswerBox
  question="Qual é o plano mínimo para acessar dados detalhados de FIIs?"
  answer="Plano Pro. O sandbox sem token funciona apenas para MXRF11 e HGLG11, para você testar antes de assinar. Cotações básicas estão disponíveis em todos os planos via /api/quote/."
  relatedEndpoints={[
  { name: 'list', path: '/api/v2/fii/list' },
  { name: 'indicators', path: '/api/v2/fii/indicators' },
]}
/>

<AnswerBox question="Posso consultar vários FIIs de uma vez?" answer="Sim — os endpoints indicators, indicators/history, historical, dividends e reports aceitam até 20 símbolos separados por vírgula no parâmetro symbols." codeExample={`curl "https://brapi.dev/api/v2/fii/indicators?symbols=MXRF11,HGLG11,XPML11"`} />

<AnswerBox question="Qual a diferença entre /api/quote/MXRF11 e /api/v2/fii/indicators?" answer="O /api/quote/ retorna cotação e dados básicos (preço, variação, volume) e está disponível em todos os planos. O /api/v2/fii/indicators retorna indicadores fundamentalistas detalhados (P/VP, DY, patrimônio, vacância, dados do administrador) e é exclusivo do plano Pro." />

<AnswerBox question="Os relatórios da CVM estão completos?" answer="Sim — importamos os relatórios gerenciais mensais com composição patrimonial (CRI, LCI, imóveis, títulos públicos), rentabilidade, taxas e passivos. Use o parâmetro allVersions=true para incluir versões retificadas." />

<AnswerBox question="Quais filtros posso usar na listagem?" answer="Você pode filtrar por segmentType (papel, tijolo, híbrido, fof), segmentoAtuacao (Logística, Shoppings, etc.), mandate (Renda, Ganho de Capital, Híbrido), tipoGestao (Ativa, Definida) e busca textual (search)." />

## Receitas prontas

Guias e tutoriais publicados no blog com código pronto para copiar:

<Cards>
  <Card href="/blog/fundos-imobiliarios-fiis-guia-completo-iniciantes" title="FIIs para iniciantes" description="Entenda os tipos de FIIs, indicadores e como usar a API para análise." />

  <Card href="/blog/fundos-imobiliarios-fiis-guia-completo-investir-renda-passiva" title="FIIs para renda passiva" description="Framework de análise, diversificação e monitoramento de carteira de FIIs." />

  <Card href="/blog/fiis-de-papel-vs-tijolo-comparativo-2026" title="Papel vs Tijolo" description="Comparativo detalhado entre FIIs de papel e tijolo com dados da API." />
</Cards>

## Sandbox sem token

Para facilitar a experimentação, todos os endpoints de FIIs aceitam consultas
no sandbox sem token, restritas a **MXRF11** e **HGLG11**:

* `GET /api/v2/fii/list`: funciona sem token (listagem geral).
* `GET /api/v2/fii/indicators`, `/indicators/history`, `/historical`,
  `/reports`, `/dividends`: apenas com `symbols` contendo exclusivamente
  MXRF11 e/ou HGLG11.

Para qualquer outro FII, é necessário autenticar com um token do plano Pro.

## Endpoints

<Cards>
  <Card href="/docs/fiis/listagem" title="Listagem de FIIs" description="Liste e filtre FIIs por segmento, setor, gestão e mandato." />

  <Card href="/docs/fiis/indicadores" title="Indicadores" description="Consulte indicadores atuais: P/VP, DY, patrimônio e mais." />

  <Card href="/docs/fiis/indicadores-historico" title="Indicadores Históricos" description="Acompanhe a evolução mensal dos indicadores de FIIs." />

  <Card href="/docs/fiis/historico" title="Cotações Históricas" description="OHLCV diário para gráficos de preço e backtests." />

  <Card href="/docs/fiis/relatorios" title="Relatórios CVM" description="Relatórios gerenciais mensais com composição patrimonial." />

  <Card href="/docs/fiis/dividendos" title="Dividendos" description="Histórico de rendimentos e amortizações." />
</Cards>