Agora você pode calcular métricas de retorno e de risco de um ativo individual, sem precisar de uma posição em um portfólio. Assim, é possível analisar o comportamento de um ativo antes de incluí-lo em um portfólio, ou comparar ativos entre si.

Os novos endpoints, agrupados em Security KPIs na referência da API, são:

• Read Security Time-Weighted Return: o TWR do ativo, com frequency, seriesType (PER_PERIOD ou ACCUMULATED) e type (GROSS, o padrão, ou GROSS_UP).
• Read Security Drawdown: a série de drawdown do ativo, também com o parâmetro type.
• Read Security Volatility e Read Security Sharpe Ratio: valores anualizados, com frequency e calculateWindow, seguindo a mesma metodologia usada para portfólios.

A rentabilidade é calculada simulando uma única compra do ativo no início do período, sem aportes nem resgates, de modo que reflete apenas a variação de preço e os eventos do próprio ativo. Para compará-la com o TWR de um portfólio, cujo padrão é GROSS_UP, use a mesma base de retorno nas duas consultas.

Saiba mais em Métricas do Ativo.

Agora você pode filtrar a listagem de transações por tipo de ativo, por exemplo, para buscar apenas as transações de ações de um portfólio sem percorrer todo o seu histórico.

Os endpoints List Transactions e List Economic Group Transactions aceitam o novo parâmetro securityType, uma lista com um ou mais tipos de ativo (por exemplo, STOCK_LOCAL). Ele aceita os mesmos valores do filtro securityType dos endpoints de posições e pode ser combinado com os demais filtros, como startDate, endDate, brokerId e type.

Exemplo: GET /portfolios/{portfolioId}/transactions?securityType=STOCK_LOCAL.

Saiba mais sobre os tipos disponíveis em Ativo.

Agora você pode consultar a volatilidade e o Índice de Sharpe de portfólios e grupos econômicos. Essas métricas de risco complementam a análise de retorno: mostram o quanto os retornos variam e quanto retorno foi obtido em relação ao risco assumido.

Os novos endpoints são Read Volatility, Read Sharpe Ratio, Read Economic Group Volatility e Read Economic Group Sharpe Ratio. Os valores são anualizados, e o Índice de Sharpe usa o CDI como taxa livre de risco.

Cada resposta traz o valor do período solicitado (interval) e uma série temporal (timeseries). Os principais parâmetros são:

• frequency (obrigatório): DAILY, MONTHLY, YEARLY ou INTERVAL.
• calculateWindow: a janela de retornos passados usada em cada ponto: 3M, 6M, 12M (padrão), 24M ou PER_FREQUENCY.
• startDate e endDate, além de filtros por custodiante, ativo, classe de ativo, tipo de ativo e classificação.

Saiba mais em Volatilidade e Índice de Sharpe.

Agora você pode criar perfis de investimento, alocações-alvo definidas por classificação de ativos, e verificar se a alocação de cada portfólio está enquadrada no seu perfil.

Um perfil de investimento tem um nome único, uma lista de classificações (classifications) cujas porcentagens somam 1 e faixas de enquadramento opcionais (thresholdLimits, padrão [5, 15]). Os perfis são gerenciados com Create Investment Profile, List Investment Profiles, Get Investment Profile By Id, Update Investment Profile e Delete Investment Profile.

Para associar um perfil a um portfólio, envie investmentProfileId em Update Portfolio by ID; enviar null remove a associação. Os portfólios passam a retornar o perfil associado no campo investmentProfile.

Dois novos endpoints mostram o enquadramento do portfólio:

• Get Portfolio Target Allocation: para cada classificação do perfil, retorna a alocação-alvo (target), a alocação real (allocation) e a diferença entre elas (differential).
• Get Portfolio Positions Allocation: retorna o peso de cada posição na exposição total do portfólio, com agrupamento (groupBy) e o filtro investmentProfileRelation (ALL, IN ou OUT) para ver as posições dentro ou fora do perfil.

Saiba mais em Perfil de Investimento.

A busca de ativos ganhou uma opção de correspondência exata, útil quando você já conhece o termo exato, como um ticker, e quer evitar resultados parciais.

