Перейти до основного вмісту

Основні вбудовані плагіни Beancount, які варто знати

· 10 хв. читання
Mike Thrift
Mike Thrift
Marketing Manager

Сила Beancount полягає не лише в його текстовому форматі, а й у можливості розширення за допомогою плагінів. Вбудовані плагіни — це модулі, які розширюють функціональність Beancount, автоматизують рутинні завдання та забезпечують дотримання найкращих практик бухгалтерського обліку. У цьому вичерпному посібнику ми розглянемо всі вбудовані плагіни, доступні в Beancount, і те, як їх ефективно використовувати.

Що таке плагіни Beancount?​

Плагіни Beancount — це модулі Python, які обробляють записи вашого леджера для додавання можливостей автоматизації, валідації або трансформації. Вони запускаються під час фази завантаження вашого файлу леджера і можуть:

  • Автоматизувати повторювані завдання (наприклад, створення оголошень рахунків)
  • Перевіряти цілісність даних (наприклад, пошук дублікатів транзакцій)
  • Трансформувати записи (наприклад, створення записів цін на основі транзакцій)
  • Впроваджувати правила обліку (наприклад, один актив на рахунок)

Як використовувати плагіни​

Щоб увімкнути плагін у вашому файлі Beancount, додайте директиву plugin у верхній частині вашого леджера:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Деякі плагіни приймають параметри конфігурації:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

Категорії вбудованих плагінів​

Вбудовані плагіни Beancount поділяються на чотири основні категорії:

1. Плагіни автоматизації​

2. Плагіни валідації​

3. Плагіни трансформації​

4. Мета-плагіни​

1. Плагіни автоматизації​

Ці плагіни автоматизують повторювані завдання з ведення обліку, заощаджуючи ваш час і зменшуючи кількість ручних помилок.

auto_accounts — Автоматичне оголошення рахунків​

Що він робить: Автоматично вставляє директиви Open для рахунків, які з'являються в транзакціях, але не були оголошені явно.

Навіщо використовувати: Усуває потребу вручну оголошувати кожен рахунок перед його використанням. Ідеально підходить для швидкого старту або для користувачів, які віддають перевагу мінімальній кількості шаблонного коду.

Приклад:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Без плагіна вам довелося б вручну додати:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

Коли використовувати: Ідеально для початківців або тих, хто хоче менш розлогий леджер. Однак явні оголошення рахунків допомагають виявляти друкарські помилки.

close_tree — Автоматичне закриття ієрархії рахунків​

Що він робить: Коли ви закриваєте батьківський рахунок, цей плагін автоматично закриває всі його дочірні рахунки.

Навіщо використовувати: Підтримує узгодженість у вашій ієрархії рахунків. Якщо ви закриваєте Assets:Investments, усі субрахунки, такі як Assets:Investments:Stocks та Assets:Investments:Bonds, будуть закриті автоматично.

Приклад:

plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; Ці рахунки будуть закриті автоматично:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Коли використовувати: При реструктуризації ієрархії рахунків або закритті цілих категорій рахунків.

implicit_prices — Автоматична генерація записів цін​

Що він робить: Синтезує директиви Price із проводок транзакцій, які включають вартість (@) або ціни (@@).

Навіщо використовувати: Автоматично наповнює вашу базу даних цін на основі транзакцій, дозволяючи створювати точні звіти про ринкову вартість без ручного введення цін.

Приклад:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Це автоматично згенерує:

2026-01-02 price AAPL  150.00 USD

Коли використовувати: Незамінний для відстеження інвестицій та мультивалютного обліку, де потрібна автоматична історія цін.

2. Плагіни валідації​

Ці плагіни забезпечують цілісність даних і дотримання найкращих практик бухгалтерського обліку, виявляючи помилки до того, як вони стануть проблемою.

noduplicates — Виявлення дублікатів транзакцій​

Що він робить: Перевіряє, щоб жодні дві транзакції не були ідентичними, обчислюючи та порівнюючи хеші даних транзакцій.

Навіщо використовувати: Запобігає випадковим дублікатам записів, особливо при імпорті транзакцій з кількох джерел.

Приклад:

plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

; Це викличе помилку:
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Коли використовувати: Рекомендується завжди, особливо якщо ви імпортуєте дані з банківських виписок або використовуєте кілька джерел даних.

check_commodity — Валідація оголошення активів​

Що він робить: Гарантує, що всі активи (commodities), які використовуються у вашому леджері, мають відповідні директиви Commodity.

Навіщо використовувати: Забезпечує обов'язкове явне оголошення активів, допомагаючи підтримувати чистий список активів та валют.

Приклад:

plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; Це викличе помилку без оголошення активу:
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Коли використовувати: Рекомендується для підтримки суворого відстеження активів та запобігання друкарським помилкам у тікерах.

check_average_cost — Валідація бази вартості​

Що робить: Перевіряє, чи правильно збережена база вартості в транзакціях, особливо при використанні обліку за середньою вартістю.

