Plugins natius essencials de Beancount que hauries de conèixer
La força de Beancount no resideix només en el seu format de text pla, sinó en la seva extensibilitat a través de connectors (plugins). Els connectors natius són mòduls integrats que milloren la funcionalitat de Beancount, automatitzen tasques tedioses i fan complir les millors pràctiques comptables. En aquesta guia completa, explorarem tots els connectors natius disponibles a Beancount i com utilitzar-los de manera eficaç.
Què són els connectors de Beancount?
Els connectors de Beancount són mòduls de Python que processen les entrades del vostre llibre de comptes per afegir capacitats d'automatització, validació o transformació. S'executen durant la fase de càrrega del fitxer del llibre i poden:
- Automatitzar tasques repetitives (per exemple, crear declaracions de comptes)
- Validar la integritat de les dades (per exemple, comprovar si hi ha transaccions duplicades)
- Transformar entrades (per exemple, generar entrades de preus a partir de transaccions)
- Fer complir regles comptables (per exemple, una única divisa o actiu per compte)
Com utilitzar els connectors
Per habilitar un connector al vostre fitxer Beancount, afegiu una directiva plugin a la part superior del llibre:
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
Alguns connectors accepten opcions de configuració:
plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"
Categories de connectors natius
Els connectors natius de Beancount es divideixen en quatre categories principals:
1. Connectors d'automatització
2. Connectors de validació
3. Connectors de transformació
4. Metaconnectors
1. Connectors d'automatització
Aquests connectors automatitzen tasques repetitives de comptabilitat, estalviant-vos temps i reduint els errors manuals.
auto_accounts - Declaracions automàtiques de comptes
Què fa: Insereix automàticament directives open per als comptes que apareixen a les transaccions però que no s'han declarat explícitament.
Per què utilitzar-lo: Elimina la necessitat de declarar manualment cada compte abans d'utilitzar-lo. És perfecte per començar ràpidament o per a usuaris que prefereixen un llibre de comptes amb el mínim codi repetitiu possible.
Exemple:
plugin "beancount.plugins.auto_accounts"
2026-01-01 * "Cafeteria"
Expenses:Food:Coffee 4.50 USD
Assets:Cash -4.50 USD
Sense el connector, hauríeu d'afegir manualment:
2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash
Quan utilitzar-lo: Ideal per a principiants o per a aquells que volen un llibre de comptes menys verbós. No obstant això, les declaracions explícites de comptes poden ajudar a detectar errors tipogràfics.
close_tree - Tancament automàtic de la jerarquia de comptes
Què fa: Quan tanqueu un compte pare, aquest connector tanca automàticament tots els seus comptes descendents.
Per què utilitzar-lo: Manté la coherència en la vostra jerarquia de comptes. Si tanqueu Assets:Investments, tots els subcomptes com Assets:Investments:Stocks i Assets:Investments:Bonds es tancaran automàticament.
Exemple:
plugin "beancount.plugins.close_tree"
2025-06-30 close Assets:Investments
; Aquests es tancaran automàticament:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate
Quan utilitzar-lo: Quan estigueu reestructurant la vostra jerarquia de comptes o tancant categories senceres de comptes.
implicit_prices - Generació automàtica d'entrades de preus
Què fa: Sintetitza directives price a partir dels apunts de les transaccions que inclouen costos (@) o preus (@@).
Per què utilitzar-lo: Omple la vostra base de dades de preus automàticament a partir de les transaccions, cosa que permet elaborar informes precisos sobre el valor de mercat sense haver d'introduir els preus manualment.
Exemple:
plugin "beancount.plugins.implicit_prices"
2026-01-02 * "Compra d'accions AAPL"
Assets:Investments:Stocks 10 AAPL @ 150.00 USD
Assets:Cash -1500.00 USD
Això genera automàticament:
2026-01-02 price AAPL 150.00 USD
Quan utilitzar-lo: Essencial per al seguiment d'inversions i la comptabilitat en múltiples divises on es vol tenir un historial de preus automàtic.
2. Connectors de validació
Aquests connectors fan complir la integritat de les dades i les millors pràctiques comptables, detectant errors abans que esdevinguin problemes.
noduplicates - Detecció de transaccions duplicades
Què fa: Comprova que no hi hagi dues transaccions idèntiques calculant i comparant els resums (hashes) de les dades de les transaccions.
Per què utilitzar-lo: Evita l'entrada accidental de transaccions duplicades, especialment quan s'importen dades de múltiples fonts.
Exemple:
plugin "beancount.plugins.noduplicates"
2026-01-02 * "Pagament del lloguer"
Expenses:Rent 1200.00 USD
Assets:Checking -1200.00 USD
; Això provocaria un error:
2026-01-02 * "Pagament del lloguer"
Expenses:Rent 1200.00 USD
Assets:Checking -1200.00 USD
Quan utilitzar-lo: Recomanat sempre, especialment si importeu extractes bancaris o utilitzeu diverses fonts de dades.
check_commodity - Validació de la declaració de commodities
Què fa: Garanteix que totes les commodities (actius o divises) utilitzades al vostre llibre de comptes tinguin les seves corresponents directives commodity.
Per què utilitzar-lo: Obliga a realitzar declaracions explícites de commodities, ajudant-vos a mantenir una llista neta d'actius i divises.
Exemple:
plugin "beancount.plugins.check_commodity"
2015-01-01 commodity USD
2020-01-01 commodity AAPL
; Això provocaria un error sense una declaració de commodity:
2026-01-02 * "Compra de Bitcoin"
Assets:Crypto 0.5 BTC @ 45000 USD
Assets:Cash -22500.00 USD
Quan utilitzar-lo: Recomanat per mantenir un seguiment estricte de les commodities i per evitar errors tipogràfics en els símbols dels actius.
check_average_cost - Validació de la base de cost
Què fa: Verifica que la base de cost es preservi correctament en les transaccions, especialment quan s'utilitza la comptabilització de cost mitjà.
Per què utilitzar-lo: Garanteix que la vostra comptabilitat de costos sigui precisa per a la presentació d'informes fiscals i els càlculs de plusvàlues.
Quan utilitzar-lo: Vital per a carteres d'inversió i qualsevol escenari on el seguiment precís dels costos sigui important.
check_closing - Validació de tancament de balanç
Què fa: Expandeix les metadades de closing en comprovacions de balanç, assegurant que les posicions siguin zero després de les operacions de tancament.
Per què utilitzar-lo: Confirma que quan veneu una posició sencera, el balanç és realment zero (no queden accions fraccionàries).
Exemple:
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
L'etiqueta #closing indica al complement que verifiqui que la vostra posició d'AAPL és zero després d'aquesta transacció.
Quan utilitzar-lo: En vendre posicions senceres per assegurar-vos que no en queda res.
coherent_cost - Verificació de consistència de moneda/cost
Què fa: Valida que les monedes no s'utilitzin de manera inconsistent — tant amb anotacions de cost com sense.
Per què utilitzar-lo: Evita barrejar monedes simples (com 100 USD) amb monedes amb cost (com 100 USD {1.2 CAD}), cosa que pot causar errors comptables.
Quan utilitzar-lo: Recomanat per a llibres majors multidivisa per mantenir la consistència.
leafonly - Aplicació de comptes fulla
Què fa: Assegura que només els comptes fulla (comptes sense fills) rebin apuntaments.
Per què utilitzar-lo: Imposa una jerarquia de comptes neta on els comptes de resum com Expenses:Food no tenen apuntaments directes, sinó només els seus fills com Expenses:Food:Groceries i Expenses:Food:Restaurants.
Exemple:
plugin "beancount.plugins.leafonly"
; This would trigger an error:
2026-01-02 * "Grocery shopping"
Expenses:Food 50.00 USD ; Error: Should post to a leaf account
Assets:Cash -50.00 USD
; Correct way:
2026-01-02 * "Grocery shopping"
Expenses:Food:Groceries 50.00 USD ; Correct: Posting to leaf account
Assets:Cash -50.00 USD
Quan utilitzar-lo: Quan vulgueu mantenir una comptabilitat jeràrquica estricta amb una categorització clara.
nounused - Detecció de comptes no utilitzats
Què fa: Identifica els comptes que s'han obert però que mai s'han utilitzat realment en cap transacció.
Per què utilitzar-lo: Us ajuda a netejar les vostres declaracions de comptes i a identificar possibles errors tipogràfics o comptes abandonats.
Quan utilitzar-lo: Periòdicament, per auditar i netejar la vostra estructura de comptes.
onecommodity - Una sola mercaderia per compte
Què fa: Imposa que cada compte contingui només un tipus de mercaderia.
Per què utilitzar-lo: Evita barrejar diferents actius en el mateix compte, la qual cosa és generalment una bona pràctica comptable.
Exemple:
plugin "beancount.plugins.onecommodity"
2026-01-02 * "Buy stocks"
Assets:Investments 10 AAPL @ 150 USD
Assets:Cash -1500.00 USD
; This would trigger an error:
2026-01-03 * "Buy more stocks"
Assets:Investments 5 GOOGL @ 140 USD ; Error: Different commodity
Assets:Cash -700.00 USD
Quan utilitzar-lo: Quan preferiu una separació estricta de comptes (un compte per acció/actiu).
sellgains - Validació de plusvàlues
Què fa: Comprova les plusvàlues declarades amb els guanys calculats a partir de les vendes de lots, assegurant que els càlculs de pèrdues i guanys siguin exactes.
Per què utilitzar-lo: Detecta errors en els càlculs manuals de plusvàlues, fet que és fonamental per a una declaració d'impostos precisa.
Exemple:
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 ; Plugin validates this is correct
El complement verificarà: Ingressos de la venda (1500) - Base de cost (1400) = Plusvàlues (100)
Quan utilitzar-lo: Essencial per a qualsevol persona que operi amb accions, criptomonedes o altres actius on les plusvàlues siguin rellevants.
unique_prices - Verificació d'unicitat de preus
Què fa: Assegura que només hi hagi una entrada de preu per mercaderia i data.
Per què utilitzar-lo: Evita dades de preus conflictives que podrien conduir a valoracions incorrectes.
Quan utilitzar-lo: Recomanat quan s'introdueixen preus manualment o quan s'importen de múltiples fonts de preus.
3. Complements de transformació
Aquests complements modifiquen o milloren les dades del vostre llibre major de maneres útils.
currency_accounts - Comptes de negociació de divises
Què fa: Implementa comptes de negociació de divises per fer un seguiment explícit de les conversions de moneda estrangera.
Per què utilitzar-lo: Proporciona un seguiment detallat de les transaccions de conversió de divises, útil per a les normes comptables que ho requereixen.
Quan utilitzar-lo: Quan necessiteu fer un seguiment dels guanys/pèrdues de divises per separat o complir requisits comptables específics.
commodity_attr - Validació d'atributs de mercaderia
Què fa: Valida que les directives de mercaderia (commodity) tinguin els atributs requerits (com export, name, etc.).
Per què utilitzar-lo: Assegura que les metadades de la mercaderia estiguin completes i siguin consistents.
Quan utilitzar-lo: Quan mantingueu metadades detallades de la mercaderia per a finalitats d'informes o d'exportació.
4. Meta-plugins
Aquests suplements són col·leccions d'altres suplements per a més comoditat.
auto - Tots els suplements automàtics
Què fa: Habilita una col·lecció de suplements "relaxats" o automàtics en una sola directiva.
Quan utilitzar-lo: Configuració ràpida per a usuaris que volen el màxim d'automatització amb el mínim de configuració.
pedantic - Tots els suplements de validació
Què fa: Habilita tots els suplements de validació estricta a la vegada.
Per què utilitzar-lo: Imposa la màxima integritat de les dades i rigor comptable. Ideal per a llibres majors de producció o quan la precisió és primordial.
Exemple:
plugin "beancount.plugins.pedantic"
; Això és equivalent a habilitar:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices
Quan utilitzar-lo: Per a llibres majors de producció on es vulgui la màxima validació i s'estigui disposat a mantenir pràctiques comptables més estrictes.
Configuracions de suplements recomanades
Per a principiants
plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"
Aquest conjunt mínim ofereix automatització alhora que evita errors comuns.
Per a inversors
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"
Se centra en el seguiment de les inversions i en la precisió dels guanys de capital.
Per a una comptabilitat estricta
plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"
Validació màxima per a entorns de producció.
Configuració per defecte a Beancount.io
A Beancount.io, incloem el suplement auto_accounts per defecte en tots els fitxers de llibre major nous:
plugin "beancount.plugins.auto_accounts"
Això proporciona un gran equilibri entre facilitat d'ús i funcionalitat per començar ràpidament.
Bones pràctiques
-
Comença pel mínim i afegeix segons calgui: Comença amb
auto_accountsinoduplicates, i després afegeix suplements de validació a mesura que el teu llibre major maduri. -
Prova els suplements individualment: Quan afegeixis diversos suplements, habilita'ls un per un per entendre'n els efectes.
-
Llegeix els missatges d'error amb atenció: Els errors dels suplements sovint indiquen problemes comptables reals que cal corregir.
-
Utilitza
pedanticper a la producció: Un cop establert el teu flux de treball, considera la possibilitat d'habilitar la validació estricta. -
Combina'ls amb suplements personalitzats: Els suplements natius funcionen conjuntament amb suplements personalitzats com el suplement de previsió (forecast) per a una funcionalitat màxima.
Més enllà dels suplements natius
Tot i que els suplements natius proporcionen la funcionalitat bàsica, l'ecosistema de Beancount inclou molts suplements desenvolupats per la comunitat per a necessitats especialitzades:
- fava.plugins.forecast - Per a la previsió de transaccions recurrents
- fava.plugins.link_documents - Per enllaçar transaccions amb fitxers de rebuts
- Importadors personalitzats per a formats CSV específics de bancs
- Calculadores i informes específics per a impostos
Explora l'ecosistema de Beancount per veure més opcions.
Conclusió
Els suplements natius de Beancount transformen la comptabilitat en text pla d'un procés manual a un sistema de gestió financera automatitzat, validat i robust. Entenent i aprofitant aquestes eines integrades, podràs:
- ✅ Automatitzar tasques de comptabilitat tedioses
- ✅ Detectar errors abans que es converteixin en problemes
- ✅ Mantenir una integritat de les dades estricta
- ✅ Generar informes financers precisos
- ✅ Centrar-te en la informació financera en lloc de l'entrada de dades
Comença a experimentar amb aquests suplements al teu llibre major avui mateix. Comença amb auto_accounts i implicit_prices, i després afegeix gradualment suplements de validació a mesura que les teves pràctiques comptables madurin.
Estàs a punt per provar aquests suplements? Ves a Beancount.io i comença a utilitzar-los al teu fitxer de llibre major avui mateix!
Fonts
- Beancount Plugins API Reference
- Beancount Scripting & Plugins Guide
- Beancount Plugins and Options by Bryan Alves
- Beancount GitHub Repository
Tens preguntes sobre els suplements de Beancount? Uneix-te a la discussió al nostre fòrum de la comunitat o consulta la nostra documentació.