O endpoint List Securities aceita o novo parâmetro searchExactMatch (booleano, padrão false), usado junto com search. Com searchExactMatch=true, as correspondências parciais são desativadas e apenas os ativos que correspondem exatamente ao termo pesquisado são retornados. Sem o parâmetro, a busca continua funcionando como antes, incluindo correspondências parciais.

Exemplo: GET /securities?search=PETR4&searchExactMatch=true.

Saiba mais em Ativo.

Os portfólios agora podem ter o come-cotas calculado automaticamente. Com essa configuração ligada, você não precisa mais inserir manualmente o come-cotas dos fundos sujeitos a essa tributação.

O novo campo booleano autoComeCotas (padrão false) pode ser definido em Create Portfolio e Update Portfolio by ID, e é retornado por List Portfolios e Read Portfolio by ID.

{
  "autoComeCotas": true
}

Com autoComeCotas igual a true, o Gorila calcula o come-cotas de todos os fundos elegíveis do portfólio e o recalcula sempre que transações são inseridas retroativamente. Se você cadastrar manualmente um come-cotas (transação do tipo COME_COTAS) na data correta (último dia útil de maio e de novembro), o lançamento manual prevalece sobre o automático.

Saiba mais na seção de come-cotas automático de Portfólio.

Agora você pode consultar a liquidez de portfólios e grupos econômicos: quanto do valor de mercado pode ser convertido em caixa em cada faixa de prazo. Essa visão ajuda a planejar resgates e a analisar o risco de liquidez.

Os endpoints Read Portfolio Liquidity e Read Economic Group Liquidity retornam o valor de mercado agrupado em faixas fixas de dias (ranges): 0 a 1, 2 a 30, 31 a 180, 181 a 360, 361 a 720 e 721 dias ou mais, além de uma faixa para ativos com liquidez indisponível. Cada faixa traz minDays, maxDays e marketValue. Na faixa de 721 dias ou mais, maxDays é null; na faixa de liquidez indisponível, os dois limites são null.

Para a visão por posição, List Position Liquidity e List Economic Group Position Liquidity retornam o daysToLiquidity de cada posição (null quando a liquidez está indisponível), com os filtros usuais de ativo e custodiante.

Os quatro endpoints aceitam o parâmetro referenceDate. Posições vendidas (short) ficam fora tanto do cálculo agregado quanto da listagem por posição.

Saiba mais em Liquidez.

O GorilaCORE passa a aceitar o novo formato de CNPJ alfanumérico adotado pela Receita Federal, além dos CNPJs numéricos atuais. Assim, fundos, emissores e custodiantes que receberem um CNPJ no novo formato podem ser identificados normalmente na API.

Os campos e filtros de CNPJ aceitam os dois formatos, sempre com 14 caracteres e sem pontuação, por exemplo 12ABC34501DE35. Isso inclui:

• issuerId em Read Issuer by ID e na criação de títulos bancários com Create Security;
• cnpj na criação de clubes de investimento e fundos administrados e na identificação de um ativo pelo seu CNPJ (por exemplo, security.cnpj em Create Transaction);
• o filtro securityCnpj nos endpoints de portfólios e grupos econômicos, como List Positions;
• o filtro brokerId (CNPJ do custodiante).

As respostas, como as de List Securities, retornam cnpj e issuer no mesmo formato, sem pontuação. Se a sua integração valida o CNPJ como um valor apenas numérico, ajuste-a para aceitar letras.

O novo tipo de transação INITIAL_CUSTODY_ADJUSTMENT registra a posição de um portfólio em um ativo numa data de corte, quando não há um histórico confiável de transações anteriores a essa data. Use-o no lugar de uma compra simples: o tipo dedicado facilita a identificação desses ajustes.

Envie o novo tipo ao endpoint Create Transaction com os mesmos campos de uma transação regular (transactDate, quantity, side, brokerId e security). O campo price é opcional: se ele não for informado, o Gorila usa o preço de fechamento do ativo na data da transação.

{
  "type": "INITIAL_CUSTODY_ADJUSTMENT",
  "transactDate": "2023-04-11",
  "quantity": 300,
  "side": "BUY",
  "brokerId": "18945670000146",
  "security": {
    "id": 122720
  }
}

As transações desse tipo também são retornadas por List Transactions e List Economic Group Transactions.

Saiba mais em Transação e no exemplo de ajuste inicial de custódia.

