API de Fundos Imobiliários (FII): Dividendos e Cotações em Python

Por que FIIs precisam de API específica

Fundos imobiliários são regulados pela CVM, inicialmente sob a Instrução CVM 472/2008 e, a partir de outubro de 2023, sob a Resolução CVM 175/2022, que unificou o regime de fundos estruturados. Cada FII publica mensalmente um informe de gestão com patrimônio líquido, distribuição por cota e detalhes operacionais (vacância, carteira de recebíveis, laudo de reavaliação). Esses informes ficam no repositório da CVM em formatos CSV e XML que mudam entre versões, exigindo parsing cuidadoso.

O preço da cota, por outro lado, está no COTAHIST da B3, marcado pelo código BDI 12 (que identifica fundos imobiliários). A combinação preço-atual × patrimônio-por-cota-do-último-informe é o que gera o P/VP. A distribuição mensal dividida pelo preço atual, acumulada em 12 meses, gera o dividend yield. Calcular isso na mão para 400+ tickers exige pipeline próprio: a API resolve com uma única requisição HTTP.

Indicadores principais de FIIs (P/VP, DY, vacância, último rendimento)

Quatro indicadores dominam qualquer análise rápida de fundo imobiliário.

P/VP (Preço sobre Valor Patrimonial)

Razão entre a cotação e o patrimônio líquido por cota (book value per share). Um P/VP de 0,95 indica que a cota é negociada 5% abaixo do valor patrimonial apurado no último informe. Em fundos de tijolo, esse valor reflete o laudo de avaliação dos imóveis; em fundos de recebíveis, reflete a marcação dos CRIs (Certificados de Recebíveis Imobiliários) em curva ou a mercado. Fundos saudáveis costumam transitar entre 0,85 e 1,05.

Dividend Yield (DY)

Soma das distribuições mensais dos últimos 12 meses dividida pelo preço atual da cota. FIIs brasileiros tipicamente entregam entre 7% e 12% ao ano. A obrigação regulamentar de distribuir no mínimo 95% do resultado semestral (na prática, em caixa mensal) é o que torna o yield fii historicamente previsível, superior ao observado em ações comparáveis.

Último rendimento

Valor em R$ por cota distribuído no mês mais recente. Serve para antecipar o fluxo de caixa do próximo pagamento e comparar com médias móveis trimestrais. Mudanças bruscas (queda de 30% em um mês sem motivo sazonal) são o primeiro sinal para investigar vacância, inadimplência ou reajuste de contratos.

Vacância (fundos de tijolo)

Percentual de área bruta locável (ABL) desocupada. Aplicável a fundos de logística, lajes corporativas e shoppings. Vacância acima de 15% em um fundo de lajes corporativas frequentemente reflete contratos em renegociação ou retração econômica regional. Em logística, o número costuma ser menor (tipicamente abaixo de 5%) por conta da alta demanda pós-2020.

Segmentos de FIIs com exemplos e DY típico

A diversificação por segmento é a base de qualquer carteira fii api. Cada categoria reage a drivers macroeconômicos distintos: juros, inflação, consumo, dinâmica imobiliária regional. A tabela a seguir resume segmentos, exemplos de tickers líquidos e bandas de dividend yield observadas em janelas de 12 meses.

Endpoint /fiis/{ticker}: dados fundamentalistas

O endpoint /fiis/{ticker} da bolsai retorna, em uma única resposta JSON, o conjunto de dados consolidados do último informe mensal cruzado com a cotação do pregão mais recente. Campos disponíveis: close_price, book_value_per_share, pvp, dividend_yield_ttm, net_asset_value, shares_outstanding, total_shareholders, segment e management_type. A documentação completa dos campos está em /docs.

Exemplo mínimo em Python usando httpx para buscar os dados de HGLG11, fundo de logística gerido pela CSHG com cerca de 1,8 milhão de m² de ABL:

import httpx

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# Fundamentos do HGLG11 (logística)
r = httpx.get(f"{BASE}/fiis/HGLG11", headers=HEADERS)
fii = r.json()

print(f"Ticker:            {fii['ticker']}")
print(f"Nome:              {fii['name']}")
print(f"Segmento:          {fii['segment']}")
print(f"Cotação:           R$ {fii['close_price']:.2f}")
print(f"VP por cota:       R$ {fii['book_value_per_share']:.2f}")
print(f"P/VP:              {fii['pvp']}")
print(f"DY TTM:            {fii['dividend_yield_ttm']}%")
print(f"Patrimônio líq.:   R$ {fii['net_asset_value']:,.0f}")
print(f"Cotistas:          {fii['total_shareholders']:,}")

