Pular para o conteúdo principal

Melhorando seus relatórios

O relatório mensal é, muitas vezes, o principal ponto de contato entre uma consultoria, uma gestora ou um family office e os seus clientes. É nele que o investidor confere quanto tem, quanto ganhou e como a carteira se comparou ao mercado. Por isso, cada número precisa estar certo e precisa conversar com os outros números da página.

A seguir, exploraremos o caso de uso voltado para empresas que buscam transformar os dados transacionais dos seus clientes em relatórios de investimento claros, consistentes e produzidos em escala.

Números que fecham​

Um relatório mostra o mesmo patrimônio sob vários ângulos: o resultado do mês, a rentabilidade comparada ao CDI, a alocação por classe e as movimentações. Quando esses números saem de planilhas e cálculos espalhados, é comum que um bloco não bata com o outro, e o cliente percebe.

Com o GorilaCORE, todos os blocos do relatório saem do mesmo motor de cálculo, a partir das mesmas transações e dos mesmos preços. A rentabilidade do mês, o resultado em reais e o patrimônio final fecham entre si, e os eventos dos ativos (dividendos, juros, amortizações, desdobramentos) já entram nas contas sem que você precise tratá-los um a um.

E se uma transação do passado for corrigida, as métricas são recalculadas: o próximo relatório já sai com os números certos, sem retrabalho manual.

Do fechamento do mês ao envio​

Gerar um relatório é fácil; gerar centenas deles todo mês, logo após o fechamento, é outra história. Cada carteira precisa estar com preços, eventos e posições atualizados antes que o primeiro PDF seja gerado.

O GorilaCORE processa mais de um milhão de carteiras diariamente, e as métricas de cada uma ficam disponíveis por API. Assim, a sua rotina de relatórios se resume a consultar os números e preenchê-los no seu modelo, com a sua marca.

Usando o GorilaCORE para montar um relatório mensal​

Vamos montar, bloco a bloco, o relatório simplificado abaixo, de uma consultoria fictícia, referente a setembro de 2026.

Partimos de um portfólio que já tem transações cadastradas. Se você ainda não chegou lá, veja como criar a organização, os portfólios e inserir as transações em Criando uma aplicação e, com trechos de código, no Guia de Início Rápido.

Relatório mensal de investimentos de exemplo, com indicadores, gráfico de rentabilidade, alocação, rentabilidade mensal e movimentações

Cabeçalho​

O nome da carteira e o perfil do cliente vêm do próprio Portfolio: consulte Read Portfolio e use os campos name e investmentProfile.name (o Perfil de Investimento associado à carteira). Os dados do cliente e do consultor ficam no seu sistema, associados ao portfolioId.

Indicadores do mês​

O primeiro bloco resume a carteira na data-base:

  • Patrimônio líquido: é o Valor Patrimonial (NAV) da carteira em 30/09/2026, consultado em Read Net Asset Value.
  • Resultado no mês: é o Lucro e Prejuízo (P&L) de 01/09 a 30/09, em Read Profit & Losses. Use a frequência INTERVAL para receber um único valor para o mês inteiro.
  • Rentabilidade no mês, no ano e em 12 meses: são o Retorno Ponderado no Tempo (TWR) de cada período. Você não precisa de uma chamada para cada um: as consultas dos próximos blocos já trazem esses valores, como veremos a seguir.

Ao lado de cada rentabilidade aparece o CDI do mesmo período e o percentual do CDI, que é simplesmente a divisão entre as duas rentabilidades.

Rentabilidade acumulada em 12 meses​

O gráfico compara a carteira com dois Benchmarks, o CDI e o Ibovespa. Para isso, precisamos de três séries com os mesmos parâmetros.

Primeiro, consultamos o TWR da carteira de 01/10/2025 a 30/09/2026, com frequency=MONTHLY e seriesType=ACCUMULATED: cada ponto é a rentabilidade acumulada até o fim do mês. Além da série, a resposta traz o campo interval, com o TWR do período inteiro: é a rentabilidade em 12 meses do bloco de indicadores.

