Número de cotistas

GET

/traded-funds/[fundIdentifier]/unitholders

Retorna os dados de cotistas de um fundo listado específico (FII, FIAGRO, FIDC, ETFs e ETFs de renda fixa), conforme reportados nos informes oficiais do fundo. Os registros são úteis para acompanhar a evolução da base de cotistas ao longo do tempo, com fonte rastreável.

Quando usar

• Exibir o número de cotistas na tela de detalhe do fundo
• Montar dashboards com a evolução da base de cotistas ao longo do tempo
• Comparar a base de cotistas entre fundos em análises de liquidez e popularidade
• Automatizar a ingestão incremental de informes usando publish_date ou retrieval_date como "cursor"

Parâmetros de requisição

Parâmetro	Local	Descrição	Obrigatório
[fundIdentifier]	URL	Identificador do fundo: ticker (ex.: HGLG11), symbol (ex.: HGLG) ou company_id numérico.	Obrigatório
fund_type	Query	Filtra pelo tipo de fundo (ver valores aceitos abaixo).	Opcional
report_type	Query	Filtra pelo tipo de informe (ver valores aceitos abaixo).	Opcional
reference_date	Query	ISO 8601. Filtra pela data de referência (considera o dia inteiro).	Opcional
publish_date	Query	ISO 8601. Retorna apenas documentos publicados após a data informada.	Opcional
retrieval_date	Query	ISO 8601. Retorna apenas documentos coletados após a data informada.	Opcional
latest_by_reference_date	Query	Se true, mantém apenas o documento publicado mais recentemente por data de referência.	Opcional
limit	Query	Quantidade de resultados. Mín.: 1, máx.: 500. Padrão: 50.	Opcional
offset	Query	Quantidade de resultados a pular. Mín.: 0. Padrão: 0.	Opcional

Boas práticas

• Para evitar duplicidade quando há reapresentações de informes, use latest_by_reference_date=true — você fica apenas com o documento mais recente por data de referência.
• Para ingestão incremental, use publish_date ou retrieval_date como "cursor": o endpoint retorna apenas documentos posteriores à data informada.
• As chaves dentro de data variam conforme o tipo de informe (report_type); trate o objeto de forma dinâmica na sua integração.

Valores aceitos

Tipos de fundo (fund_type)

• FII: fundos de investimento imobiliário
• FIAGRO: fundos de investimento nas cadeias produtivas agroindustriais
• FIDC: fundos de investimento em direitos creditórios
• ETFs: fundos de índice (renda variável)
• ETFs_RF: fundos de índice de renda fixa

Tipos de informe (report_type)

• DAILY_REPORT: informe diário
• MONTHLY_REPORT: informe mensal
• QUARTERLY_REPORT: informe trimestral
• ANNUAL_REPORT: informe anual
• TRIAL_BALANCE: balancete
• CDA: composição e diversificação das aplicações

Resposta

Código	Descrição
200	Retorna os dados de cotistas.
400	Parâmetros ausentes ou inválidos.
401	Não autorizado.
404	Fundo não encontrado.

Formato da resposta

A resposta é uma lista de objetos com os campos abaixo:

Campo	Tipo	Descrição
section	string	Seção do dado no documento de origem (varia conforme o informe).
fund_type	string	Tipo do fundo (FII, FIAGRO, FIDC, ETFs, ETFs_RF).
report_type	string	Tipo do informe de origem (DAILY_REPORT, MONTHLY_REPORT, QUARTERLY_REPORT, ANNUAL_REPORT, TRIAL_BALANCE, CDA).
reference_date	string (ISO 8601)	Data de referência do informe.
publish_date	string (ISO 8601)	Data de publicação do documento na fonte.
retrieval_date	string (ISO 8601)	Data/hora em que a Partnr coletou o documento.
data	object	Dados de cotistas conforme reportados no documento de origem; as chaves variam conforme o informe.
sources	array	Lista de fontes oficiais do documento.

Estrutura de sources[]

Campo	Tipo	Descrição
visualization_url	string	URL para visualização do documento original na FNET.
download_url	string | null	URL para download do documento original (quando disponível).
published_at	string (ISO 8601)	Data de publicação do documento na fonte.
retrieved_at	string (ISO 8601)	Data/hora em que a Partnr coletou o documento.
name	string	Nome/descrição do documento (ex.: Monthly Report).

Exemplo

[
  {
    "section": "...",
    "fund_type": "FII",
    "report_type": "MONTHLY_REPORT",
    "reference_date": "2024-01-31T00:00:00.000Z",
    "publish_date": "2024-02-15T00:00:00.000Z",
    "retrieval_date": "2024-02-16T10:00:00.000Z",
    "data": {
      "...": "..."
    },
    "sources": [
      {
        "visualization_url": "https://fnet.bmfbovespa.com.br/fnet/publico/exibirDocumento?id=792417&cvm=true",
        "download_url": null,
        "published_at": "2024-02-15T00:00:00.000Z",
        "retrieved_at": "2024-02-16T10:00:00.000Z",
        "name": "Monthly Report"
      }
    ]
  }
]