Saída aproximada em 2026-04-01:

Ticker:            HGLG11
Nome:              CSHG LOGISTICA FII
Segmento:          Logistica
Cotação:           R$ 163.85
VP por cota:       R$ 172.10
P/VP:              0.95
DY TTM:            8.92%
Patrimônio líq.:   R$ 4,235,000,000
Cotistas:          285,417

A leitura é direta: o HGLG11 negocia com leve desconto patrimonial (P/VP 0,95), entrega DY de 8,92% no acumulado de 12 meses e mantém base de quase 286 mil cotistas. Substituindo o ticker na URL (/fiis/MXRF11, /fiis/KNRI11, /fiis/XPLG11), o mesmo payload é retornado para qualquer fundo listado. Tickers sem o sufixo 11 são normalizados automaticamente pela API.

Histórico de rendimentos com /fiis/{ticker}/distributions

Medir consistência exige histórico. O endpoint /fiis/{ticker}/distributions retorna a série mensal de distribuições por cota, o dividend yield TTM consolidado e um resumo anual. O parâmetro years controla a janela retroativa. O uso natural é avaliar se o fundo sustenta distribuição estável ao longo dos ciclos.

import httpx

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# Histórico de 3 anos de distribuições do MXRF11 (recebíveis)
r = httpx.get(
    f"{BASE}/fiis/MXRF11/distributions",
    params={"years": 3},
    headers=HEADERS,
)
data = r.json()

print(f"DY TTM:            {data['dividend_yield_ttm']}%")
print(f"Total 12m/cota:    R$ {data['ttm_per_share']:.4f}")
print(f"Total de meses:    {data['total_payments']}")

for year in data["annual_summary"]:
    print(f"  {year['year']}: R$ {year['total_per_share']:.4f}  ({year['payments']} meses)")

# Medir consistência: maior queda mês a mês nos últimos 12 pagamentos
recentes = data["payments"][:12]
variacoes = [
    (recentes[i]["value_per_share"] / recentes[i+1]["value_per_share"] - 1) * 100
    for i in range(len(recentes) - 1)
]
print(f"Maior queda mensal: {min(variacoes):.1f}%")

Saída aproximada em 2026-04-01:

DY TTM:            11.04%
Total 12m/cota:    R$ 1.1440
Total de meses:    36
  2026: R$ 0.3780  (3 meses)
  2025: R$ 1.1340  (12 meses)
  2024: R$ 1.0860  (12 meses)
Maior queda mensal: -5.2%

O MXRF11, um dos maiores fundos de recebíveis do Brasil em número de cotistas, entrega aqui um DY TTM acima de 11%, pagamento mensal sem interrupções e maior queda mensal contida em 5,2%. Fundos de recebíveis com CRIs indexados a IPCA costumam ter essa volatilidade limitada enquanto a inflação está próxima da banda central do BCB.

Montando uma carteira diversificada de FIIs via código

Diversificação setorial é o principal mecanismo de controle de risco em uma carteira de FIIs. Com a API, o investidor pode construir uma carteira programaticamente, alocando pesos por segmento e recuperando todos os indicadores em uma única rodada. O padrão reutilizável é uma lista de tickers agrupados por segmento, seguida de uma chamada ao endpoint /fiis/{ticker} para cada um.

import httpx

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# Alocação alvo por segmento
carteira = {
    "HGLG11": 0.25,   # logistica
    "XPLG11": 0.10,   # logistica
    "HGRE11": 0.15,   # lajes corporativas
    "XPML11": 0.15,   # shoppings
    "MXRF11": 0.15,   # recebiveis
    "KNCR11": 0.10,   # recebiveis
    "KNRI11": 0.10,   # fundo de fundos
}

dy_ponderado = 0.0
for ticker, peso in carteira.items():
    r = httpx.get(f"{BASE}/fiis/{ticker}", headers=HEADERS)
    d = r.json()
    dy_ponderado += (d["dividend_yield_ttm"] or 0) * peso
    print(
        f"{ticker:6} peso={peso:>5.0%}  "
        f"P/VP={d['pvp']:>4}  DY={d['dividend_yield_ttm']:>5.2f}%  "
        f"{d['segment']}"
    )

