Com els scripts de Python automatitzen Beancount i Fava

Beancount (una eina de comptabilitat de partida doble en text pla) i Fava (la seva interfície web) són altament extensibles i programables. El seu disseny et permet automatitzar tasques financeres, generar informes personalitzats i configurar alertes escrivint scripts de Python. En paraules d'un usuari, «M'agrada molt tenir les meves dades en un format tan convenient, i m'agrada poder automatitzar coses tant com vulgui. No hi ha cap API com un fitxer al teu disc; és fàcil d'integrar.» Aquesta guia repassarà la creació de fluxos de treball programables—des d'automatitzacions aptes per a principiants fins a connectors avançats de Fava.

Explora un llibre major d'exemple en directe:

Comença amb la línia d'ordres bea​

Abans d'escriure cap Python, comprova si bea ja fa la feina. Valida el llibre major, executa consultes BQL, produeix els quatre informes financers i importa extractes bancaris, i l'opció global --json converteix cadascun d'aquests en un sobre analitzable que la teva shell pot canalitzar cap a jq. Els seus codis de sortida són el contracte sobre el qual es ramifica una tasca programada, de manera que cron o CI no necessiten cap script carregador. Consulta automatitza la comptabilitat amb bea per a la resolució d'objectius, el sobre i la ramificació per codis de sortida, i torna aquí quan necessitis un càlcul personalitzat que la CLI no exposa.

Per començar: Executar Beancount com a script de Python​

Per als scripts personalitzats de Python que es mostren a continuació, instal·la les biblioteques d'scripting (pip install beancount beanquery beangulp). Els fluxos de treball de la comanda bea utilitzen el motor gestionat; segueix la guia ràpida de la CLI per instal·lar-lo. Com que Beancount està escrit en Python, pots fer-lo servir com a biblioteca en els teus propis scripts. Els scripts següents es van executar amb Beancount 3.2.3, beanquery 0.2.0 i beangulp 0.2.0. L'enfocament general és:

• Carrega el teu llibre major de Beancount: Utilitza el carregador de Beancount per analitzar el fitxer .beancount en objectes de Python. Per exemple:

  from beancount import loader
  entries, errors, options = loader.load_file("myledger.beancount")
  if errors:
      for error in errors:
          print(error)
      raise SystemExit(1)

  El carregador retorna entrades i errors junts. Un fitxer desequilibrat o invàlid encara retorna entrades, així que comprova errors i atura't abans de confiar en les dades. Tots els teus comptes, transaccions i saldos són ara accessibles en codi.

• Aprofita el Llenguatge de Consulta de Beancount (BQL): En lloc d'iterar manualment, pots executar consultes semblants a SQL sobre les dades. Les consultes viuen al paquet separat beanquery. No hi ha cap mòdul beancount.query a Beancount 3.2.3. Per exemple, per obtenir les despeses totals per mes, connecta les entrades carregades i executa la consulta directament:

  import beanquery
   
  conn = beanquery.connect("beancount:", entries=entries, errors=errors, options=options)
  cur = conn.execute(
      "SELECT year, month, sum(position) WHERE account ~ 'Expenses' GROUP BY year, month"
  )
  for row in cur.fetchall():
      print(row)

  Això fa servir beanquery per agregar dades. És el mateix motor que hi ha darrere de bea query, però aquí el crides des d'un script. Això evita invocar una comanda externa en un bucle.

