Pular para o conteúdo principal

Ativo Personalizado (Custom Security)

Ativos personalizados (tipo GENERIC) são ativos criados e gerenciados pela própria Organização. Eles permitem representar em um portfólio investimentos que não estão na base do Gorila, como imóveis, participações em empresas de capital fechado ou fundos de private equity no exterior. Como esses ativos não têm uma fonte de mercado, cabe à organização informar os seus preços e eventos.

Assim como os demais ativos criados pela organização, os ativos personalizados ficam disponíveis apenas para as chaves de API da sua organização.

Criação​

Para criar um ativo personalizado, use o endpoint Create Security com o tipo CUSTOM. Os principais campos são:

  • name e description (obrigatórios): identificam o ativo.
  • assetClass (obrigatório): classe de ativo de mais alto nível (CASH, CURRENCY, FIXED_INCOME, MULTIMARKET, OFFSHORE, STOCKS ou TANGIBLE).
  • initialDate (obrigatório): data inicial do ativo.
  • maturityDate: data de vencimento, quando houver.
  • classificationId: posição do ativo na árvore de Classificação de Ativos.
  • daysToSettlement: prazo, em dias, para que o valor de uma venda fique disponível. É usado no cálculo de Liquidez.
  • taxIncentivized: indica se o ativo tem incentivo fiscal.
//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "CUSTOM",
  "name": "Apartamento",
  "description": "Apartamento localizado em São Paulo",
  "assetClass": "TANGIBLE",
  "initialDate": "2022-04-04",
  "classificationId": "TANGIBLE_GENERIC"
}

A resposta retornará o Id (securityId) do ativo recém-criado, que deve ser usado para cadastrar preços, eventos e transações:

//RESPONSE

{
  "id": 44789072
}

Para listar os ativos criados pela sua organização, use o filtro securityProvider=ORGANIZATION no endpoint List Securities.

Preços​

Os preços de um ativo personalizado são informados pela organização por meio do endpoint Upsert Security Prices, que aceita até 1.000 preços por requisição. Se já existir um preço na data informada, ele é substituído. Nos dias sem preço informado, vale o último preço disponível.

//REQUEST
//PUT https://core.gorila.com.br/securities/{securityId}/prices

{
  "prices": [
    { "referenceDate": "2024-01-31", "price": 1000.00 },
    { "referenceDate": "2024-02-29", "price": 1012.50 }
  ]
}

Para consultar os preços cadastrados, use List Security Prices. Para remover o preço de uma data específica, use Delete Security Prices.

Eventos​

Os eventos de um ativo personalizado também são cadastrados pela organização, por meio do endpoint Create Security Event. Os tipos disponíveis são:

  • Eventos em dinheiro: amortização (CASH_AMORTIZATION), amortização extraordinária (CASH_AMORTIZATION_UNSCHEDULED), dividendos (CASH_DIVIDEND), rendimentos (CASH_INCOME), juros (CASH_INTEREST), juros sobre capital próprio (CASH_JSCP), prêmios (CASH_PREMIUM) e restituição de capital (CASH_RETURN_OF_CAPITAL). Esses eventos impactam o caixa do portfólio e exigem o valor pago por unidade do ativo (unitValue).
  • Vencimento (EXPIRATION): impacta a custódia. Quando cadastrado, ele produz o equivalente a uma venda total, ao preço de liquidação (settlementPrice), para todos os portfólios que detêm o ativo na data do evento. Assim, as posições são encerradas automaticamente na data do vencimento.

Todo evento tem uma data de referência (referenceDate), a data "ex" que define quem tem direito ao evento, e uma data de pagamento (paymentDate).

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

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

Ao lançar eventos em dinheiro, lembre-se do impacto que eles produzem no preço do ativo. Normalmente, um pagamento de X reais por unidade do ativo reduz o seu preço na mesma proporção. Por isso, é necessário lançar também a queda de preço na mesma data, para contrabalançar o valor pago no evento. Caso contrário, o Lucro e Prejuízo (P&L) terá uma distorção positiva que não reflete a realidade.

Os eventos cadastrados podem ser consultados em List Security Custom Events, atualizados em Update Security Event e excluídos em Delete Security Event. Uma vez cadastrados, eles passam a aparecer nos Eventos do Portfólio como qualquer outro evento. A lista completa de tipos de evento do Gorila pode ser consultada em List Security Event Types.

Classificação​

É possível reclassificar qualquer ativo, inclusive os personalizados. Caso deseje que o ativo criado faça parte de uma determinada classe ou subclasse, basta informar a classificação desejada no campo classificationId, seja na criação, seja na atualização do ativo. Mais detalhes sobre classes e reclassificação estão na documentação de Classificação de Ativos.

Atualização e exclusão​

Pelo endpoint Update Security by ID, você pode alterar o nome, a descrição, a data de vencimento, o incentivo fiscal, o prazo de liquidação e a classificação de um ativo personalizado. Ativos personalizados também podem ser excluídos pelo endpoint Delete Security by ID.