Pular para o conteúdo principal

Ativo (Security)

Todos os ativos disponíveis no Gorila, que podem ser precificados e adicionados a um portfólio, são chamados de Securities.

A maioria deles está disponível para ser adicionado ao portfólio de alguém usando Transações Transactions, enquanto alguns devem primeiro ser criados no escopo da organização antes de poderem ser usados.

Cada ativo possui um identificador único (securityId), mas dependendo do seu tipo, você pode identificar um ativo por outros identificadores conhecidos usados pelos participantes do mercado financeiro, como ISIN para a maioria dos ativos listados em bolsa ou CNPJ para fundos brasileiros.

Tipos de ativos​

Os tipos de ativos são agrupamentos que separam os ativos por semelhanças em termos de sua natureza, tipo de cálculo e informações necessárias para expressar uma transação transactions. É um tipo de agrupamento semelhante (porém mais granular) a uma classe de ativos.

Aqui estão os tipos de ativos (clique no link para ver um exemplo de transação com cada um deles):

Tipos de ativos gerenciados pelo Gorila​

Tipos de ativos que precisam ser criados​

Criando ativos​

Vamos explorar os três casos de criação de ativos, sua motivação e um exemplo prático para cada um.

Título Bancário (CDB, LC, LCA, LCI, LF)​

Para alguns títulos bancários não existe mercado secundário organizado. A falta deste mercado ou até mesmo de balcão organizado gera algumas dificuldades para fins de cotização, como: falta de um provedor de preço, falta de identificador público e único para cada título, além de nenhuma fonte de precificação a mercado (mark-to-market) geralmente aceita.

Estes títulos podem ser préfixados ou pós-fixados vinculados a um benchmark e os seus tipos e taxas variam de acordo com cada operação.

Por essas razões, você primeiro precisa criar o título antes de criar transações que se refiram a ele. Os seguintes títulos se enquadram nesse critério:

  • CDB (Certificado de Depósito Bancário) - CORPORATE_BONDS_CDB
  • LC (Letra de Câmbio) - CORPORATE_BONDS_LC
  • LCA (Letra do Crédito do Agronegócio) - CORPORATE_BONDS_LCA
  • LCI (Letra de Crédito Imobiliário) - CORPORATE_BONDS_LCI
  • LF (Letra Financeira) - CORPORATE_BONDS_LF

Abaixo estão dois exemplos (um para um título prefixado e outro para um pós-fixado) dos payloads que precisamos para modelar os títulos:

Exemplo de CDB prefixado - Tipo: FIXED_RATE_BANKING_BOND​

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

{
  "type": "FIXED_RATE_BANKING_BOND",
  "bankingBondType": "LCA",
  "initialDate": "2020-01-01",
  "maturityDate": "2040-12-31",
  "issuerId": "03215790000110",
  "yield": 0.05
}

A resposta retornará o Id (securityId) do ativo recém-criado:

//RESPONSE

{
  "id": 44789070
}

Em posse do securityId é possível criar uma transaction com esse ativo:

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

{
  "type": "REGULAR",
  "transactDate": "2023-01-04",
  "quantity": 100,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789070
  },
  "side": "BUY"
}

Exemplo de CDB pós-fixado - Tipo: FLOATING_RATE_BANKING_BOND​

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

{
  "type": "FLOATING_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2020-01-01",
  "maturityDate": "2040-12-31",
  "issuerId": "03215790000110",
  "index": "CDI",
  "multiplier": 1.25
}

Observação: O campo multiplier é usado apenas quando a remuneração dos títulos é pós-fixada, ou seja, é um percentual (%) de um índice (exemplo: 120% do CDI). No caso de ativos com remuneração híbrida, como IPCA+ ou CDI+, o campo usado deve ser o spread (exemplo: IPCA + 5%).

A resposta retornará o Id (securityId) do ativo recém-criado:

//RESPONSE

{
  "id": 44789069
}

Em posse do securityId é possível criar uma transaction com esse ativo:

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

{
  "type": "REGULAR",
  "transactDate": "2022-01-04",
  "quantity": 100,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789069
  },
  "side": "BUY"
}

Termo de Ação (FORWARD_STOCK)​

Contratos de compra a termo de ações são contratos personalizados entre duas contrapartes que concordam em comprar ou vender uma ação a um preço especificado em uma data futura (que também é a data de vencimento do contrato). Como os contratos a termo são negociados no mercado de balcão e podem ser personalizados entre as partes, você precisará criá-los antes de registrar uma transação. Para criar contratos de compra a termo de ações, você precisará especificar as seguintes informações:

  • A ação subjacente, representada pelo seu securityId
  • A data inicial (semelhante a uma data de emissão)
  • A data de vencimento

Exemplo de Termo de Ação - Tipo: FORWARD_STOCK​

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

{
  "type": "FORWARD_STOCK",
  "underlyingSecurity": {
    "id": 4855044
    // you can also use ISIN: "BRPETRACNPR6"
  },
  "initialDate": "2023-01-01",
  "maturityDate": "2023-12-31"
}

A resposta retornará o Id (securityId) do ativo recém-criado:

//RESPONSE

{
  "id": 44789071
}

Em posse do securityId é possível criar uma transaction com esse ativo:

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

{
  "type": "REGULAR",
  "transactDate": "2023-02-01",
  "quantity": 100,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789071
  },
  "side": "BUY",
  "price": 25
}

Ativo Genérico (GENERIC)​

Para saber mais sobre a criação e gerenciamento dos ativos genéricos, clique aqui.