Навіщо використовувати: Гарантує, що ваш облік вартості залишається точним для податкової звітності та розрахунку приросту капіталу.

Коли використовувати: Критично важливо для інвестиційних портфелів та будь-яких сценаріїв, де важливе точне відстеження вартості.

check_closing — Валідація закриття балансу​

Що робить: Розгортає метадані closing у перевірки балансу, гарантуючи, що позиції стають нульовими після закриття угод.

Навіщо використовувати: Підтверджує, що при продажу всієї позиції баланс справді стає нульовим (не залишається дробових частин акцій).

Приклад:

plugin "beancount.plugins.check_closing"

2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15000.00 USD
  Income:Investments:Gains   -500.00 USD

Тег #closing вказує плагіну перевірити, чи став ваш баланс AAPL нульовим після цієї транзакції.

Коли використовувати: При продажу всієї позиції, щоб переконатися, що нічого не залишилося.

coherent_cost — Перевірка узгодженості валюти/вартості​

Що робить: Перевіряє, щоб валюти не використовувалися неузгоджено — одночасно з анотаціями вартості та без них.

Навіщо використовувати: Запобігає змішуванню чистих валют (наприклад, 100 USD) з валютами, що мають вартість (наприклад, 100 USD {1.2 CAD}), що може спричинити помилки в обліку.

Коли використовувати: Рекомендовано для мультивалютних журналів для підтримки узгодженості.

leafonly — Примусове використання кінцевих рахунків​

Що робить: Гарантує, що проводки здійснюються лише на кінцеві рахунки (рахунки, що не мають дочірніх рахунків).

Навіщо використовувати: Забезпечує чисту ієрархію рахунків, де узагальнювальні рахунки, як-от Expenses:Food, не мають прямих проводок, а лише їхні дочірні рахунки, наприклад Expenses:Food:Groceries та Expenses:Food:Restaurants.

Приклад:

plugin "beancount.plugins.leafonly"

; Це спричинить помилку:
2026-01-02 * "Grocery shopping"
  Expenses:Food              50.00 USD  ; Помилка: проводка має бути на кінцевий рахунок
  Assets:Cash               -50.00 USD

; Правильний спосіб:
2026-01-02 * "Grocery shopping"
  Expenses:Food:Groceries    50.00 USD  ; Правильно: проводка на кінцевий рахунок
  Assets:Cash               -50.00 USD

Коли використовувати: Якщо ви хочете підтримувати сувору ієрархію обліку з чіткою категоризацією.

nounused — Виявлення невикористаних рахунків​

Що робить: Визначає рахунки, які були відкриті, але ніколи не використовувалися в транзакціях.

Навіщо використовувати: Допомагає впорядкувати оголошення рахунків та виявити потенційні друкарські помилки або покинуті рахунки.

Коли використовувати: Періодично, для аудиту та очищення структури ваших рахунків.

onecommodity — Один актив на рахунок​

Що робить: Встановлює правило, за яким кожен рахунок може містити лише один тип активу (commodity).

Навіщо використовувати: Запобігає змішуванню різних активів на одному рахунку, що зазвичай вважається найкращою практикою бухгалтерського обліку.

Приклад:

plugin "beancount.plugins.onecommodity"

2026-01-02 * "Buy stocks"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD

; Це спричинить помилку:
2026-01-03 * "Buy more stocks"
  Assets:Investments         5 GOOGL @ 140 USD  ; Помилка: інший актив
  Assets:Cash              -700.00 USD

Коли використовувати: Якщо ви віддаєте перевагу суворому розділенню рахунків (один рахунок на кожну акцію/актив).

sellgains — Валідація приросту капіталу​

Що робить: Зіставляє задекларований приріст капіталу з розрахованим прибутком від продажу лотів, гарантуючи точність ваших розрахунків прибутків та збитків.

Навіщо використовувати: Виявляє помилки в ручних розрахунках приросту капіталу, що критично важливо для точної податкової звітності.

Приклад:

plugin "beancount.plugins.sellgains"

2026-01-02 * "Sell AAPL shares"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Плагін підтверджує, що це правильно

Плагін перевірить: Виручка від продажу (1500) - База вартості (1400) = Приріст (100)

Коли використовувати: Необхідно для всіх, хто торгує акціями, криптовалютою або іншими активами, де важливий приріст капіталу.

unique_prices — Перевірка унікальності цін​

Що робить: Гарантує наявність лише одного запису ціни для кожного активу на певну дату.

Навіщо використовувати: Запобігає суперечливим даним про ціни, які можуть призвести до неправильної оцінки активів.

Коли використовувати: Рекомендовано при ручному введенні цін або імпорті з кількох джерел.

3. Плагіни трансформації​

Ці плагіни корисним чином змінюють або розширюють дані вашого журналу.

currency_accounts — Рахунки для торгівлі валютою​

Що робить: Впроваджує рахунки для торгівлі валютою для явного відстеження форекс-конвертацій.

