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 adicionada 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 o ISIN para a maioria dos ativos listados em bolsa ou o CNPJ para fundos brasileiros. Para encontrar um ativo, use o endpoint List Securities, que permite buscar por nome ou identificador e filtrar por tipo, classe ou classificação.

Tipos de ativos

Os tipos de ativos (type) 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 (transaction). É um agrupamento semelhante (porém mais granular) a uma classe de ativos. Para agrupar ativos por classes e subclasses, consulte a Classificação 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

Classificação de ativos

Além do tipo, cada ativo é enquadrado em uma árvore de classes e subclasses com até 4 níveis, de CLASSIFICATION_L0 (o mais amplo, como Renda Fixa ou Renda Variável) a CLASSIFICATION_L3 (o mais detalhado). Por exemplo, um título público indexado à inflação está em "Renda Fixa > Indexado a Inflação > Título Público". Essa classificação aparece no campo classifications dos dados do ativo e é a base das análises de alocação por classe, dos filtros e agrupamentos por classificação (securityClassification e groupBy) e dos Perfis de Investimento.

Por padrão, os ativos seguem a classificação oficial do Gorila. Se a lógica da sua instituição for diferente, a sua organização pode criar classes personalizadas e reclassificar qualquer ativo, informando o classificationId desejado na atualização do ativo (ou null, para devolvê-lo à classificação oficial). A reclassificação vale para todos os portfólios da sua organização.

Para entender os níveis, a criação de classes personalizadas e as regras de reclassificação, consulte a documentação de Classificação de Ativos.

Criando ativos

Vamos explorar os casos de criação de ativos, sua motivação e um exemplo prático para cada um. Todos eles usam o endpoint Create Security, e o campo type define qual modelo de ativo está sendo criado.

Títulos Bancários (CDB, LC, LCA, LCI, LF e afins)

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

Estes títulos podem ser prefixados (FIXED_RATE_BANKING_BOND) ou pós-fixados vinculados a um indexador (FLOATING_RATE_BANKING_BOND), 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. O campo bankingBondType define o tipo do título e, consequentemente, o tipo de ativo (type) resultante:

`bankingBondType`	Título	Tipo de ativo
`CDB`	Certificado de Depósito Bancário	`CORPORATE_BONDS_CDB`
`DPGE`	Depósito a Prazo com Garantia Especial	`CORPORATE_BONDS_DPGE`
`LC`	Letra de Câmbio	`CORPORATE_BONDS_LC`
`LCA`	Letra de Crédito do Agronegócio	`CORPORATE_BONDS_LCA`
`LCD`	Letra de Crédito do Desenvolvimento	`CORPORATE_BONDS_LCD`
`LCI`	Letra de Crédito Imobiliário	`CORPORATE_BONDS_LCI`
`LF`	Letra Financeira	`CORPORATE_BONDS_LF`
`LFS` e `LFSN`	Letras Financeiras subordinadas	`CORPORATE_BONDS_LFS` e `CORPORATE_BONDS_LFSN`
`LIG`	Letra Imobiliária Garantida	`CORPORATE_BONDS_LIG`
`RDB`	Recibo de Depósito Bancário	`CORPORATE_BONDS_RDB`
`RDC`	Recibo de Depósito Cooperativo	`CORPORATE_BONDS_RDC`
`P2B_LENDING`	Empréstimo P2B (peer-to-business)	`P2B_LENDING`
`REPO`	Operação Compromissada	`REPO`

Os campos comuns aos dois modelos são:

bankingBondType, initialDate (data de emissão), maturityDate e issuerId (CNPJ do emissor, sem máscara): obrigatórios.
issuanceFaceValue: valor de face na emissão. É opcional, mas recomendado.
interestPaymentPeriod: periodicidade do pagamento de juros (cupom). Não se esqueça de informar esse parâmetro para títulos que fazem pagamentos periódicos. Valores aceitos:
- BULLET (padrão, sem pagamentos intermediários), MONTHLY, EVERY_2_MONTHS, EVERY_3_MONTHS, EVERY_4_MONTHS, EVERY_6_MONTHS ou YEARLY.

Integrando renda fixa bancária

