Gestão de Inventário no Beancount

O sistema de inventário do Beancount é um recurso poderoso para rastrear ativos que são comprados e vendidos ao longo do tempo, como ações, fundos mútuos ou moedas estrangeiras. Ele permite o rastreamento preciso do custo base, o que é essencial para calcular os ganhos de capital e entender o desempenho do portfólio. Este tutorial aborda os principais mecanismos de gestão de inventários no seu livro razão.

Conceitos Essenciais

Em sua essência, a gestão de inventário gira em torno do rastreamento de posições. Uma "posição" é simplesmente uma quantidade de uma commodity mantida em uma conta. O Beancount distingue entre dois tipos fundamentais de posições.

Tipos de Posição

1. Posição Simples (Sem Custo): Esta é uma postagem de saldo padrão. Representa uma quantidade de uma commodity sem qualquer custo de aquisição associado. É adequado para dinheiro ou declarações de saldo simples.

   Assets:Bank:Checking      100.00 USD

2. Posição com Custo Base: Este tipo de posição inclui não apenas o número de unidades e a commodity, mas também o custo pelo qual foi adquirido. Esta é a base do rastreamento de inventário. O custo é especificado entre chaves {}.

   Assets:Invest:VTSAX      10 VTSAX {100.00 USD, "lot-1"}

   Neste exemplo, detemos 10 unidades de VTSAX. Cada unidade foi adquirida a um custo de $100.00 USD. Este lote específico de ações é identificado como um "lote".

Operações de Inventário

Existem duas operações principais que você pode executar em um inventário:

1. Aumentos (Adicionando ao inventário): Quando você compra uma commodity, você aumenta seu inventário. Você cria um novo lote com um número específico de unidades e um custo base.

   2024-01-15 * "Buy shares"
     Assets:Invest:STOCK     50 STOCK {25.00 USD, "lot-1"}
     Assets:Bank:Checking   -1250.00 USD

   Aqui, compramos 50 unidades de STOCK a um custo por unidade de $25.00 USD. Isso cria um lote na conta Assets:Invest:STOCK.

2. Reduções (Removendo do inventário): Quando você vende uma commodity, você reduz seu inventário. Você deve especificar de qual lote você está vendendo. Isso é feito fornecendo informações correspondentes entre chaves.

   2024-01-20 * "Sell shares"
     Assets:Invest:STOCK    -25 STOCK {25.00 USD}
     Assets:Bank:Checking    625.00 USD

   Nesta transação, estamos vendendo 25 unidades de STOCK do lote que foi comprado a $25.00 USD por unidade.

Métodos de Lançamento

Quando você reduz um inventário, o Beancount precisa de uma regra para decidir de qual lote específico retirar se vários lotes corresponderem ou se a correspondência for ambígua. Esta regra é chamada de "método de lançamento". Você pode definir um método padrão para todo o seu arquivo ou especificar um para cada conta.

1. STRICT (Padrão)

O método STRICT é o método de lançamento padrão e mais seguro. Ele impõe uma correspondência explícita e inequívoca.

2024-01-01 open Assets:Invest:STOCK "STRICT"

• Requer Correspondência Exata do Lote: Você deve fornecer informações suficientes na postagem de redução ({...}) para identificar exclusivamente o lote que está sendo vendido.
• Erros em Correspondências Ambíguas: Se as informações fornecidas corresponderem a vários lotes, o Beancount levantará um erro, forçando você a ser mais específico.
• Exceção: Se uma postagem de redução remover exatamente o número total de unidades mantidas em uma conta, um especificador de custo vazio ({}) é permitido.

2. FIFO (First-In, First-Out)

O método FIFO lança automaticamente as reduções contra os lotes disponíveis mais antigos primeiro.

2024-01-01 open Assets:Invest:STOCK "FIFO"

• Resolução Automática: Ele resolve a ambiguidade selecionando os lotes correspondentes mais antigos.
• Correspondência Cronológica: Este é um método contábil comum onde você assume que está vendendo os ativos que você detém há mais tempo. Este é o método exigido para fins fiscais em muitos países.

3. LIFO (Last-In, First-Out)

O método LIFO é o oposto de FIFO. Ele lança as reduções contra os lotes disponíveis mais recentes primeiro.

2024-01-01 open Assets:Invest:STOCK "LIFO"

• Ordem Cronológica Inversa: Ele seleciona os lotes adquiridos mais recentemente que correspondem aos critérios de redução.
• Otimização Fiscal: Em algumas jurisdições, este método pode ser usado para otimização fiscal, por exemplo, vendendo as ações com o custo base mais alto primeiro para minimizar os ganhos de capital.

4. NONE

O método NONE desativa a correspondência de lotes completamente.

2024-01-01 open Assets:Invest:STOCK "NONE"

• Sem Correspondência de Lotes: O Beancount não tenta corresponder reduções a aumentos.
• Permite Sinais Mistos: Isso permite que uma conta mantenha saldos positivos e negativos da mesma commodity simultaneamente. Este comportamento é semelhante à forma como a ferramenta Ledger CLI lida com commodities.

Especificação de Lote

Um "lote" é um bloco específico de uma commodity adquirida em um determinado momento e preço. Quando você cria ou reduz uma posição, você pode especificar seus atributos de lote em detalhes.

Especificação Completa