Agora você pode alterar o nome e a descrição dos ativos criados pela sua organização, mantendo a identificação deles atualizada sem precisar recriá-los.

O endpoint Update Security by ID passa a aceitar os campos name e description para ativos dos tipos CUSTOM, INVESTMENT_CLUB e MANAGED_FUND:

{
  "name": "Apartment",
  "description": "Apartment located in São Paulo"
}

Para os demais tipos de ativo, enviar name ou description retorna erro 400. Os outros campos aceitos pelo endpoint não são afetados por essa restrição.

Saiba mais em Ativo Personalizado e Clube de Investimento e Fundo Administrado.

Agora você pode filtrar a busca de ativos pela data de criação, e cada ativo passa a informar quando foi criado.

O endpoint List Securities aceita os novos parâmetros de consulta createdDateFrom e createdDateTo, no formato YYYY-MM-DD, para retornar apenas os ativos criados a partir de e/ou até uma data. O createdDateTo não pode ser anterior ao createdDateFrom. Exemplo: GET /securities?createdDateFrom=2026-04-01&createdDateTo=2026-04-28.

Os endpoints List Securities e Read Security by ID também passam a retornar o novo campo createdDate, com a data de criação do ativo.

Agora você pode verificar se um ativo tem incentivo fiscal pelo novo campo taxIncentivized e informá-lo nos seus ativos personalizados.

O campo taxIncentivized (booleano) é retornado pelos endpoints List Securities e Read Security by ID. Para ativos personalizados:

• Create Security aceita taxIncentivized (padrão false);
• Update Security by ID permite alterar o taxIncentivized e passa a aceitar também a data de vencimento (maturityDate).

Saiba mais em Ativo Personalizado.

Agora você pode filtrar a listagem de portfólios pela data de criação, e cada portfólio passa a informar quando foi criado.

O endpoint List Portfolios aceita os novos parâmetros de consulta createdDateFrom e createdDateTo, no formato YYYY-MM-DD, para retornar apenas os portfólios criados a partir de e/ou até uma data. Exemplo: GET /portfolios?createdDateFrom=2026-01-01&createdDateTo=2026-03-31.

Cada portfólio da resposta também traz o novo campo createdDate, com a data e a hora da criação (por exemplo, "createdDate": "2024-01-01T00:00:00Z").

O objeto do ativo agora traz o seu vencimento, indexador e taxa, inclusive nas respostas de posições e transações, sem que seja preciso consultar o ativo separadamente.

Novos campos:

• maturityDate: data de vencimento do ativo.
• index: indexador usado como referência.
• dealType: tipo de indexação do ativo.
• yield: taxa do ativo, de acordo com dealType e index.

Os campos são retornados por List Securities e Read Security by ID e também no resumo do ativo (objeto security) presente em outras respostas, tanto de portfólios quanto de grupos econômicos: posições e métricas por posição (como List Positions), eventos de ativos e transações (como List Transactions).

As transações importadas pelas integrações com BTG e XP, que antes não podiam ser alteradas pela API, agora podem ser editadas e excluídas. As suas alterações são mantidas mesmo após novas sincronizações ou reprocessamentos da integração.

Os endpoints Update Transaction by ID e Delete Transaction by ID passam a aceitar essas transações.

Na edição, é possível alterar price, quantity, exchangeRate e fees. Os campos brokerId, side, sourceBrokerId, targetBrokerId e transactDate não podem ser alterados, e a requisição que tentar mudá-los retorna erro 400.

Sua organização agora pode criar classificações próprias de ativos e reclassificar qualquer ativo, adaptando a árvore de classes à lógica com que avalia os seus portfólios.

Novos endpoints para gerenciar classificações personalizadas:

• Create Security Classification: cria uma classificação em qualquer nível (level, de CLASSIFICATION_L0 a CLASSIFICATION_L3). Abaixo do L0, a classificação pai é indicada em parentId e pode ser uma das classificações oficiais do Gorila.
• Read Classification by ID, Update Security Classification by ID (para renomeá-la) e Delete Security Classification by ID. Apenas classificações personalizadas podem ser renomeadas ou excluídas. Ao excluir uma, as subclasses abaixo dela também são excluídas, e os ativos que estavam nelas voltam à classificação oficial do Gorila.

O endpoint List Securities Classifications passa a incluir também as classificações da sua organização.