print(f"\nDY ponderado da carteira: {dy_ponderado:.2f}%")

O DY ponderado resume o rendimento esperado em caixa. O mesmo padrão serve para calcular P/VP médio ponderado e exposição por segmento, substituindo a acumulação de dividend_yield_ttm pelos outros campos. Um pipeline de rebalanceamento completo, com histórico e controle de concentração, está documentado em como montar uma carteira de dividendos com Python.

Screening: encontrar FIIs com DY alto e P/VP razoável

O endpoint /screener filtra o universo completo por sufixos _gt e _lt. Para FIIs, a combinação mais usada é DY mínimo com teto de P/VP, eliminando fundos caros e fundos sem histórico. Um filtro comum: DY acima de 9% e P/VP abaixo de 1,0, ordenado por dividend yield. Esse é o ponto de partida típico para uma análise de oportunidade.

import httpx

API_KEY = "sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# Top 10 FIIs com DY > 9% e P/VP < 1.1
r = httpx.get(
    f"{BASE}/screener",
    params={
        "dividend_yield_gt": 9,
        "pvp_max": 1.1,
        "sort": "dividend_yield",
        "order": "desc",
        "limit": 10,
    },
    headers=HEADERS,
)

for fii in r.json()["data"]:
    print(
        f"{fii['ticker']:7}  DY={fii['dividend_yield']:>5.2f}%  "
        f"P/VP={fii['pvp']:>4}  {fii.get('sector', '')}"
    )

Saída aproximada em 2026-04-01:

MXRF11   DY=11.04%  P/VP= 1.00  Recebiveis
CPTS11   DY=10.78%  P/VP= 0.97  Recebiveis
KNCR11   DY=10.45%  P/VP= 1.02  Recebiveis
HGLG11   DY= 8.92%  P/VP= 0.95  Logistica (descartado: DY < 9)
VGIP11   DY= 9.84%  P/VP= 0.92  Recebiveis
RBRR11   DY= 9.62%  P/VP= 0.95  Recebiveis
...

Os retornos tendem a se concentrar em recebíveis (por conta do DY estruturalmente mais alto). Um screener mais balanceado costuma adicionar filtro de segmento ou combinar dois filtros separados para equilibrar tijolo e papel. A leitura do P/VP também merece a seção P/VP via API em Python para contexto sobre quando o desconto patrimonial indica oportunidade real.

Tributação de FIIs: dividendos isentos e ganho de capital

A tributação de FIIs tem duas dimensões distintas, e errar a leitura de qualquer uma distorce o cálculo de retorno líquido.

Rendimentos mensais (isenção de IR para PF)

A Lei 11.196/2005 instituiu a isenção de Imposto de Renda sobre os rendimentos distribuídos por fundos imobiliários a pessoas físicas, desde que três condições sejam atendidas cumulativamente: (1) o fundo tenha no mínimo 50 cotistas, (2) seja negociado exclusivamente em bolsa ou mercado de balcão organizado, e (3) o cotista beneficiário detenha menos de 10% das cotas totais. A esmagadora maioria dos FIIs listados na B3 atende aos três critérios, o que torna a isenção a regra prática para o investidor pessoa física.

Ganho de capital em alienação de cotas (20%)

A venda de cotas com lucro é tributada em 20%, recolhida via DARF até o último dia útil do mês subsequente à operação. Diferente das ações, não existe faixa de isenção mensal de R$ 20 mil para FIIs. O recolhimento é responsabilidade do próprio investidor, com compensação de prejuízos permitida apenas entre operações com cotas de FII. Qualquer simulador de rentabilidade precisa separar o fluxo de rendimento (bruto = líquido, na regra atual) do fluxo de ganho de capital (bruto × 0,80 após IR).

Limitações: vacância, inadimplência em recebíveis, liquidez

A estabilidade aparente do rendimento mensal pode mascarar três riscos recorrentes no universo dos fundos imobiliários.

Vacância alta em fundos de tijolo

Fundos de lajes corporativas em ciclos de retração (crise de 2015–2016, pandemia 2020–2021) registraram vacância acima de 20%, com impacto direto na distribuição. O informe mensal da CVM publica vacância física e financeira, e a API preserva o campo em campos dedicados para fundos de tijolo. Monitorar vacância trimestre a trimestre é obrigatório em qualquer carteira com exposição relevante ao segmento.