Para um passo a passo completo, do cadastro do título à conferência da carteira, e para os desafios mais comuns dos dados da indústria (valor de face em outra escala, taxas em formatos diferentes, compras no mercado secundário e transferências de custódia), veja o caso de uso Integrando renda fixa bancária.

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`

No modelo prefixado, a taxa anual é informada em formato decimal no campo yield (ex.: 0.05 = 5% a.a.).

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

{
  "type": "FIXED_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2020-01-01",
  "maturityDate": "2040-12-31",
  "issuerId": "03215790000110",
  "issuanceFaceValue": 1000,
  "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": "2020-01-01",
  "quantity": 25,
  "price": 1000,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789070
  },
  "side": "BUY"
}

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

No modelo pós-fixado, o campo index define o indexador (CDI, IPCA, IGPM ou SELIC).

//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",
  "issuanceFaceValue": 100,
  "index": "CDI",
  "multiplier": 1.25
}

Observação: o campo multiplier é usado apenas quando a remuneração do título é um percentual (%) de um índice (exemplo: 120% do CDI → 1.20). No caso de ativos com remuneração híbrida, como IPCA+ ou CDI+, o campo usado deve ser o spread (exemplo: IPCA + 5% → 0.05). Envie apenas um dos dois.

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-04-15",
  "quantity": 30,
  "price": 103.4323,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789069
  },
  "side": "BUY"
}

CDB escalonado (rentabilidade progressiva)

Alguns títulos pós-fixados têm rentabilidade progressiva: o percentual do indexador muda em datas predefinidas (por exemplo, começa em 100% do CDI e sobe 5 pontos percentuais a cada ano). Esse tipo de estrutura é modelado com os campos scaleType e scaling:

scaleType = INCREMENTAL: a nova taxa vale apenas a partir da data da mudança. A vida do título é dividida em intervalos, e em cada intervalo aplica-se a taxa vigente.
scaleType = RETROACTIVE: ao atingir a data da mudança, a nova taxa passa a valer desde o início do título, causando uma mudança acentuada no preço para refletir o preço do título como se ele tivesse rendido mais desde o initialDate.

O multiplier continua indicando a taxa inicial (a vigente na emissão), e o scaling lista apenas as mudanças seguintes, com a data e o novo multiplier de cada uma. Os dois campos devem ser enviados juntos e, hoje, o escalonamento só é aceito para títulos indexados ao CDI, sem spread e com interestPaymentPeriod igual a BULLET.

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

{
  "type": "FLOATING_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2025-01-01",
  "maturityDate": "2030-01-01",
  "issuerId": "30306294000145",
  "issuanceFaceValue": 1000,
  "index": "CDI",
  "multiplier": 1.0,
  "scaleType": "INCREMENTAL",
  "scaling": [
    { "date": "2026-01-01", "multiplier": 1.05 },
    { "date": "2027-01-01", "multiplier": 1.10 },
    { "date": "2028-01-01", "multiplier": 1.15 },
    { "date": "2029-01-01", "multiplier": 1.20 }
  ]
}

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
}

Clube de Investimento e Fundo Administrado

Clubes de investimento (INVESTMENT_CLUB) e Fundos administrados (MANAGED_FUND) também precisam ser criados antes de receber transações. O cadastro exige nome (name), descrição (description), classe de ativo (assetClass) e data inicial (initialDate), e aceita opcionalmente o cnpj.

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

{
  "type": "INVESTMENT_CLUB",
  "name": "Clube de Investimento Gorila",
  "description": "Clube composto por uma carteira diversificada de renda variável e renda fixa",
  "assetClass": "STOCKS",
  "initialDate": "2022-04-04"
}

Assim como nos ativos personalizados, o valor da cota desses ativos é informado pela organização por meio do endpoint Upsert Security Prices.

Ativo Personalizado (GENERIC)

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

Tipos de ativos​

Tipos de ativos gerenciados pelo Gorila​

Tipos de ativos que precisam ser criados​

Classificação de ativos​

Criando ativos​

Títulos Bancários (CDB, LC, LCA, LCI, LF e afins)​

Exemplo de CDB prefixado - Tipo: FIXED_RATE_BANKING_BOND​

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

CDB escalonado (rentabilidade progressiva)​

Termo de Ação (FORWARD_STOCK)​

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

Clube de Investimento e Fundo Administrado​

Ativo Personalizado (GENERIC)​

Tipos de ativos

Tipos de ativos gerenciados pelo Gorila

Tipos de ativos que precisam ser criados

Classificação de ativos

Criando ativos

Títulos Bancários (CDB, LC, LCA, LCI, LF e afins)

Exemplo de CDB prefixado - Tipo: `FIXED_RATE_BANKING_BOND`

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

CDB escalonado (rentabilidade progressiva)

Termo de Ação (FORWARD_STOCK)

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

Clube de Investimento e Fundo Administrado

Ativo Personalizado (GENERIC)