• Configura una estructura de projecte: Organitza els teus scripts al costat del teu llibre major. Una disposició habitual és tenir directoris per a importadors (per obtenir/analitzar dades externes), informes o consultes (per a scripts d'anàlisi), i documents (per emmagatzemar extractes descarregats). Per exemple, un usuari manté:

  • importers/ – scripts d'importació personalitzats de Python (amb proves),
  • queries/ – scripts per generar informes (executables via python3 queries/...),
  • documents/ – CSVs/PDFs bancaris descarregats organitzats per compte.

Amb aquesta configuració, pots executar els scripts manualment (per exemple, python3 queries/cash_flow.py) o programar-los (via cron o un gestor de tasques) per automatitzar el teu flux de treball.

Automatització de tasques de conciliació​

La conciliació significa assegurar-se que el teu llibre major coincideix amb els registres externs (extractes bancaris, informes de targetes de crèdit, etc.). El llibre major en text pla i l'API de Python de Beancount fan possible automatitzar bona part d'aquest procés.

Importació i concordança de transaccions (Nivell inicial)​

Per als principiants, l'enfocament recomanat és utilitzar importadors del paquet separat beangulp. Beancount 3 va eliminar el mòdul d'ingesta de la v2 i la seva comanda extract. Escrius una petita classe de Python que hereta de beangulp.Importer per analitzar un format determinat (CSV, OFX, PDF, etc.) i produir transaccions. Registra-la en un script d'ingesta curt i després executa-la mitjançant bea ingest al motor gestionat:

• Escriu un importador (una classe de Python amb els mètodes identify(), account() i extract()) per al format CSV del teu banc.
• Afegeix un script d'ingesta que registri els teus importadors. bea ingest executa les comandes identify, extract i archive de l'script. Per exemple, un flux de treball executa extract sobre tots els fitxers de ~/Downloads i envia les transaccions a un fitxer temporal.
• Revisa manualment i copia les transaccions del fitxer temporal al teu llibre major principal, després executa bea check per assegurar-te que els saldos quadren.

Un exemple mínim: un statement.csv amb les columnes date,description,amount, analitzat per aquest importador (checking_importer.py):

import csv
import datetime
from beancount.core import data
from beancount.core.amount import Amount
from beancount.core.number import D
import beangulp
 
 
class CheckingImporter(beangulp.Importer):
    def identify(self, filepath: str) -> bool:
        return filepath.endswith("statement.csv")
 
    def account(self, filepath: str) -> str:
        return "Assets:Bank:Checking"
 
    def extract(self, filepath: str, existing):
        entries = []
        with open(filepath, newline="") as f:
            for row in csv.DictReader(f):
                date = datetime.date.fromisoformat(row["date"])
                amount = Amount(D(row["amount"]), "USD")
                meta = data.new_metadata(filepath, 0)
                entries.append(
                    data.Transaction(
                        meta, date, "*", None, row["description"],
                        data.EMPTY_SET, data.EMPTY_SET, [
                            data.Posting("Expenses:Food:Groceries", amount,
                                         None, None, None, None),
                            data.Posting("Assets:Bank:Checking",
                                         Amount(-amount.number, "USD"),
                                         None, None, None, None),
                        ]))
        return entries

L'script d'ingesta (ingest.py) el connecta:

from checking_importer import CheckingImporter
from beangulp import Ingest
 
ingest = Ingest([CheckingImporter()])
 
if __name__ == "__main__":
    ingest()

Executa'l contra un fitxer descarregat. No calen credencials per a un CSV local. Instal·la primer la biblioteca del sistema libmagic. La comanda d'habilitació d'una sola vegada descarrega Beangulp al motor gestionat:

bea engine enable beangulp
bea ingest identify --config ingest.py statement.csv
bea ingest extract --config ingest.py statement.csv -o new.beancount

identify informa de checking_importer.CheckingImporter per al fitxer. extract escriu les transaccions en format Beancount:

2024-01-08 * "Grocery Store"
  Expenses:Food:Groceries   120.00 USD
  Assets:Bank:Checking     -120.00 USD

Revisa new.beancount, copia les entrades al teu llibre major principal i executa bea check.

Tot i que aquest procés encara implica un pas de revisió, bona part de la feina feixuga d'analitzar i formatar entrades queda automatitzada. Els scripts d'importació també poden assignar categories automàticament i fins i tot establir asserccions de saldo (declaracions de saldos esperats) per detectar discrepàncies. Per exemple, després d'importar, podries tenir una línia com 2025-04-30 balance Assets:Bank:Checking 1234.56 USD que afirma el saldo de tancament. Quan executes bea check, Beancount verificarà que totes aquestes assercions de saldo són correctes, i assenyalarà qualsevol error si falten transaccions o estan duplicades. Aquesta és una bona pràctica: genera automàticament assercions de saldo per a cada període d'extracte per deixar que l'ordinador detecti les diferències no conciliades per tu.

Scripts de conciliació personalitzats (Intermedi)​

Per a més control, pots escriure un script personalitzat de Python per comparar la llista de transaccions d'un banc (CSV o via API) amb les entrades del teu llibre major:

1. Llegeix les dades externes: Analitza el fitxer CSV del banc amb el mòdul csv de Python (o Pandas). Normalitza les dades en una llista de transaccions, per exemple cadascuna amb una data, un import i una descripció.
2. Carrega les transaccions del llibre major: Fes servir loader.load_file tal com es mostra més amunt per obtenir totes les entrades del llibre major. Filtra aquesta llista pel compte d'interès (per exemple, el teu compte corrent) i potser pel rang de dates de l'extracte.
3. Compara i troba discrepàncies:

• Per a cada transacció externa, comprova si existeix una entrada idèntica al llibre major (coincidència per data i import, potser descripció). Si no es troba, marca-la com a «nova» i possiblement envia-la com una transacció en format Beancount perquè la revisis.
• A la inversa, identifica qualsevol entrada del llibre major en aquest compte que no aparegui a la font externa – podrien ser errors d'entrada de dades o transaccions que no s'han compensat al banc.

4. Envia els resultats: Imprimeix un informe o crea un fragment .beancount nou amb les transaccions que falten.

Com a exemple, un script de la comunitat anomenat reconcile.py fa exactament això: donat un fitxer de Beancount i un CSV d'entrada, imprimeix una llista de transaccions noves que s'haurien d'importar, així com qualsevol apunt existent al llibre major que no sigui a l'entrada (possiblement un senyal de classificació errònia). Amb aquest script, la conciliació mensual pot ser tan simple com executar-lo i després afegir les transaccions suggerides al teu llibre major. Un usuari de Beancount assenyala que «fa un procés de conciliació de tots els comptes cada mes» i utilitza una col·lecció creixent de codi Python per eliminar bona part de la feina manual d'importar i conciliar dades.

Consell: Durant la conciliació, aprofita les eines de Beancount per a la precisió:

• Utilitza asserccions de saldo tal com s'ha esmentat, per tenir comprovacions automatitzades dels saldos dels comptes.
• Utilitza la directiva pad si vols, que pot inserir automàticament entrades de quadre per a petites diferències d'arrodoniment (utilitza-la amb precaució).
• Escriu proves unitàries per a la teva lògica d'importació o conciliació (Beancount proporciona ajudants de prova). Per exemple, un flux de treball consistia a agafar un CSV de mostra, escriure proves que fallaven amb les transaccions esperades, i després implementar l'importador fins que totes les proves passaven. Això assegura que el teu script d'importació funcioni correctament per a diversos casos.

Generació d'informes i resums personalitzats​

Tot i que Fava proporciona molts informes estàndard (Compte de resultats, Balanç, etc.), pots crear informes personalitzats amb scripts. Aquests poden anar des de sortides simples per consola fins a fitxers amb format ric o gràfics.

Consulta de dades per a informes (Nivell principiant)​

A un nivell bàsic, pots utilitzar el Llenguatge de Consulta de Beancount (BQL) per obtenir dades de resum i imprimir-les o desar-les. Per exemple:

• Resum de flux de caixa: Utilitza una consulta per calcular el flux de caixa net. El «flux de caixa» es podria definir com el canvi de saldo de certs comptes durant un període. Amb BQL, podries fer:

  SELECT year, month, sum(position)
  WHERE account ~ 'Income' OR account ~ 'Expenses'
  GROUP BY year, month

  Això neteja tots els apunts d'ingressos i despeses per mes. Filtra amb ~ i una expressió regular: LIKE és un error de sintaxi a beanquery 0.2.0. Els apunts porten position, no amount. Cada fila conté un Inventory, així que cada divisa es llista per separat en lloc de convertir-se. Els ingressos arriben en negatiu i les despeses en positiu. Podries executar-ho mitjançant bea query o via l'API de Python de beanquery mostrada més amunt, i després formatar el resultat.

• Informe de despeses per categoria: Consulta les despeses totals per categoria:

  SELECT account, sum(position)
  WHERE account ~ 'Expenses'
  GROUP BY account
  ORDER BY sum(position) ASC

  Això produeix una taula de despeses per categoria. Cada total és un Inventory en la seva divisa original. No embolcallis l'agregat en round(): no hi ha cap funció round(inventory, int), així que round(sum(position), 2) no compila. Pots executar diverses consultes en un script i enviar els resultats com a text, CSV o fins i tot JSON per a processament posterior.

Un usuari va trobar «trivial» analitzar dades financeres amb Fava o amb scripts, citant que fa servir un script de Python per extreure dades de Beancount via el Llenguatge de Consulta i després posar-les en un DataFrame de Pandas per preparar un informe personalitzat. Per exemple, podries obtenir els totals mensuals amb una consulta i després utilitzar Pandas/Matplotlib per traçar un gràfic de flux de caixa al llarg del temps. La combinació de BQL i biblioteques de ciència de dades et permet construir informes més enllà del que Fava ofereix per defecte.

Informes avançats (Gràfics, Rendiment, etc.)​

Per a necessitats més avançades, els teus scripts poden calcular mètriques com el rendiment d'inversions o crear sortides visuals:

• Rendiment d'inversions (TIR/XIRR): Com que el teu llibre major conté tots els fluxos de caixa (compres, vendes, dividends), pots calcular les taxes de rendiment de la cartera. Per exemple, podries escriure un script que filtri les transaccions dels teus comptes d'inversió i després calculi la Taxa Interna de Rendiment. Hi ha biblioteques (o fórmules) per calcular la TIR donades les dades de flux de caixa. Algunes extensions de Fava desenvolupades per la comunitat (com PortfolioSummary o fava_investor) fan exactament això, calculant la TIR i altres mètriques per a carteres d'inversió. Com a script, podries utilitzar una funció de TIR (de NumPy o pròpia) sobre la sèrie d'aportacions/retirades més el valor final.

• Mètriques multiperíode o personalitzades: Vols un informe de la teva taxa d'estalvi (proporció d'estalvis sobre ingressos) cada mes? Un script de Python pot carregar el llibre major, sumar tots els comptes d'Ingressos i tots els comptes de Despeses, i després calcular estalvis = ingressos - despeses i el percentatge. Això podria produir una taula bonica o fins i tot generar un informe HTML/Markdown per als teus registres.

