O novo tipo de transação POSITION_CLOSE fecha uma posição em uma data sem exigir a quantidade vendida, o que evita resquícios na posição quando a informação transacional não tem todas as casas decimais.

Ao criar uma transação com o endpoint Create Transaction e type igual a POSITION_CLOSE, informe a data (transactDate), o custodiante (brokerId) e o ativo (security). O Gorila calcula a custódia nessa data e gera uma venda na quantidade exata, de modo que a posição termine o dia zerada. Se uma transação com data anterior ao fechamento for incluída depois, a quantidade da venda é recalculada.

O tipo está disponível para fundos e títulos de renda fixa bancária (CDB, LCI, LCA, LF etc.). O campo price é opcional: se não for informado, é usado o preço de fechamento do dia. As taxas podem ser informadas em fees.

// REQUEST
// POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions

{
  "type": "POSITION_CLOSE",
  "transactDate": "2023-06-30",
  "brokerId": "18945670000146",
  "security": {
    "id": 2407939
  }
}

Saiba mais em Transação e no exemplo de Position Close.

Clubes de investimento agora podem ser cadastrados no GorilaCORE com o novo tipo de ativo INVESTMENT_CLUB e, em seguida, usados nas transações dos seus portfólios.

Assim como títulos bancários e ativos personalizados, um clube de investimento precisa ser criado antes de receber transações. Use o endpoint Create Security com type igual a INVESTMENT_CLUB, informando nome (name), descrição (description), classe de ativo (assetClass) e data inicial (initialDate). O campo cnpj é opcional.

Assim como nos ativos personalizados, o valor da cota do clube é informado pela sua organização, por meio dos endpoints de preços:

• Upsert Security Prices: cria ou atualiza preços.
• List Security Prices: lista os preços cadastrados.
• Delete Security Prices: exclui o preço de uma data específica.

Saiba mais em Ativo.

Agora você pode buscar portfólios pelo nome diretamente na listagem de portfólios.

O endpoint List Portfolios aceita o novo parâmetro opcional search, que filtra os portfólios retornados pelo nome. O termo buscado deve ter pelo menos 3 caracteres.

GET https://core.gorila.com.br/portfolios?search=Silva

Saiba mais em Portfólio.

Agora você pode excluir os ativos personalizados que não usa mais, assim como o preço de um ativo personalizado em uma data específica.

• Delete Security by ID: exclui um ativo personalizado. A exclusão só é permitida se o ativo não tiver transações em nenhum portfólio; caso contrário, a requisição é recusada.
• Delete Security Prices: exclui o preço de um ativo personalizado na data informada em referenceDate.

Saiba mais em Ativo Personalizado.

A listagem de portfólios passa a retornar o status de processamento de cada portfólio, permitindo acompanhar vários portfólios em uma única chamada.

Cada registro retornado pelo endpoint List Portfolios agora inclui o campo status (PROCESSING, COMPLETED ou INVALID), que antes estava disponível apenas em Read Portfolio by ID. Um portfólio fica COMPLETED quando todas as suas transações já foram processadas e estão refletidas nas suas posições e métricas.

Desde 27/12/2024, os endpoints Create Portfolio e Update Portfolio by ID também retornam o portfólio completo, incluindo o campo status.

Saiba mais em Portfólio.

Títulos bancários agora podem ser criados com o novo tipo P2B_LENDING, para representar operações de empréstimo P2B (peer-to-business).

No endpoint Create Security, envie bankingBondType igual a P2B_LENDING ao criar um título bancário prefixado (FIXED_RATE_BANKING_BOND) ou pós-fixado (FLOATING_RATE_BANKING_BOND). O ativo resultante tem o tipo P2B_LENDING e, como os demais títulos bancários, pode então ser usado em transações pelo securityId retornado.

Saiba mais em Ativo.

Além das chaves de API da organização, a API passa a aceitar Personal Access Tokens (PATs): chaves pessoais que dão acesso com as permissões do usuário a quem pertencem.

As duas credenciais diferem no escopo:

• Chave de API da organização: associada à organização, dá acesso aos portfólios e recursos da organização.
• PAT: associado a um usuário, carrega as permissões desse usuário. Requisições autenticadas com um PAT enxergam apenas os portfólios e recursos aos quais o usuário tem acesso.

O PAT é gerado pelo próprio usuário na plataforma do Gorila, e não pela API. Ele é enviado da mesma forma que a chave de API, no cabeçalho Authorization, e pode ser reconhecido pelo prefixo pat_:

curl --request GET \
  --url https://core.gorila.com.br/portfolios \
  --header 'Authorization: pat_<token>'

Saiba mais sobre as chaves de API em Organização.

Agora você pode escolher como a rentabilidade de um benchmark é contabilizada no primeiro dia da série, com o novo parâmetro calculationMethod.

O endpoint Read Benchmark by ID aceita o parâmetro opcional calculationMethod:

• INDEX (padrão): contabiliza a rentabilidade desde o primeiro dia (startDate) para todos os benchmarks.
• INTEREST: não contabiliza a rentabilidade do primeiro dia para nenhum benchmark.
• AUTO: não contabiliza o primeiro dia para benchmarks de renda fixa (como CDI e SELIC), mas contabiliza para os demais (como IBOVESPA ou USDBRL).

Antes desta mudança, as séries eram sempre calculadas com o comportamento AUTO. Para manter os resultados anteriores, envie calculationMethod=AUTO.

Saiba mais em Benchmark.

Transações e portfólios passam a retornar o campo status, que indica se os cálculos de posições e métricas já refletem as transações que você inseriu ou editou.

O campo assume os valores PROCESSING, COMPLETED ou INVALID e é retornado pelos seguintes endpoints:

• Transações: Create Transaction, List Transactions e Read Transaction by ID.
• Portfólios: Read Portfolio by ID.

Logo após a inserção ou a edição, a transação fica com o status PROCESSING enquanto o Gorila realiza os cálculos e as verificações. Ao final, o status muda para COMPLETED. O portfólio passa a COMPLETED quando todas as suas transações já foram processadas. Antes de consultar as métricas de um portfólio, verifique se o status dele já é COMPLETED.

Saiba mais em Transação e Portfólio.

Agora você pode consultar as posições encerradas de um portfólio, além das abertas, e cada posição passa a informar o seu estado.

O endpoint List Positions aceita o novo parâmetro positionState, com os valores OPEN (padrão, apenas as posições abertas), CLOSED (apenas as encerradas) ou ALL (abertas e encerradas). Cada posição da resposta traz também o novo campo state, com o valor OPEN ou CLOSED. Uma posição é encerrada quando a sua quantidade é totalmente zerada.

Saiba mais em Posição.

Agora você pode enviar uma chave de idempotência ao criar transações. Ela garante que a mesma transação não seja registrada duas vezes, por exemplo, quando uma requisição é repetida após uma falha de rede ou um timeout.

O endpoint Create Transaction aceita o header opcional idempotency-key: um identificador único da transação, gerado pelo seu sistema (como um UUID ou o código da operação no seu banco de dados).

• A chave é única por portfólio. A mesma chave pode ser usada em portfólios diferentes.
• Se a requisição for enviada com uma chave já usada no portfólio, a transação não é criada e a API responde com o erro HTTP 409 Conflict (idempotency key already used).
• Sem o header, cada requisição cria uma nova transação, mesmo que os dados sejam idênticos.

Saiba mais em Transação.

Agora sua organização pode criar ativos personalizados para representar investimentos que não estão na base do Gorila, como imóveis ou participações em empresas de capital fechado, e informar os seus preços.

Para criar um ativo personalizado, use o endpoint Create Security com o tipo CUSTOM, informando name, description, assetClass e initialDate (maturityDate é opcional). A resposta traz o id do novo ativo, usado para cadastrar preços e transações.

// REQUEST
// POST https://core.gorila.com.br/securities

{
  "type": "CUSTOM",
  "name": "Apartment",
  "description": "Apartment located in São Paulo",
  "assetClass": "TANGIBLE",
  "initialDate": "2022-04-04"
}

