API de FIIs: Indicadores, Carteira, Imóveis e Dividendos

A API de FIIs da brapi separa cada tipo de dado em um endpoint. Você pode listar fundos, consultar indicadores, baixar cotações, abrir a carteira declarada à CVM, medir vacância e acompanhar dividendos.

Para testar sem token, use MXRF11 ou HGLG11:

curl "https://brapi.dev/api/v2/fii/indicators?symbols=MXRF11,HGLG11"

Os dados detalhados de todos os FIIs fazem parte do plano Pro. Cotações básicas continuam disponíveis no endpoint geral de cotação.

Qual endpoint usar

A documentação de FIIs mantém os parâmetros e schemas de cada rota. Use essa página como referência do contrato.

Listar FIIs por tipo e segmento

O endpoint de listagem aceita busca, ticker, CNPJ e filtros de classificação.

curl "https://brapi.dev/api/v2/fii/list?segmentType=tijolo&segmentoAtuacao=Logística&sortBy=dividendYield12m&sortOrder=desc&limit=20"

segmentType aceita papel, tijolo, hibrido e fof. Você também pode filtrar por mandato, tipo de gestão e segmento de atuação.

O filtro ajuda a montar um universo comparável. Ordenar todos os FIIs juntos por dividend yield mistura fundos com riscos e fontes de renda diferentes.

Consultar indicadores em Python

import os
import requests
import pandas as pd

BASE = "https://brapi.dev/api/v2/fii"
TOKEN = os.getenv("BRAPI_TOKEN")
HEADERS = {"Authorization": f"Bearer {TOKEN}"} if TOKEN else {}

response = requests.get(
    f"{BASE}/indicators",
    params={"symbols": "MXRF11,HGLG11"},
    headers=HEADERS,
    timeout=30,
)
response.raise_for_status()

payload = response.json()
df = pd.DataFrame(payload["fiis"])

columns = [
    "symbol",
    "priceToNav",
    "dividendYield12m",
    "navPerShare",
    "equity",
    "totalAssets",
]

print(df[columns])

Confira o nome do array principal no schema atual de indicadores de FIIs. Os endpoints mantêm envelopes consistentes, mas cada domínio usa uma chave que descreve o resultado.

Analisar FIIs de tijolo

Para um FII de tijolo, combine três rotas:

1. /indicators para P/VP, DY e patrimônio;
2. /properties para imóveis e vacância;
3. /portfolio para a composição declarada.

curl "https://brapi.dev/api/v2/fii/properties?symbols=HGLG11"

Use referenceDate quando precisar reproduzir um trimestre específico. O parâmetro allVersions ajuda em auditorias de informes retificados.

O histórico permite observar se a vacância piorou durante vários trimestres, em vez de tirar uma conclusão a partir de um único relatório.

Analisar FIIs de papel

Nos fundos de papel, a carteira informa a exposição a CRIs, LCIs, caixa, outros FIIs e recebíveis. O relatório mensal acrescenta patrimônio, passivos, taxas e rentabilidade declarada.

curl "https://brapi.dev/api/v2/fii/reports?symbols=MXRF11&sortBy=referenceDate&sortOrder=desc&limit=12"

Para interpretar papel e tijolo sem misturar os riscos, consulte FIIs de papel vs tijolo.

Histórico de dividendos

curl "https://brapi.dev/api/v2/fii/dividends?symbols=MXRF11&startDate=2025-01-01&sortOrder=asc"

Guarde separadamente a data com direito ao rendimento e a data de pagamento. Elas não são intercambiáveis em um calendário de caixa.

FIIs não seguem um intervalo universal entre as duas datas. Evite preencher datas faltantes somando um número fixo de dias.

O tutorial de calendário de dividendos de FIIs com Python mostra como transformar os eventos em agenda.

Fluxo recomendado para um produto

Uma integração robusta pode seguir esta ordem:

1. filtre o universo em /list;
2. busque indicadores dos símbolos selecionados;
3. carregue histórico apenas na tela de detalhe;
4. consulte imóveis ou carteira conforme o tipo do FII;
5. mostre a data de referência de cada conjunto;
6. armazene relatórios retificados como versões, não como duplicatas.

Esse desenho reduz chamadas, evita misturar competências e deixa claro qual fonte sustenta cada número mostrado ao usuário.