Em seguida, encontramos o identificador do CDI e do Ibovespa em List Benchmarks (com o parâmetro search) e consultamos a série de cada um em Read Benchmark by ID, com o mesmo período, a mesma frequência e o mesmo tipo de série.

Com as três séries em mãos, é só escolher a sua biblioteca de gráficos favorita.

Alocação por classe de ativo​

Para o gráfico de rosca e a tabela, usamos o endpoint de Valor de Mercado, List Position Market Values, na data-base (referenceDate). Não é preciso somar as posições manualmente: com o parâmetro groupBy igual a um nível de classificação (por exemplo, CLASSIFICATION_L1), a resposta já traz o valor de mercado somado por classe. O percentual de cada classe é o seu valor dividido pelo total dos grupos.

A coluna de rentabilidade do mês vem de List Position Time-Weighted Returns, com o mesmo groupBy e o período de 01/09 a 30/09: a resposta traz o TWR de cada classe no mês.

As classes deste relatório são as da consultoria, e não necessariamente as do Gorila. Se for o seu caso, crie classificações personalizadas e reclassifique os ativos: os agrupamentos passam a seguir a sua árvore de classes, em todos os portfólios da sua organização. Para exibir o nome de cada classe, consulte as classificações em List Security Classifications.

Rentabilidade mensal​

A tabela mostra a rentabilidade de cada mês do ano, comparada ao CDI. Consultamos o TWR da carteira de 01/01/2026 a 30/09/2026, agora com frequency=MONTHLY e seriesType=PER_PERIOD: cada ponto é o retorno do próprio mês. Fazemos o mesmo com o CDI em Read Benchmark by ID.

Essa consulta completa o bloco de indicadores: o último ponto da série é a rentabilidade no mês, e o campo interval é a rentabilidade no ano. A coluna de 12 meses já veio da consulta do gráfico.

Movimentações do mês​

Este bloco explica como o patrimônio saiu de um valor para o outro:

  • Patrimônio inicial e final: consulte o NAV de 31/08 a 30/09. O primeiro ponto da série é o patrimônio no fim do mês anterior e o último, o da data-base.
  • Aplicações e resgates: consulte a lista de transações do mês para medir as compras (entradas) e as vendas (saídas).
  • Proventos recebidos: consulte os Eventos do Portfólio do mês em List Security Events e some o valor recebido (receivedValue) dos eventos em dinheiro, como dividendos (CASH_DIVIDEND), juros sobre capital próprio (CASH_JSCP) e rendimentos (CASH_INCOME). Cada evento traz a data ex (eventDate) e a data de pagamento (paymentDate); escolha qual delas define o mês no seu relatório. Os proventos já fazem parte do resultado do mês, por isso aparecem apenas como informação.
  • Resultado do mês: é o mesmo P&L do bloco de indicadores.

A conta fecha: o patrimônio final é igual ao inicial, mais as aplicações, menos os resgates, mais o resultado do mês. No exemplo, R$ 2.434.088,63 + R$ 20.000,00 + R$ 27.261,79 = R$ 2.481.350,42.

Comentário e rodapé​

O comentário é escrito pela consultoria, mas os dados ajudam: o TWR de cada posição no mês, agrupado por ativo (groupBy=SECURITY_ID), mostra quais investimentos se destacaram.

O rodapé informa que as rentabilidades são calculadas pelo método de cotas (TWR) e são brutas de impostos. No GorilaCORE, o TWR desconta os custos das operações e nunca desconta impostos sobre os ganhos; veja a base de retorno para escolher entre GROSS_UP e GROSS.

Conclusão​

Exploramos como montar um relatório mensal com o GorilaCORE, mas você pode ir muito além! Para clientes com várias carteiras, os mesmos indicadores estão disponíveis para um Grupo Econômico, consolidando tudo em um único relatório. Você também pode incluir o enquadramento da carteira ao perfil do cliente com a alocação-alvo, um bloco de risco com Drawdown, Volatilidade e Sharpe, ou a TIR para mostrar o retorno financeiro efetivamente obtido pelo investidor.

Entre em contato conosco se tiver dúvidas sobre como começar.