Como esses ativos não têm uma fonte de mercado, cabe à organização informar os preços: use Upsert Security Prices para enviar uma lista de preços (prices, com referenceDate e price) e List Security Prices para consultá-los. Os preços valem para todos os portfólios da organização que têm o ativo. Ativos personalizados ficam disponíveis apenas para as chaves de API da sua organização.

Saiba mais em Ativo Personalizado.

O endpoint List Security Event Types agora está disponível: ele lista os tipos de eventos de ativos tratados pelo Gorila, como dividendos, amortizações e bonificações.

Esses tipos classificam os eventos que afetam as posições dos portfólios, como os listados em List Security Events. Os resultados são paginados (limit e pageToken), e o parâmetro search filtra os tipos por parte do nome ou das informações.

Saiba mais em Eventos do Ativo.

Agora você pode listar os eventos de ativos, como dividendos e bonificações, que afetaram as posições de um portfólio em um período.

O endpoint List Security Events recebe o período em startDate e endDate e retorna os resultados paginados (limit e pageToken). Cada evento informa o ativo e o custodiante, o tipo do evento (eventType), a data "ex" (eventDate) e a data de pagamento (paymentDate). Conforme o evento, a resposta traz também o valor unitário (unitValue) ou, nos eventos que entregam outro ativo, o ativo recebido (receivedSecurity), a quantidade recebida (receivedQuantity) e o fator aplicado sobre a posição (eventFactor).

Saiba mais em Eventos do Portfólio.

O novo endpoint Price Conversion converte as informações que você conhece de uma negociação, como o valor aplicado, no preço (price) e na quantidade (quantity) necessários para criar uma transação.

Isso é especialmente útil para títulos bancários (CDB, LC, LCI, LCA, LF), cujas transações passaram a exigir price e quantity, e não apenas quantity.

A requisição identifica o ativo (security, por id, isin ou cnpj) e a data da negociação (date), além do valor financeiro (notional) ou, para CRI, CRA e debêntures, da taxa da negociação (multiplier ou spread). São aceitos títulos bancários (CDB, LC, LCI, LCA, LF), todos os tipos de cotas de fundos e títulos de crédito privado (CRI, CRA e debêntures).

Por exemplo, para converter R$ 10.000,00 aplicados em um fundo:

// REQUEST
// POST https://core.gorila.com.br/securities/price-conversions

{
  "security": {
    "cnpj": "26673556000132"
  },
  "date": "2023-06-23",
  "notional": 10000
}

// RESPONSE

{
  "security": {
    "id": 2363053,
    "cnpj": "26673556000132",
    "name": "ALASKA INSTITUCIONAL FIA",
    "type": "FUNDQUOTE",
    "assetClass": "STOCKS"
  },
  "date": "2023-06-23",
  "price": 3.2519722,
  "quantity": 3075.0570377
}

O price e a quantity retornados estão prontos para uso no endpoint Create Transaction.

Saiba mais em Conversão de Preço.

Reformulamos a documentação do GorilaCORE para facilitar a modelagem de transações, ativos e métricas na sua integração.

A página de Transação foi reescrita e agora detalha cada tipo de transação, para que serve e quando usá-lo. Ela leva à nova página de Exemplos de Transações, que mostra como criar transações para todos os ativos suportados pelo Gorila.

As páginas de Taxa Interna de Retorno (TIR) e Retorno Ponderado no Tempo (TWR) ganharam exemplos que mostram as diferenças entre as duas métricas e quando usar cada uma. As páginas de Valor Patrimonial (NAV), Lucro e Prejuízo (P&L), Preço Médio e Posição também foram ampliadas.

A página de Ativo ganhou exemplos de criação de ativos, como títulos bancários, e de como registrar transações com eles.

Por fim, a referência da API passou a trazer links para as páginas de conceitos, para que você entenda rapidamente os conceitos usados em cada endpoint.

A busca de ativos agora ordena os resultados por relevância: os ativos mais aderentes aos termos buscados aparecem primeiro, e você não precisa mais percorrer listas extensas para encontrar o que procura.

A mudança vale para as buscas feitas com o parâmetro search do endpoint List Securities.

Saiba mais em Ativo.