• Visualització: Pots generar gràfics fora de Fava. Per exemple, utilitza matplotlib o altair en un script per crear un gràfic de patrimoni net al llarg del temps, fent servir les dades del llibre major. Com que el llibre major té tots els saldos històrics (o pots acumular-los iterant les entrades), pots produir gràfics de sèries temporals. Desa aquests gràfics com a imatges o HTML interactiu. (Si prefereixes visuals dins l'aplicació, consulta la secció d'extensions de Fava més avall per afegir gràfics dins de Fava.)

Opcions de sortida: Decideix com lliurar l'informe:

• Per a una anàlisi puntual, imprimir a pantalla o desar en un fitxer CSV/Excel podria ser suficient.
• Per a taulers de control, considera generar un fitxer HTML amb les dades (possiblement utilitzant una biblioteca de plantilles com Jinja2 o fins i tot escrivint només Markdown) que puguis obrir en un navegador.
• També pots integrar-te amb Jupyter Notebooks per a un entorn d'informes interactiu, tot i que això és més per a exploració que per a automatització.

Disparar alertes des del vostre llibre major​

Un altre ús potent dels fluxos de treball programables és configurar alertes basades en condicions de les teves dades financeres. Com que el teu llibre major s'actualitza regularment (i pot incloure elements amb data futura com factures properes o pressupostos), pots escanejar-lo amb un script i rebre notificacions d'esdeveniments importants.