Навіщо використовувати: Забезпечує детальне відстеження транзакцій з конвертації валют, що корисно для стандартів обліку, які цього вимагають.

Коли використовувати: Якщо вам потрібно окремо відстежувати прибутки/збитки від форекс або відповідати специфічним вимогам обліку.

commodity_attr — Валідація атрибутів активів​

Що робить: Перевіряє, чи мають директиви товарів (активів) необхідні атрибути (такі як export, name тощо).

Навіщо використовувати: Гарантує, що метадані ваших активів є повними та узгодженими.

Коли використовувати: Якщо ви ведете детальні метадані активів для звітності або експорту.

4. Мета-плагіни​

Ці плагіни є наборами інших плагінів для зручності.

auto — усі автоматичні плагіни​

Призначення: Активує набір «м’яких» або автоматичних плагінів однією директивою.

Коли використовувати: Швидке налаштування для користувачів, яким потрібна максимальна автоматизація за мінімальної конфігурації.

pedantic — усі плагіни валідації​

Призначення: Активує всі плагіни суворої валідації одночасно.

Навіщо використовувати: Забезпечує максимальну цілісність даних і суворість обліку. Чудово підходить для основних бухгалтерських книг або коли точність має першочергове значення.

Приклад:

plugin "beancount.plugins.pedantic"

; Це еквівалентно активації:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Коли використовувати: Для основних книг, де ви хочете отримати максимальну перевірку і готові дотримуватися суворіших практик обліку.

Рекомендовані конфігурації плагінів​

Для початківців​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

Цей мінімальний набір забезпечує автоматизацію, запобігаючи поширеним помилкам.

Для інвесторів​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Орієнтований на відстеження інвестицій та точність розрахунку приросту капіталу.

Для суворого обліку​

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Максимальна валідація для робочих середовищ.

Стандартна конфігурація на Beancount.io​

На Beancount.io ми включаємо плагін auto_accounts за замовчуванням у всі нові файли головної книги:

plugin "beancount.plugins.auto_accounts"

Це забезпечує чудовий баланс між простотою використання та функціональністю для швидкого старту.

Найкращі практики​

  1. Почніть з мінімуму, додавайте за потреби: Почніть з auto_accounts та noduplicates, а потім додавайте плагіни валідації в міру розвитку вашої книги.

  2. Тестуйте плагіни окремо: Додаючи кілька плагінів, активуйте їх по одному, щоб зрозуміти їхній вплив.

  3. Уважно читайте повідомлення про помилки: Помилки плагінів часто вказують на реальні бухгалтерські проблеми, які потребують виправлення.

  4. Використовуйте pedantic для основних книг: Коли ваш робочий процес налагоджено, розгляньте можливість активації суворої валідації.

  5. Поєднуйте з користувацькими плагінами: Нативні плагіни працюють разом із користувацькими плагінами, такими як плагін прогнозування, для максимальної функціональності.

Поза межами нативних плагінів​

Хоча нативні плагіни забезпечують основну функціональність, екосистема Beancount включає багато плагінів, розроблених спільнотою для спеціалізованих потреб:

  • fava.plugins.forecast — для прогнозування регулярних транзакцій
  • fava.plugins.link_documents — для прив'язки транзакцій до файлів квитанцій
  • Користувацькі імпортери для CSV-форматів конкретних банків
  • Спеціалізовані податкові калькулятори та звіти

Дослідіть екосистему Beancount для пошуку інших варіантів.

Висновок​

Нативні плагіни Beancount перетворюють текстовий облік з ручного процесу на автоматизовану, перевірену та надійну систему управління фінансами. Розуміючи та використовуючи ці вбудовані інструменти, ви зможете:

  • ✅ Автоматизувати нудні бухгалтерські завдання
  • ✅ Виявляти помилки до того, як вони стануть проблемами
  • ✅ Підтримувати сувору цілісність даних
  • ✅ Створювати точні фінансові звіти
  • ✅ Зосередитися на фінансовому аналізі, а не на введенні даних

Почніть експериментувати з цими плагінами у своїй книзі вже сьогодні. Почніть з auto_accounts та implicit_prices, а потім поступово додавайте плагіни валідації в міру вдосконалення вашої практики обліку.

Готові спробувати ці плагіни? Перейдіть на Beancount.io і почніть використовувати їх у файлі вашої головної книги вже сьогодні!

Джерела​

Маєте запитання про плагіни Beancount? Приєднуйтесь до обговорення на нашому форумі спільноти або перегляньте нашу документацію.

References:
Share on TwitterFollow @beancount_io

Почніть роботу з Beancount.io

Візьміть фінанси під контроль з нашою відкритою системою подвійного запису. Почніть свій Ledger сьогодні.

Почати безкоштовноПереглянути ціни

Початок роботи

Функції

Спільнота

Юридична інформація

Beancount.io© 2019 - 2026 Beancount.io
Завантажити в App StoreЗавантажити в Google Play
Побудовано на прозорості • Контроль версій • На базі ШІ