Pular para o conteúdo principal

Transação (Transaction)

As Transações (transactions) são a entrada usada pelo motor do Gorila para gerar todas as métricas de um portfolio.

Elas refletem transações da vida real que são executadas em corretoras ou bolsas. A maioria das transações pode ser criada usando o conjunto de ativos que o Gorila gerencia e mantém atualizado. Porém, existem casos (envolvendo renda fixa bancárias) em que você precisará criar o ativo (security) usando nossos modelos para renda fixa. A criação de ativos também se aplica à Termos de Ações.

Além disso, permitimos a possibilidade de criar Ativos Genéricos (Custom Securities), que são títulos criados e atualizados pelo usuário da API. Todas os ativos criados estarão vinculadas ao nível de Organização (Organization) do usuário da API, ou seja, elas só serão visíveis para as Chaves da API (API Keys) da sua organização.

Nós separamos as Transações em cinco tipos principais: REGULAR, COME_COTAS, OPTION_EXERCISE, CUSTODY_TRANSFER and SUBSCRIPTION_RECEIPT_EXERCISE.

Regular​

Esses são os tipos mais comuns de transações e, por isso, merecem toda atenção. Dividimos as transações Regulares (Regular) em quatro variantes que estão relacionadas às informações básicas necessárias para registrá-las (clique para ver exemplos):

A idéia por trás dessas variações é simplificar os campos necessários para criação da transação e retornar uma mensagem de erro correspondente para ajudar a evitar erros de entrada não intencionais.

As transações do tipo Regular englobam os seguintes tipos de ativos (clique para ver um exemplo de como criar uma transação):

Preço e Quantidade​

Somente quantidade​

Preço, taxa de câmbio e quantidade​

Taxa de câmbio e quantidade​

Come Cotas​

Para alguns fundos brasileiros, existe uma tributação especial chamada "Come-Cotas". O imposto funciona como um pagamento antecipado do Imposto de Renda Retido na Fonte e ocorre duas vezes por ano, no último dia útil de maio e novembro.

O come-cotas é um imposto incomum, pois tributa a quantidade de cotas do fundo do titular. Para entender como o pagamento funciona, visite nosso blog: Come-cotas: como é a tributação sobre os fundos de investimento.

Devido à algumas discrepâncias na forma como os custodiantes aplicam o imposto, você precisa criar uma transação em cima de um ativo existente em sua carteira que indique a quantidade a ser subtraída da posição.

Exemplo: Come Cotas: COME_COTAS

Exercício de opções​

Exercício de opções significa colocar em prática o direito de comprar ou vender o instrumento financeiro subjacente especificado em um contrato de opções. Suponha que o proprietário de uma opção decida comprar ou vender o instrumento subjacente em vez de permitir que o contrato expire sem valor ou encerrar a posição. Nesse caso, eles estarão "exercendo a opção" ou fazendo uso do direito ou privilégio disponível no contrato. Um detentor de opções pode exercer seu direito de comprar ou vender as ações subjacentes do contrato a um preço especificado, também chamado de preço de exercício.

  • Exercer uma opção de venda permite vender o título subjacente a um preço declarado dentro de um período específico.
  • Exercer uma opção de compra permite comprar o título subjacente a um preço declarado dentro de um período específico.

Para saber mais sobre opções, visite nosso blog: O que são opções e como investir neste mercado?.

Exemplo: Options Exercise: OPTION_EXERCISE

Transferência de Custódia​

Consiste no procedimento de mudar a instituição responsável por registrar e proteger seus investimentos (custodiante). Isso ocorre quando você muda de corretora ou migra de um banco para uma corretora, ou vice-versa. Dessa forma, o investidor pode alterar a instituição responsável por uma posição ou por uma carteira inteira sem a necessidade de resgatar todos os investimentos realizados.

Exemplo: Custody Transfer: CUSTODY_TRANSFER

Exercício de Subscrição de Ações​

⚠️ Ainda não implementado. Em breve.

Um recibo de subscrição de ações é um documento que comprova o direito de um investidor adquirir ações de uma empresa a um preço abaixo do valor de mercado. Ele contém informações como o nome da empresa, o número de ações a que o investidor tem direito de comprar, o preço de subscrição, a data de vencimento e as condições associadas à subscrição.

O exercício do recibo ocorre quando o titular decide comprar as ações pelo preço de subscrição especificado no recibo. No Gorila, como isso depende de uma escolha a ser exercida, a inserção da operação de recibo de subscrição é necessária. Na data de vencimento do recibo, ele será automaticamente convertido no ativo em questão.

Exemplo: Stock Receipt Exercise: SUBSCRIPTION_EXERCISE