Para reclassificar um ativo, envie o classificationId desejado em Update Security by ID, ou null para voltar à classificação oficial. A reclassificação vale para todos os portfólios da organização e é refletida nas posições e nas métricas.

Saiba mais em Classificação de Ativos.

Agora você pode cadastrar e gerenciar os eventos dos seus ativos personalizados, como vencimento, amortizações, juros e dividendos, para que eles sejam refletidos nas posições, no Lucro e Prejuízo e na rentabilidade dos seus portfólios.

Novos endpoints:

• Create Security Event: cadastra um evento por requisição.
• List Security Custom Events: lista os eventos cadastrados, com filtros por período (startDate, endDate) e tipo (types).
• Update Security Event e Delete Security Event: editam e excluem um evento.

Tipos aceitos:

• Vencimento (EXPIRATION), com o preço de liquidação (settlementPrice). Ele encerra as posições no ativo na data do evento, e cada ativo pode ter apenas um.
• Eventos em dinheiro (CASH_AMORTIZATION, CASH_AMORTIZATION_UNSCHEDULED, CASH_DIVIDEND, CASH_INCOME, CASH_INTEREST, CASH_JSCP, CASH_PREMIUM e CASH_RETURN_OF_CAPITAL), com o valor pago por unidade do ativo (unitValue).

Todo evento tem uma data de referência (referenceDate) e uma data de pagamento (paymentDate), que não pode ser anterior à data de referência.

// REQUEST
// POST https://core.gorila.com.br/securities/{securityId}/events

{
  "type": "CASH_AMORTIZATION",
  "referenceDate": "2024-01-31",
  "paymentDate": "2024-02-05",
  "unitValue": 2.5
}

Saiba mais em Ativo Personalizado.

Agora você pode filtrar a listagem de transações pela data em que cada transação foi criada ou atualizada, o que facilita buscar apenas o que mudou desde a sua última sincronização.

Os endpoints List Transactions e List Economic Group Transactions aceitam quatro novos parâmetros de consulta, no formato YYYY-MM-DD:

• createdDateFrom e createdDateTo: transações criadas a partir de e/ou até a data informada.
• updatedDateFrom e updatedDateTo: transações atualizadas a partir de e/ou até a data informada.

Eles podem ser combinados com os demais filtros da listagem. As datas de criação e de atualização de cada transação são retornadas nos campos createdDate e updatedDate.

Agora você pode consultar o drawdown de portfólios e grupos econômicos: a queda percentual da rentabilidade acumulada em relação ao seu pico.

Os novos endpoints Read Drawdown e Read Economic Group Drawdown retornam a série diária do drawdown, com a data (referenceDate) e o valor (drawdown) de cada ponto, em formato decimal (-0.25 corresponde a uma queda de 25%).

O pico é sempre calculado a partir de todo o histórico: startDate e endDate apenas recortam a série retornada. Os endpoints também aceitam filtros por ativo, classe de ativo, tipo de ativo, classificação e custodiante, que restringem as posições consideradas.

Saiba mais em Drawdown.

Os ativos de fundos agora trazem a estrutura de classes e subclasses da Resolução CVM 175. Cada subclasse é um ativo distinto, o que permite diferenciar os ativos que compartilham o mesmo CNPJ.

Os endpoints List Securities e Read Security by ID retornam os novos campos de identificação do fundo: anbimaFundId, anbimaFundName, anbimaClassId, anbimaClassName, anbimaSubclassId, anbimaSubclassName, cvmClassId e cvmSubclassId.

Exemplo dos novos campos na resposta:

{
  "anbimaFundId": "F0000261599",
  "anbimaFundName": "Fundo de Investimento em Cotas de Fundos de Investimento RIVO FIDC",
  "anbimaClassId": "C0000261599",
  "anbimaClassName": "RIVO FIDC",
  "anbimaSubclassId": "S0000261599",
  "anbimaSubclassName": "SÊNIOR",
  "cvmClassId": "1",
  "cvmSubclassId": "1"
}

Como vários ativos podem ter o mesmo CNPJ, fundos multiclasse devem ser referenciados pelo ID do ativo (security.id) ao criar transações (Create Transaction) e conversões de preço (Price Conversion). Requisições que identificam esses fundos pelo cnpj são rejeitadas com erro 400.