Ao aumentar um inventário (comprando), você pode especificar até três atributos para o lote:

Assets:Invest:STOCK  10 STOCK {
    100.00 USD,           # Custo base (custo por unidade)
    2024-01-15,           # Data de aquisição
    "lot-identifier"      # Um rótulo de string exclusivo
}

Embora todos os três sejam opcionais, fornecer pelo menos o custo base é uma prática padrão.

Métodos de Correspondência

Ao reduzir um inventário (vendendo), você usa a mesma sintaxe para especificar de quais lotes vender.

• Correspondência por custo: Este é o método mais comum.

  Assets:Invest:STOCK  -5 STOCK {100.00 USD}

• Correspondência por data: Se os custos forem idênticos, você pode desambiguar usando a data de aquisição.

  Assets:Invest:STOCK  -5 STOCK {2024-01-15}

• Correspondência por rótulo: Os rótulos fornecem uma maneira infalível de identificar um lote.

  Assets:Invest:STOCK  -5 STOCK {"lot-identifier"}

• Corresponder a qualquer lote: Um conjunto vazio de chaves {} corresponderá a qualquer lote disponível. Isso é frequentemente usado com o lançamento FIFO ou LIFO, onde o lote específico é selecionado automaticamente.

  Assets:Invest:STOCK  -5 STOCK {}

Tratamento de Preços

É crucial entender a diferença entre custo base ({}) e preço (@). Eles têm propósitos diferentes e não são intercambiáveis.

Preço vs Custo

• {cost}: Define o custo de aquisição de um ativo. Faz parte do próprio lote de inventário e é usado para lançar reduções e calcular ganhos de capital.
• @ price: Uma anotação que registra um preço de mercado no momento de uma transação. É usado para conversões de moeda ou para observar o valor de mercado em uma data específica.

Aqui estão os três cenários:

1. Anotação de Preço (Conversão): Use @ para converter de uma moeda para outra.

   Assets:Forex     1000 USD @ 0.85 EUR

2. Custo Base (Aquisição): Use {} ao comprar um ativo para estabelecer seu custo.

   Assets:Invest    10 STOCK {100.00 USD}

3. Ambos (Venda com Registro de Preço): Ao vender um ativo, use {} para identificar o lote que está sendo vendido e @ para registrar o preço de venda. Isso permite o cálculo automatizado de ganhos de capital.

   Assets:Invest    -10 STOCK {100.00 USD} @ 105.00 USD

   Esta entrada vende 10 STOCK do lote que custou $100.00 cada, a um preço de venda de$105.00 cada.

Regras de Uso de Preço

1. As anotações de preço (@) não afetam qual lote é lançado. A correspondência de lotes é tratada exclusivamente pelo custo base ({}) e pelo método de lançamento da conta.
2. O símbolo @ é usado apenas para:

• Conversões de moeda.
• Registrar o valor de mercado de um ativo no momento de uma transação.
• Fornecer o preço de venda para cálculos de ganhos de capital.

Configuração

Você pode configurar métodos de lançamento globalmente ou por conta.

Método de Lançamento Global

Você pode definir um método de lançamento padrão para todo o seu arquivo Beancount usando a diretiva option.

option "booking_method" "STRICT"

As opções disponíveis são "STRICT", "FIFO", "LIFO" e "NONE".

Substituição por Conta

Muitas vezes, é útil ter métodos diferentes para contas diferentes. Por exemplo, você pode querer FIFO para uma conta de aposentadoria, mas STRICT para uma conta de corretagem tributável para garantir que você está vendendo lotes fiscais específicos. Você pode definir o método de lançamento ao abrir a conta.

2024-01-01 open Assets:Retirement:401K "FIFO"
2024-01-01 open Assets:Taxable:Stock  "STRICT"

Melhores Práticas

1. Organização do Inventário: Para manter seu livro razão limpo e simples, é altamente recomendável usar contas separadas para cada commodity exclusiva que você detém.

   # BOM: Contas separadas por commodity
   Assets:Invest:VTSAX    ; Apenas posições VTSAX aqui
   Assets:Invest:VFIAX    ; Apenas posições VFIAX aqui

   Evite misturar diferentes ações ou fundos na mesma conta, pois isso complica a gestão do inventário.

2. Gestão de Lotes:

• Use rótulos significativos para lotes, especialmente para transações específicas, como colheita de perdas fiscais ou concessões de ações para funcionários.

  Assets:Invest:STOCK  10 STOCK {100.00 USD, "tax-loss-harvest-2024"}

• Documente suas negociações com comentários. Isso torna seu livro razão mais fácil de ler e entender mais tarde.

  Assets:Invest:STOCK  -10 STOCK {100.00 USD} @ 110.00 USD ; Ganho: 10%

3. Depuração: Se você encontrar erros ou comportamento inesperado, o Beancount fornece ferramentas para inspecionar o estado do seu inventário.

• Examinar o Estado do Inventário: A ferramenta bean-doctor pode mostrar o estado exato de todos os inventários em qualquer ponto do seu arquivo.

  Substitua <LINENO> pelo número da linha logo após uma transação para ver seu efeito.

• Verificar a Correspondência de Lotes: A ferramenta bean-check valida todo o seu arquivo. Ele detectará quaisquer erros de lançamento, como correspondências de lotes ambíguas no modo STRICT.