Avisos de saldo baix del compte​

Per evitar descobriments o mantenir un saldo mínim, podries voler una alerta si algun compte (per exemple, corrent o estalvis) baixa per sota d'un llindar. Aquí tens com implementar-ho:

1. Determina els saldos actuals: Després de carregar entries via el carregador, calcula el saldo més recent dels comptes d'interès. Pots fer-ho agregant apunts o utilitzant una consulta. Per exemple, fes servir una consulta BQL per al saldo d'un compte específic:

   SELECT sum(position) WHERE account = 'Assets:Bank:Checking'

   Això retorna el saldo actual d'aquest compte (suma de tots els seus apunts). Alternativament, utilitza les funcions internes de Beancount per construir un balanç. Per exemple:

   from beancount.core import realization
   tree = realization.realize(entries)
   acct = realization.get_or_create(tree, "Assets:Bank:Checking")
   balance = acct.balance  # an Inventory of commodities

   Passa només les entrades: el segon paràmetre és min_accounts, no el mapa d'opcions. Després extreu el valor numèric (per exemple, balance.get_currency_units('USD') retorna l'import Decimal en USD). Com un agregat de consulta, el saldo manté cada divisa per separat. Tot i això, utilitzar la consulta és més simple per a la majoria de casos.

2. Comprova el llindar: Compara el saldo amb el teu límit predefinit. Si està per sota, dispara una alerta.