Inadimplência em fundos de recebíveis

Fundos de CRI operam com risco de crédito corporativo ou residencial. Eventos de default relevantes em CRIs concentrados podem derrubar o DY em 20% ou 30% em um único mês, com efeito prolongado caso a recuperação judicial se arraste. O histórico de pagamentos mensais do endpoint /fiis/{ticker}/distributions é a forma mais direta de detectar a deterioração, observando quedas abruptas antes que o mercado precifique integralmente.

Liquidez em fundos pequenos

Fundos com patrimônio inferior a R$ 200 milhões ou menos de 20 mil cotistas frequentemente apresentam volume diário inferior a R$ 500 mil. Isso amplifica o spread bid-ask e gera distorção entre o preço de tela e o preço executável. Cruzar shares_outstanding e total_shareholders do endpoint /fiis/{ticker} com o volume médio de /stocks/{ticker}/history é o caminho para quantificar esse risco antes de incluir o fundo em carteira.

Uma visão comparativa de APIs alternativas para dados de FIIs está em bolsai vs brapi, útil para quem avalia a cobertura de fundos imobiliários entre provedores antes de escolher o ponto de integração.

Perguntas frequentes

Qual FII tem o maior dividend yield?

Fundos de recebíveis (CRI) como MXRF11 e KNCR11 tipicamente apresentam os maiores DYs, frequentemente entre 10% e 13% ao ano, por distribuírem juros indexados ao IPCA e CDI. Fundos de tijolo (logística, lajes, shoppings) costumam pagar entre 6% e 9%. DY muito acima de 13% pede checagem de inadimplência, marcação a mercado dos CRIs e sustentabilidade da distribuição — o número isolado não indica oportunidade sem análise do passivo da carteira do fundo.

Dividendos de FII são tributados?

Os rendimentos distribuídos por FIIs são isentos de Imposto de Renda para pessoa física, desde que o fundo possua no mínimo 50 cotistas, seja negociado em bolsa e o cotista detenha menos de 10% das cotas. A isenção está prevista na Lei 11.196/2005. Ganho de capital em venda de cotas é tributado em 20%, sem a faixa de isenção aplicada às ações. Pessoa jurídica segue regra diferente, tributando os rendimentos como receita financeira.

P/VP abaixo de 1 significa que o FII está barato?

Não necessariamente. P/VP abaixo de 1 indica que o mercado precifica a cota abaixo do valor patrimonial apurado no último laudo, o que pode refletir vacância elevada, inadimplência em recebíveis, gestão questionada ou expectativa de queda no resultado futuro. P/VP isolado é insuficiente: é preciso avaliar vacância, perfil dos locatários, prazo de contratos e histórico de distribuição antes de concluir se há desconto real. A interpretação completa do indicador está em P/VP via API em Python.

Como diversificar uma carteira de FIIs?

A diversificação envolve combinar segmentos com comportamentos distintos: logística (HGLG11, XPLG11) oferece contratos longos; lajes corporativas (HGRE11, BRCR11) são sensíveis à vacância; shoppings (XPML11, VISC11) acompanham consumo; recebíveis (CPTS11, MXRF11) protegem contra inflação; fundos de fundos (KNRI11) entregam diversificação embutida. Pesos entre 15% e 25% por segmento limitam concentração. O conjunto de passos de construção e rebalanceamento aparece detalhado em dividend yield via API.

Leia também

Este conteúdo é educacional e não constitui recomendação de investimento. Os valores citados (DY, P/VP, cotação, vacância) são aproximações observadas em 01 de abril de 2026 e variam com o tempo. A tributação de FIIs depende de condições específicas do fundo e do cotista; consulte um assessor credenciado ou contador antes de decidir aportes ou rebalanceamentos.

Acesse dados de FIIs via API

A bolsai consolida dados de 400+ fundos imobiliários listados na B3 com P/VP, DY TTM, histórico de distribuições mensais, patrimônio líquido, número de cotistas e segmento. O plano gratuito libera 200 requisições por dia, suficiente para prototipar screening, carteira fii api e dashboards. O plano Pro (R$ 49/mês) aumenta o limite, libera histórico completo e desbloqueia o /screener. Preços detalhados em /#pricing.