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ária) em que você precisará criar o ativo (security) usando nossos modelos para renda fixa. A criação de ativos também se aplica aos 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. Todos os ativos criados estarão vinculados ao nível de Organização (Organization) do usuário da API, ou seja, eles só serão visíveis para as Chaves da API (API Keys) da sua organização.

Os tipos de transação que podem ser criados são: REGULAR, COME_COTAS, OPTION_EXERCISE, CUSTODY_TRANSFER, INITIAL_CUSTODY_ADJUSTMENT e POSITION_CLOSE. Para criar uma transação, use o endpoint Create Transaction.

Status da transação​

Todas as transações possuem um campo de status que indica o estado atual do processamento da transação. Esse campo é definido como PROCESSING logo após a inserção, sinalizando que a transação está em fase de cálculo e validação. Durante este estágio, todos os cálculos e verificações relacionados à transação são realizados para garantir que ela seja refletida corretamente no portfólio. Uma vez que todos os cálculos e verificações são concluídos com sucesso, o status da transação muda para COMPLETED, indicando que a transação foi completamente processada e integrada ao portfólio. Esse mesmo processo de atualização do status ocorre também em caso de edição da transação, onde o status retorna a PROCESSING até que todas as modificações sejam devidamente processadas e validadas.

Evitando transações duplicadas (chave de idempotência)​

O endpoint Create Transaction aceita o header opcional idempotency-key: um identificador único da transação, gerado pelo seu sistema (por exemplo, um UUID ou o código da operação no seu banco de dados). Ele evita que a mesma transação seja criada duas vezes quando uma requisição é repetida, por exemplo, em uma nova tentativa após uma falha de rede ou um timeout, em que não se sabe se a primeira tentativa foi processada.

  • A chave é única por portfólio: duas transações do mesmo portfólio não podem ter a mesma chave. 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. A resposta traz o transactionId da transação já existente, que você pode consultar para confirmar que ela foi registrada.
  • Sem o header, cada requisição cria uma nova transação, mesmo que os dados sejam idênticos.
// REQUEST
// POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions
// idempotency-key: 7d1f5c2e-3a9b-4e8f-b6d0-91c4a2e5f803

{
  "type": "REGULAR",
  "transactDate": "2023-03-07",
  "quantity": 500,
  "brokerId": "18945670000146",
  "security": {
    "isin": "BRMXRFCTF008"
  },
  "side": "BUY",
  "price": 9.50
}

Se a mesma requisição for enviada novamente com a mesma chave, a resposta será:

//RESPONSE 409

{
  "code": 409,
  "message": "idempotency key already used",
  "transactionId": "776287ce-4b50-4b7e-8e5b-23711578d4df"
}

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 ideia 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 (type). Clique para ver um exemplo de como criar uma transação de cada tipo:

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 a algumas discrepâncias na forma como os custodiantes aplicam o imposto, você precisa criar uma transação do tipo COME_COTAS 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. Para isso, é necessário criar uma transação do tipo OPTION_EXERCISE. 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​

A transação do tipo CUSTODY_TRANSFER deve ser usada para refletir o procedimento de mudar a instituição responsável por registrar e proteger seus investimentos (custodiante). Isso ocorre quando você muda um investimento 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

Ajuste inicial de Custódia​

Este tipo de transação (INITIAL_CUSTODY_ADJUSTMENT) existe para ajudar o caso específico onde é necessário usar informação de posição como uma transação de ajuste inicial. Esse caso é comum quando é necessário criar uma data de corte para uma posição devido à ausência ou imprecisão de informação transacional passada (anterior à data de corte). Nesse caso, o recomendável é usar este tipo de transação ao invés de uma compra simples.

Além da transação ficar com um tipo dedicado para o ajuste e facilitar identificação e segregação, ela dispensa a informação de preço (o campo preço da transação é opcional). Caso o preço não seja preenchido, o Gorila vai usar o preço de fechamento de mercado do ativo na data da transação.

Outro efeito é que, se por acaso existe uma posição aberta anterior à data da transação, ela é automaticamente fechada e reaberta pela transação.

Exemplo: Initial Custody Adjustment: INITIAL_CUSTODY_ADJUSTMENT

Fechar posição​

A transação do tipo POSITION_CLOSE pode ser usada para indicar que uma posição fechou (toda a custódia foi vendida) numa data específica. Não é necessário passar a quantidade vendida, calculamos a custódia do dia da transação e geramos uma venda na quantidade exata, de modo a garantir que a posição termina o dia "zerada". Como apenas Fundos e produtos de Renda Fixa Bancária (CDB, LCI, LCA, LIG, LF, etc.) são elegíveis para esse tipo, o parâmetro preço é opcional. Caso o preço não seja informado na requisição, o preço de fechamento do dia será usado (os ativos elegíveis só podem ser negociados no preço de fechamento). O caso de uso mais indicado é quando a informação transacional não possui todas as casas decimais necessárias, produzindo resquícios oriundos de imprecisão matemática na posição na hora da venda. Vale notar também que, caso uma transação com data anterior à transação de fechar posição seja incluída no portfólio postumamente, a quantidade da venda da transação de fechar posição será recalculada de modo a refletir o que é necessário para garantir a venda total.

Exemplo: Position Close: POSITION_CLOSE

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