3. Dispara la notificació: Això podria ser tan simple com imprimir un avís a la consola, però per a alertes reals podries enviar un correu electrònic o una notificació push. Pots integrar-te amb el correu electrònic (via smtplib) o un servei com IFTTT o l'API de webhook de Slack per enviar l'alerta. Per exemple:

   if balance < 1000:
       send_email("Low balance alert", f"Account XYZ balance is {balance}")

   (Implementa send_email amb els detalls del teu servidor de correu.)

Executant aquest script diàriament (via una tasca cron o el Programador de tasques de Windows), obtindràs avisos proactius. Com que utilitza el llibre major, pot considerar totes les transaccions, incloent-hi les que acabes d'afegir.

Terminis de pagament propers​

Si utilitzes Beancount per fer seguiment de factures o terminis, pots marcar pagaments futurs i fer que els scripts t'ho recordin. Dues maneres de representar obligacions properes a Beancount:

• Esdeveniments: Beancount admet una directiva event per a notes arbitràries amb data. Per exemple:

  2025-05-10 event "BillDue" "Mortgage payment due"

  Això no afecta els saldos però registra una data amb una etiqueta. Un script pot escanejar entries a la recerca d'entrades Event on Event.type == "BillDue" (o qualsevol tipus personalitzat que triïs) i comprovar si la data està dins, per exemple, dels propers 7 dies a partir d'avui. Si és així, dispara una alerta (correu electrònic, notificació o fins i tot un popup).

• Transaccions futures: Algunes persones introdueixen transaccions amb data futura (postdatades) per a coses com pagaments programats. Aquestes no apareixeran als saldos fins que passi la data (llevat que executis informes amb dates futures). Un script pot buscar transaccions datades en un futur proper i llistar-les.

Utilitzant aquestes, podries crear un script «recordatori» que, quan s'executi, produeixi una llista de tasques o factures properes. Integra't amb una API com Google Calendar o un gestor de tasques si vols crear recordatoris automàticament allà.

Detecció d'anomalies​

Més enllà de llindars o dates coneguts, pots programar alertes personalitzades per a patrons inusuals. Per exemple, si una despesa normalment mensual no s'ha produït (potser t'has oblidat de pagar una factura), o si la despesa d'una categoria és anormalment alta aquest mes, el teu script podria assenyalar-ho. Això normalment implica consultar dades recents i comparar-les amb l'historial (cosa que podria ser un tema avançat – possiblement emprant estadística o ML).

A la pràctica, molts usuaris es basen en la conciliació per detectar anomalies (transaccions inesperades). Si reps notificacions bancàries (com correus electrònics per a cada transacció), podries analitzar-les amb un script i afegir-les automàticament a Beancount, o com a mínim verificar que estan registrades. Un entusiasta fins i tot va configurar el seu banc per enviar correus d'alerta de transaccions, amb el pla d'analitzar-los i afegir-los al llibre major automàticament. Aquest tipus d'alerta dirigida per esdeveniments pot assegurar que cap transacció quedi sense registrar.

Ampliar Fava amb complements i vistes personalitzades​

Fava ja és programable a través del seu sistema d'extensions. Si vols que la teva automatització o els teus informes s'integrin directament a la interfície web, pots escriure una extensió de Fava (també anomenada connector) en Python.

Com funcionen les extensions de Fava: Una extensió és un mòdul de Python que defineix una classe que hereta de fava.ext.FavaExtensionBase. La registres al teu fitxer de Beancount mitjançant una opció personalitzada. Per exemple, si tens un fitxer myextension.py amb una classe MyAlerts(FavaExtensionBase), pots habilitar-la afegint al teu llibre major:

1970-01-01 custom "fava-extension" "myextension"

Quan Fava es carrega, importarà aquest mòdul i inicialitzarà la teva classe MyAlerts.

Les extensions poden fer diverses coses:

• Hooks: Es poden enganxar a esdeveniments del cicle de vida de Fava. Per exemple, after_load_file() es crida després que es carregui el llibre major. Podries utilitzar-ho per executar comprovacions o precalcular dades. Si volguessis implementar la comprovació de saldo baix dins de Fava, after_load_file podria iterar sobre els saldos dels comptes i potser emmagatzemar avisos (tot i que mostrar-los a la interfície podria requerir una mica més de feina, com llançar un FavaAPIError o utilitzar Javascript per mostrar una notificació).
• Informes/Pàgines personalitzats: Si la teva classe d'extensió estableix un atribut report_title, Fava afegirà una pàgina nova a la barra lateral per a ella. Després proporciones una plantilla (HTML/Jinja2) per al contingut d'aquesta pàgina. Així és com crees vistes completament noves, com un tauler de control o un resum que Fava no té per defecte. L'extensió pot recollir les dades que necessiti (pots accedir a self.ledger que té totes les entrades, saldos, etc.) i després renderitzar la plantilla.

Per exemple, l'extensió integrada portfolio_list de Fava afegeix una pàgina que llista les posicions de la teva cartera. Les extensions de la comunitat van més enllà:

