API de FIAGRO: dados da CVM, carteira e relatórios mensais

Um FIAGRO pode ter crédito do agronegócio, imóveis rurais, participações e cotas de outros fundos. O ticker não conta essa história. Para saber onde o dinheiro está, você precisa ler o relatório mensal e a carteira declarada à CVM.

A brapi separa esses dados em dois endpoints: um acompanha o relatório ao longo do tempo, o outro abre a composição de um mês específico.

Qual endpoint usar

Veja o contrato completo na documentação de FIAGRO. Use a documentação de FIIs somente para fundos imobiliários classificados como FII.

Confirmar a família do ativo

Consulte a listagem antes de escolher a rota. O filtro assetType=fiagro retorna fundos dessa família, e a busca também aceita symbols, cnpjs, search, status e paginação.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/funds/list?assetType=fiagro&search=agro&limit=20"

Guarde symbol, cnpj e assetType. O símbolo resolve fundos listados. O CNPJ salva quando o código muda ou quando o fundo nem negocia na B3.

O final 11 engana. Ele não distingue FIAGRO de FII, e mandar um para o endpoint do outro devolve vazio. Deixe assetType escolher a rota.

Consultar relatórios mensais

/api/v2/funds/fiagro/reports aceita símbolo, CNPJ, datas, paginação e ordenação. Para auditar mudanças, allVersions traz também as versões retificadas.

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['BRAPI_TOKEN']}"}
params = {
    "symbols": "XPCA11",
    "startDate": "2026-01-01",
    "endDate": "2026-06-30",
    "sortBy": "referenceDate",
    "sortOrder": "asc",
    "limit": 100,
}

response = requests.get(
    "https://brapi.dev/api/v2/funds/fiagro/reports",
    params=params,
    headers=headers,
    timeout=30,
)
response.raise_for_status()

payload = response.json()
reports = payload["reports"]

Cada relatório descreve um período, com patrimônio, valor patrimonial por cota, cotistas, resultado e itens próprios do segmento. O schema cresce quando a CVM acrescenta campos, então selecione colunas pelo nome. Índice posicional quebra na primeira mudança regulatória.

Use referenceDate como eixo da série. requestedAt só diz quando a sua aplicação chamou a API.

Abrir a carteira do FIAGRO

/api/v2/funds/fiagro/portfolio mostra a carteira em seções: resumo, alocações, passivos e investidores. Ele aceita symbols, cnpjs, referenceDate, allVersions e include.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/funds/fiagro/portfolio?symbols=XPCA11&referenceDate=2026-06-30"

A chave principal da resposta é funds. Leia a estrutura atual no schema da carteira.

As alocações é que distinguem estratégias. Um fundo concentra tudo em CRA. Outro mistura cotas de FIDC, imóveis e participações. Os dois carregam o rótulo FIAGRO e têm quase nada em comum.

O bloco de passivos traz obrigações declaradas no documento e o de investidores mostra concentração. Nenhum dos dois substitui a leitura do regulamento e dos relatórios do gestor.

Juntar relatório e carteira

Use o mesmo fundo e a mesma data de referência. Se a carteira mais recente é de maio, não a combine com indicadores de junho sem mostrar a diferença.

def by_reference_date(items):
    return {
        item["referenceDate"]: item
        for item in items
        if item.get("referenceDate")
    }

reports_by_date = by_reference_date(reports)

A estrutura interna da carteira pode usar seções aninhadas. Não aplique a função acima sem antes selecionar a coleção que contém referenceDate.

Em produção, guarde o documento bruto e a versão normalizada. Um informe retificado altera um número antigo, e sem o original você não consegue explicar a diferença para ninguém. Ao pedir allVersions=true, marque qual versão alimenta o gráfico principal.

Comparar fundos sem perder contexto

Para participações por categoria, divida cada alocação pelo patrimônio do mesmo mês. Só faça a conta quando unidades e datas baterem.

Classificar o fundo pelo maior ativo é tentador e raso. Passivos, concentração e qualidade do crédito mudam a leitura. Dois CRAs de mesmo valor podem ter emissores, garantias e prazos que não se parecem em nada.

Tratar paginação e retificações

O endpoint de relatórios devolve pagination. Repita as chamadas enquanto existirem páginas, respeitando o limit máximo do schema.

Uma retificação pode corrigir patrimônio, cotistas ou composição. Painel ao vivo: use a versão mais recente. Auditoria: preserve todas e registre o critério.

Trate resposta vazia como resposta vazia. Um período sem registro pode ser um documento que ainda não chegou ou um fundo que estava em outra classificação naquele mês. Patrimônio zero é a única leitura que ele quase nunca tem.

Consulte a referência da carteira de FIAGRO e faça a primeira chamada com um símbolo conhecido.