• Taulers de control: El connector fava-dashboards permet definir gràfics i panells personalitzats (utilitzant biblioteques com Apache ECharts). Llegeix una configuració YAML de consultes a executar, les executa via Beancount i genera una pàgina de tauler de control dinàmica a Fava. En essència, uneix les dades de Beancount i una biblioteca de gràfics de JavaScript per produir visualitzacions interactives.
• Anàlisi de cartera: L'extensió PortfolioSummary (contribuïda per usuaris) calcula resums d'inversions (agrupant comptes, calculant la TIR, etc.) i els mostra a la interfície de Fava.
• Revisió de transaccions: Una altra extensió, fava-review, ajuda a revisar transaccions al llarg del temps (per exemple, per assegurar-te que no t'has deixat cap rebut).

Per crear una extensió simple tu mateix, comença heretant de FavaExtensionBase. Per exemple, una extensió mínima que afegeix una pàgina podria ser així:

from fava.ext import FavaExtensionBase
 
class HelloReport(FavaExtensionBase):
    report_title = "Hello World"
 
    def __init__(self, ledger, config):
        super().__init__(ledger, config)
        # any initialization, perhaps parse config if provided
 
    def after_load_file(self):
        # (optional) run after ledger is loaded
        print("Ledger loaded with", len(self.ledger.entries), "entries")

Si posessis això a hello.py i afegissis custom "fava-extension" "hello" al teu llibre major, Fava mostraria una pàgina nova «Hello World» (també necessitaries un fitxer de plantilla HelloReport.html en una subcarpeta templates per definir el contingut de la pàgina, llevat que l'extensió només utilitzi hooks). La plantilla pot utilitzar dades que adjuntis a la classe de l'extensió. Fava utilitza plantilles Jinja2, així que podries renderitzar les teves dades en una taula HTML o un gràfic en aquesta plantilla.

Nota: El sistema d'extensions de Fava és potent però es considera «inestable» (subjecte a canvis). Requereix una mica de familiaritat amb el desenvolupament web (HTML/JS) si fas pàgines personalitzades. Si el teu objectiu és simplement executar scripts o anàlisis, podria ser més fàcil mantenir-los com a scripts externs. Utilitza extensions de Fava quan vulguis una experiència personalitzada dins l'aplicació per al teu flux de treball.

Integració d'APIs i dades de tercers​

Un dels avantatges dels fluxos de treball programables és la capacitat d'incorporar dades externes. Aquí tens integracions habituals:

Per a preus de valoració allotjats, Live Prices ofereix includes gestionats sense un script programat d'obtenció de preus. Tria parells d'actius admesos i una divisa de cotització al selector. Els fluxos de treball locals basats en fitxers que es mostren a continuació continuen sent útils per a Beancount, Fava i informes reproduïbles upstream. Una actualització gestionada no crea cap commit de Git al teu llibre major.

• Tipus de canvi i matèries primeres: Beancount upstream no obté preus per si mateix, però proporciona una directiva price perquè els proporcioni tu. Pots automatitzar l'obtenció d'aquests preus. Per exemple, un script pot consultar una API (Yahoo Finance, Alpha Vantage, etc.) pel darrer tipus de canvi o preu d'una acció i afegir una entrada de preu al teu llibre major:

  2025-04-30 price BTC 30000 USD
  2025-04-30 price EUR 1.10 USD

  Hi ha eines com bea price, recolzades per Beanprice al motor gestionat, que obtenen cotitzacions diàries i les envien en format Beancount. Podries habilitar-la una vegada amb bea engine enable beanprice, i després programar bea price main.beancount per executar-se cada nit i actualitzar un fitxer include prices.beancount. O fer servir Python: per exemple, amb la biblioteca requests per cridar una API. La documentació de Beancount suggereix que per a actius cotitzats públicament, pots «invocar codi que descarregarà preus i escriurà les directives per tu». En altres paraules, deixa que un script faci la consulta i insereixi les línies price, en lloc de fer-ho manualment tu.

• Dades de carteres d'accions: De manera semblant als tipus de canvi, pots integrar-te amb API per obtenir dades detallades d'accions o dividends. Per exemple, l'API de Yahoo Finance (o biblioteques de la comunitat com yfinance) pot recuperar dades històriques d'un ticker. Un script podria actualitzar el teu llibre major amb l'historial de preus mensuals de cada acció que tinguis, permetent informes històrics precisos del valor de mercat. Algunes extensions personalitzades (com fava_investor) fins i tot obtenen dades de preus sobre la marxa per mostrar-les, però el més simple és importar preus regularment al llibre major.

• API bancàries (Open Banking/Plaid): En lloc de descarregar CSVs, pots utilitzar API per obtenir transaccions automàticament. Serveis com Plaid agreguen comptes bancaris i permeten accés programàtic a les transaccions. En una configuració avançada, podries tenir un script de Python que utilitzi l'API de Plaid per obtenir transaccions noves diàriament i desar-les en un fitxer (o importar-les directament al llibre major). Un usuari avançat va construir un sistema on Plaid alimentava el seu pipeline d'importació, fent els seus llibres gairebé automàtics. Assenyala que «res no impedeix registrar-te a l'API de Plaid i fer el mateix localment» – és a dir, pots escriure un script local per obtenir dades bancàries, i després utilitzar la teva lògica d'importació de Beancount per analitzar-les en entrades del llibre major. Algunes regions tenen API d'open banking proporcionades pels bancs; es podrien utilitzar de manera semblant.

• Altres API: Podries integrar eines de pressupostos (exportant pressupostos planificats per comparar amb els reals a Beancount), o utilitzar una API d'OCR per llegir rebuts i fer-los coincidir automàticament amb transaccions. Com que els teus scripts tenen accés complet a l'ecosistema de Python, pots integrar-ho tot, des de serveis de correu electrònic (per enviar alertes) fins a Google Sheets (per exemple, actualitzar un full amb mètriques financeres mensuals) fins a aplicacions de missatgeria (enviar-te un informe de resum via un bot de Telegram).

Quan utilitzis API de tercers, recorda protegir les teves credencials (utilitza variables d'entorn o fitxers de configuració per a les claus d'API), i gestionar els errors (problemes de xarxa, caigudes de l'API) amb gràcia als teus scripts. Sovint és prudent emmagatzemar dades a la memòria cau (per exemple, desar els tipus de canvi obtinguts per no sol·licitar el mateix tipus històric repetidament).

Bones pràctiques per a scripts modulals i mantenibles​

A mesura que construeixes fluxos de treball programables, mantén el teu codi organitzat i robust:

• Modularitat: Divideix les diferents preocupacions en scripts o mòduls diferents. Per exemple, tingues scripts separats per a «importació/conciliació de dades» vs. «generació d'informes» vs. «alertes». Fins i tot pots crear un petit paquet de Python per al teu llibre major amb mòduls com ledger_import.py, ledger_reports.py, etc. Això fa que cada part sigui més fàcil d'entendre i provar.

• Configuració: Evita valors codificats en dur. Utilitza un fitxer de configuració o variables a l'inici de l'script per a coses com noms de comptes, llindars, claus d'API, rangs de dates, etc. Això facilita els ajustos sense editar el codi a fons. Per exemple, defineix LOW_BALANCE_THRESHOLDS = {"Assets:Bank:Checking": 500, "Assets:Savings": 1000} a dalt, i el teu script d'alerta pot recórrer aquest diccionari.

• Proves: Tracta la teva automatització financera com a codi crític – perquè ho és! Escriu proves per a la lògica complexa. Beancount proporciona alguns ajudants de prova (utilitzats internament per a proves d'importadors) que pots aprofitar per simular entrades del llibre major. Fins i tot sense marcs sofisticats, pots tenir un CSV fictici i les transaccions de sortida esperades, i afirmar que el teu script d'importació produeix les entrades correctes. Si utilitzes pytest, pots integrar aquestes proves fàcilment (com va fer Alex Watt mitjançant una comanda just test que embolcalla pytest).

• Control de versions: Mantén el teu llibre major i els teus scripts sota control de versions (git). Això no només et dóna còpies de seguretat i historial, sinó que t'anima a fer canvis d'una manera controlada. Pots etiquetar versions dels teus «scripts financers» o revisar diferències quan depures un problema. Alguns usuaris fins i tot fan seguiment dels seus registres financers a Git per veure els canvis al llarg del temps. Només vés amb compte d'ignorar dades sensibles (com fitxers d'extractes en cru o claus d'API) al teu repositori.

• Documentació: Documenta els teus fluxos de treball personalitzats per al teu jo futur. Un README al teu repositori explicant com configurar l'entorn, com executar cada script i què fa cadascun serà invaluable després que hagin passat mesos. També comenta el teu codi, especialment qualsevol lògica comptable no òbvia o interacció amb API.

• Manteniment dels connectors de Fava: Si escrius una extensió de Fava, mantén-la simple. Fava podria canviar, així que les extensions més petites amb funcionalitat específica són més fàcils d'actualitzar. Evita duplicar massa lògica – utilitza el motor de consultes de Beancount o les funcions ajudants existents sempre que sigui possible, en lloc de codificar en dur càlculs que podrien ser sensibles als canvis del llibre major.

• Seguretat: Com que els teus scripts poden manejar dades sensibles i connectar-se a serveis externs, tracta'ls amb cura. No exposis claus d'API, i considera executar la teva automatització en una màquina segura. Si utilitzes una solució allotjada o al núvol (com programar GitHub Actions o un servidor per executar Fava), assegura't que les dades del teu llibre major estiguin xifrades en repòs i que estiguis còmode amb les implicacions de privacitat.

Seguint aquestes pràctiques, assegures que el teu flux de treball es mantingui fiable fins i tot a mesura que les teves finances (i les eines mateixes) evolucionen. Vols scripts que puguis reutilitzar any rere any, amb ajustos mínims.

Conclusió​

Beancount i Fava proporcionen una plataforma potent i flexible perquè els usuaris experts en tecnologia personalitzin completament el seguiment de les seves finances personals. Escrivint scripts de Python, pots automatitzar tasques feixugues com conciliar extractes, produir informes rics adaptats a les teves necessitats, i mantenir-te al dia de les teves finances amb alertes oportunes. Hem cobert una gamma d'exemples de bàsics a avançats – començant amb consultes simples i importacions de CSV, i passant a connectors de Fava complets i integracions amb API externes. A mesura que els implementis, comença simple i construeix gradualment. Fins i tot uns quants scripts d'automatització petits poden estalviar hores de feina i millorar enormement la precisió. I recorda, com que tot és text pla i Python, tens el control total – el teu sistema financer creix amb tu, adaptant-se a les teves necessitats específiques. Feliç scripting!

Fonts: Les tècniques anteriors es basen en la documentació de Beancount i en experiències de la comunitat. Per a més lectura, consulta la documentació oficial de Beancount, guies i blogs de la comunitat, i el repositori Awesome Beancount per enllaços a connectors i eines útils.