Com els scripts de Python automatitzen Beancount i Fava

Beancount (una eina de comptabilitat de doble entrada en text pla) i Fava (la seva interfície web) són altament extensibles i programables. El seu disseny 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 al meu gust. No hi ha cap API com un fitxer al teu disc; és fàcil d'integrar." Aquesta guia t'explicarà com crear fluxos de treball programables—des de l'automatització per a principiants fins a complements avançats de Fava.

Explora un llibre major d'exemple en viu:

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 les exportacions bancàries, i el --json global converteix cadascun d'aquests en un sobre analitzable que el teu shell pot canalitzar cap a jq. Els seus codis de sortida són el contracte sobre el qual es ramifica un treball programat, de manera que cron o CI no necessita cap script de càrrega. Consulta automatitza la comptabilitat amb bea per a la resolució de destinacions, el sobre i la ramificació per codi de sortida, i torna aquí quan necessitis un càlcul personalitzat que la CLI no exposi.

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

Per als scripts de Python personalitzats que es mostren a continuació, instal·la les biblioteques de scripting (pip install beancount beanquery beangulp). Els fluxos de treball amb l'ordre bea utilitzen el motor gestionat; segueix la guia d'inici ràpid de la CLI per instal·lar-lo. Com que Beancount està escrit en Python, pots utilitzar-lo com a biblioteca en els teus propis scripts. Els scripts següents s'han executat 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 juntament. Un fitxer desequilibrat o invàlid encara retorna entrades, així que comprova els errors i atura't abans de confiar en les dades. Tots els teus comptes, transaccions i saldos són ara accessibles al codi.

• Aprofita el Llenguatge de Consultes 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ò utilitza beanquery per agregar dades. És el mateix motor que hi ha darrere de bea query, però aquí el crides en un script. Això evita haver de cridar a una ordre externa en un bucle.

• Configura una estructura de projecte: Organitza els teus scripts juntament amb el teu llibre major. Una disposició habitual és tenir directoris per als 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ó de Python personalitzats (amb proves),
  • queries/ – scripts per generar informes (executables amb python3 queries/...),
  • documents/ – CSV/PDF bancaris descarregats organitzats per compte.

Amb aquesta configuració, pots executar scripts manualment (per exemple, python3 queries/cash_flow.py) o programar-los (mitjançant cron o un executor 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 de text pla de Beancount i la seva API de Python fan possible automatitzar gran 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'ingestió de la v2 i la seva ordre d'extracció. 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'ingestió curt i després executa-la mitjançant bea ingest al motor gestionat:

• Escriviu un importador (una classe Python amb els mètodes identify(), account() i extract()) per al format CSV del vostre banc.
• Afegiu un script d'ingestió que registri els vostres importadors. bea ingest executa les ordres identify, extract i archive de l'script. Per exemple, un flux de treball executa extract en tots els fitxers de ~/Downloads i genera les transaccions en un fitxer temporal.
• Reviseu manualment i copieu les transaccions del fitxer temporal al vostre llibre principal, i després executeu bea check per assegurar-vos 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'ingestió (ingest.py) ho connecta:

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

Executeu-lo contra un fitxer descarregat. No calen credencials per a un CSV local. Instal·leu primer la biblioteca del sistema libmagic. L'ordre d'activació única descarrega Beangulp a l'engine 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

Reviseu new.beancount, copieu les entrades al vostre llibre principal i executeu bea check.

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

Scripts de conciliació personalitzats (Intermedi)​

Per a més control, podeu escriure un script Python personalitzat per comparar la llista de transaccions d'un banc (CSV o mitjançant API) amb les entrades del vostre llibre:

1. Llegiu les dades externes: Analitzeu el fitxer CSV del banc mitjançant el mòdul csv de Python (o Pandas). Normalitzeu les dades en una llista de transaccions, p. ex. cadascuna amb una data, un import i una descripció.
2. Carregueu les transaccions del llibre: Utilitzeu loader.load_file com es mostra abans per obtenir totes les entrades del llibre. Filtreu aquesta llista al compte d'interès (p. ex. el vostre compte corrent) i potser a l'interval de dates de l'extracte.
3. Compareu i trobeu les discrepàncies:

• Per a cada transacció externa, comproveu si existeix una entrada idèntica al llibre (coincidiu per data i import, potser descripció). Si no es troba, marqueu-la com a "nova" i potser sortiu-la com a transacció formatada en Beancount perquè la reviseu.
• Inversament, identifiqueu les entrades del llibre en aquest compte que no apareixen a la font externa – podrien ser errors d'entrada de dades o transaccions que encara no s'han liquidat al banc.

4. Sortiu els resultats: Imprimiu un informe o creeu 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 Beancount i un CSV d'entrada, imprimeix una llista de transaccions noves que s'haurien d'importar, així com qualsevol assentament existent del llibre que no sigui a l'entrada (potencialment un signe de classificació errònia). Amb aquest script, la conciliació mensual pot ser tan senzilla com executar-lo i després afegir les transaccions suggerides al vostre llibre. Un usuari de Beancount assenyala que "fa un procés de conciliació en tots els comptes cada mes" i utilitza una col·lecció creixent de codi Python per eliminar gran part del treball manual en importar i conciliar dades.

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

• Utilitzeu assertions de saldo com s'ha esmentat, per tenir comprovacions automàtiques dels saldos dels comptes.
• Utilitzeu la directiva pad si ho desitgeu, que pot inserir automàticament entrades de conciliació per a petites diferències d'arrodoniment (utilitzeu-la amb precaució).
• Escriviu proves unitàries per al vostre importador o lògica de conciliació (Beancount proporciona ajudes de prova). Per exemple, un flux de treball implicava prendre un CSV de mostra, escriure proves fallides amb transaccions esperades, i després implementar l'importador fins que totes les proves van passar. Això assegura que el vostre script d'importació funciona correctament per a diversos casos.

Generació d'informes i resums personalitzats​

Mentre que Fava proporciona molts informes estàndard (Estat de resultats, Balanç de situació, etc.), podeu crear informes personalitzats utilitzant scripts. Aquests poden anar des de sortides simples de consola fins a fitxers formats o gràfics.

Consulta de dades per a informes (Nivell principiant)​

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

• Resum del flux de caixa: Utilitzeu una consulta per calcular el flux de caixa net. El "flux de caixa" podria definir-se com el canvi en el saldo de certs comptes durant un període. Amb BQL, podríeu fer:

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

  Això agrega totes les partides d'ingressos i despeses per mes. Filtreu amb ~ i una expressió regular: LIKE és un error de sintaxi a beanquery 0.2.0. Les partides porten position, no amount. Cada fila conté un Inventory, de manera que cada moneda es llista per separat en lloc de convertir-se. Els ingressos apareixen negatius i les despeses positives. Podríeu executar això a través de bea query o mitjançant l'API de Python de beanquery esmentada anteriorment, i després formatar el resultat.

• Informe de despeses per categoria: Consulteu el total de despeses 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 moneda original. No envolteu l'agregat amb round(): no hi ha funció round(inventory, int), així que round(sum(position), 2) no compila. Podeu executar múltiples consultes en un script i sortir els resultats com a text, CSV, o fins i tot JSON per a un processament posterior.

Un usuari va trobar que era "trivial" analitzar dades financeres amb Fava o amb scripts, citant que utilitzen un script de Python per extreure dades de Beancount a través del Llenguatge de Consulta i després posar-les en un DataFrame de Pandas per preparar un informe personalitzat. Per exemple, podríeu obtenir totals mensuals amb una consulta i després utilitzar Pandas/Matplotlib per representar un gràfic de flux de caixa al llarg del temps. La combinació de BQL i biblioteques de ciència de dades us 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 vostres scripts poden calcular mètriques com el rendiment d'inversions o crear sortides visuals:

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

• Mètriques multiperíode o personalitzades: Vols un informe de la teva taxa d'estalvi (ràtio d'estalvi 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 l'estalvi = ingressos - despeses i el percentatge. Això podria sortir una taula bonica o fins i tot generar un informe HTML/Markdown per als vostres registres.

• Visualització: Podeu generar gràfics fora de Fava. Per exemple, utilitzeu matplotlib o altair en un script per crear un gràfic de patrimoni net al llarg del temps, utilitzant dades del llibre major. Com que el llibre major té tots els saldos històrics (o podeu acumular-los iterant les entrades), podeu produir gràfics de sèrie temporal. Deseu aquests gràfics com a imatges o HTML interactiu. (Si preferiu visuals dins de l'aplicació, vegeu la secció d'extensions de Fava més avall per afegir gràfics dins de Fava.)

Opcions de sortida: Decidiu com lliurar l'informe:

• Per a anàlisis puntuals, imprimir a la pantalla o desar en un fitxer CSV/Excel pot ser suficient.
• Per a quadres de comandament, considereu generar un fitxer HTML amb les dades (possiblement utilitzant una biblioteca de plantilles com Jinja2 o fins i tot escrivint Markdown) que pugueu obrir en un navegador.
• També podeu integrar amb Jupyter Notebooks per a un entorn de generació d'informes interactius, 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 amb scripts és configurar alertes basades en condicions de les vostres dades financeres. Com que el vostre llibre major s'actualitza regularment (i pot incloure elements datats en el futur com factures properes o pressupostos), podeu analitzar-lo amb un script i rebre notificacions d'esdeveniments importants.

Avisos de saldo baix del compte​

Per evitar descobriments en descobert o per mantenir un saldo mínim, podeu voler una alerta si qualsevol compte (per exemple, compte corrent o d'estalvi) cau per sota d'un llindar. Aquí teniu com podeu implementar-ho:

1. Determineu els saldos actuals: Després de carregar entries mitjançant el carregador, calculeu el saldo més recent dels comptes d'interès. Podeu fer-ho agregant les anotacions o utilitzant una consulta. Per exemple, utilitzeu 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 totes les anotacions). Alternativament, utilitzeu les funcions internes de Beancount per construir un balanç de situació. 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

   Passeu 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 moneda per separat. Tanmateix, utilitzar la consulta és més senzill per a la majoria dels casos.

2. Comproveu el llindar: Compareu el saldo amb el vostre límit predefinit. Si està per sota, activeu una alerta.

3. Activeu la notificació: Això pot ser tan senzill com imprimir un avís a la consola, però per a alertes reals podeu enviar un correu electrònic o una notificació push. Podeu integrar amb correu electrònic (mitjançant 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}")

   (Implementeu send_email amb els detalls del vostre servidor de correu.)

En executar aquest script diàriament (mitjançant una tasca cron o el Programador de tasques de Windows), rebreu avisos proactius. Com que utilitza el llibre major, pot considerar totes les transaccions incloent les que acabeu d'afegir.

Terminis de pagament propers​

Si utilitzeu Beancount per fer el seguiment de factures o terminis, podeu marcar pagaments futurs i fer que els scripts us ho recordin. Dues maneres de representar obligacions properes a Beancount:

• Esdeveniments: Beancount admet una directiva event per a notes arbitràries datades. 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 analitzar entries per a entrades Event on Event.type == "BillDue" (o qualsevol tipus personalitzat que trieu) i comprovar si la data és dins, per exemple, dels propers 7 dies des d'avui. Si és així, activeu una alerta (correu electrònic, notificació o fins i tot un diàleg emergent).

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

Utilitzant aquestes, podríeu crear un script de "recordatori" que, quan s'executi, generi una llista de tasques o factures que vençen aviat. Integreu amb una API com Google Calendar o un gestor de tasques si voleu crear recordatoris automàticament.

Detecció d'anomalies​

Més enllà de llindars o dates conegudes, podeu programar alertes personalitzades per a patrons inusuals. Per exemple, si una despesa normalment mensual no ha ocorregut (potser heu oblidat pagar una factura), o si la despesa d'una categoria és anormalment alta aquest mes, el vostre script podria marcar-ho. Això normalment implica consultar dades recents i comparar amb l'historial (que pot ser un tema avançat – possiblement utilitzant estadístiques o ML).

A la pràctica, molts usuaris confien en la conciliació per detectar anomalies (transaccions inesperades). Si rebeu notificacions bancàries (com correus electrònics per a cada transacció), podríeu analitzar-les amb un script i afegir-les automàticament a Beancount, o almenys 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 mitjançant el seu sistema d'extensions. Si voleu que les vostres automatitzacions o informes s'integrin directament a la interfície web, podeu 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 registreu al vostre fitxer de Beancount mitjançant una opció personalitzada. Per exemple, si teniu un fitxer myextension.py amb una classe MyAlerts(FavaExtensionBase), la podeu activar afegint al vostre llibre major:

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

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

Les extensions poden fer diverses coses:

• Ganxos (hooks): Poden enganxar-se a esdeveniments del cicle de vida de Fava. Per exemple, after_load_file() es crida després que el llibre major es carregui. Podríeu utilitzar-ho per executar comprovacions o precalcular dades. Si volguéssiu implementar la comprovació de saldo baix dins de Fava, after_load_file podria iterar sobre els saldos dels comptes i emmagatzemar avisos (tot i que mostrar-los a la interfície pot requerir una mica més de feina, com llançar una FavaAPIError o utilitzar Javascript per mostrar una notificació).
• Informes/Pàgines personalitzats: Si la vostra classe d'extensió estableix un atribut report_title, Fava afegirà una nova pàgina a la barra lateral per a ella. Després proporcioneu una plantilla (HTML/Jinja2) per al contingut d'aquesta pàgina. Així és com creeu vistes completament noves, com un tauler de control o un resum que Fava no té per defecte. L'extensió pot recopilar qualsevol dàda que necessiti (podeu 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 vostres posicions de 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 llibreries com Apache ECharts). Llegeix un fitxer YAML de consultes per executar, les executà mediante Beancount, i genera una pàgina de tauler dinàmic a Fava. En essència, uneix les dàdes de Beancount amb una llibreria de gràfics JavaScrit per produir visualitzacions interactives.
• Anàlisi de cartera: L'extensió PortfolioSummary (contribuïda per usuaris) computa resums d'inversions (agrupant comptes, calculant IRR, 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-vos que no heu perdut cap rebut).

Per crear una extensió simple vosaltres mateixos, comenceu per subclassejar 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 col.loqueu això a hello.py i afegiu custom "fava-extension" "hello" al vostre llibre major, Fava mostrarà una nova pàgina "Hello World" (també necessitaríeu 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 ganxos). La plantilla pot utilitzar dades que adjunteu a la classe d'extensió. Fava utilitza plantilles Jinja2, així que podríeu renderitzar les vostres 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 certa familiaritat amb el desenvolupament web (HTML/JS) si esteu fent pàgines personalitzades. Si el vostre objectiu és simplement executar scripts o anàlisis, pot ser més fàcil mantenir-los com a scripts externs. Utilitzeu extensions de Fava quan vulgueu una experiència a mida dins de l'aplicació per al vostre 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í teniu integracions comunes:

• Tipus de canvi i matèries primeres: Beancount no obté preus automàticament per disseny (per mantenir els informes deterministes), però proporciona una directiva Price perquè proveïu les taxes. Podeu automatitzar la descàrrega d'aquests preus. Per exemple, un script pot consultar una API (Yahoo Finance, Alpha Vantage, etc.) per obtenir l'últim tipus de canvi o preu de les accions i afegir una entrada de preu al vostre 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 generen en format Beancount. Podeu activar-ho una vegada amb bea engine enable beanprice i després programar bea price main.beancount perquè s'executi cada nit i actualitzi un fitxer d'inclusió prices.beancount. O useu Python: p. ex., amb la biblioteca requests per cridar una API. La documentació de Beancount suggereix que per a actius negociats públicament podeu «invocar algun codi que descarregui preus i escrigui les directives per a vosaltres». En altres paraules, deixeu que un script faci la cerca i inseriu les línies de price, en lloc de fer-ho manualment.

• Dades de cartera d'accions: De manera similar als tipus de canvi, podeu integrar-vos amb API per obtenir dades detallades d'accions o dividends. Per exemple, l'API de Yahoo Finance (o biblioteques comunitàries com yfinance) pot recuperar dades històriques per a un ticker. Un script podria actualitzar el vostre llibre major amb un historial mensual de preus per a cada acció que tingueu, 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 visualitzar-les, però el més senzill és importar regularment els preus al llibre major.

• API bancàries (Open Banking/Plaid): En lloc de descarregar CSV, podeu 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, podríeu tenir un script de Python que utilitzi l'API de Plaid per obtenir noves transaccions 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 alimenta el seu pipeline d'importació, fent que els seus llibres siguin gairebé automàtics. Ells noten que «res no us impedeix registrar-vos amb l'API de Plaid i fer el mateix localment», és a dir, podeu escriure un script local per obtenir dades bancàries i després usar la vostra lògica d'importació de Beancount per processar-les en entrades del llibre major. Algunes regions tenen API de banca oberta proporcionades pels bancs; que es podrien utilitzar de manera similar.

• Altres API: Podeu integrar eines de pressupost (exportant pressupostos planificats per comparar amb els reals a Beancount), o utilitzar una API d'OCR per llegir rebuts i fer-ne la conciliació automàtica amb transaccions. Com que els vostres scripts tenen accés complet a l'ecosistema de Python, podeu integrar des de serveis de correu electrònic (per enviar alertes) fins a Google Sheets (p. ex., actualitzar un full amb mètriques financeres mensuals) fins a aplicacions de missatgeria (enviar-vos un informe resum mitjançant un bot de Telegram).

Quan utilitzeu API de tercers, recordeu protegir les vostres credencials (utilitzeu variables d'entorn o fitxers de configuració per a les claus API) i gestioneu els errors (problemes de xarxa, caigudes de l'API) de manera adequada als vostres scripts. Sovint és prudent emmagatzemar dades en cau (p. ex., emmagatzemar 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 construïu fluxus de treball automatitzats, manteniu el codi organitzat i robust:

• Modularitat: Separeu diferents preocupacions en diferents scripts o mòduls. Per exempre, tingueu scripts separats per a «importació/conciliació de dades» vs. «generació d'informes» vs. «alertes». Podeu fins i tot creur un paquet de Python petit per al vostre 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 de provar.

• Configuració: Eviteu codificar valors. Utilitzeu un fitxer de configuració o variables al principi del script per a coses com noms de comptes, llindars, claus API, rangs de dates, etc. Això facilita l'ajust sense haver de modificar el codi en profunditat. Per exempre, definiu LOW_BALANCE_THRESHOLDS = {"Assets:Bank:Checking": 500, "Assets:Savings": 1000} al principi, i el vostre script d'alertes pot recòrrer aquest diccionari.

• Provves: Trecteu la vostra automatizació financer com a codi crític per a la missió – perquè ho és! Escriviu provves per a la lògica complexa. Beancount proporciona alguns ajudants de provva (utilitzats internament per a les provves d'importadors) que podeu aprofitar per simular entradaes al llibre major. Fins i tot sense marc us sofisticats, podeu tenir un CSV fictici i transaccions de sortida esperades, i verificar que el vostre script d'importació produeix les entradaes correctes. Si utilitzeu pytest, podeu integrar aquestes provves fàcilment (com va fer Alex Watt mitjançant una comanda just test que envolta pytest).

• Control de versions: Mantingueu el vostre llibre major i scripts sota control de versions (git). Això no només us proporciona còpies de seguretat i historial, sinó que us anima a fer canvis de manera controlada. Podeu etiquetar versions dels vostres "scripts financers" o revisar diferències quan depureu un problema. Alguns usuaris fins i tot fan un seguiment dels seus registres financers a Git per veure els canvis al llarg del temps. Només aneu amb compte de ignorar les dades sensibles (com ara fitxers d'estat de compte crus o claus API) al vostre repositori.

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

• Manteniment de complements de Fava: Si escriviu una extensió de Fava, manteniu-la senzilla. Fava pot canviar, per tant, les extensions més petites amb funcionalitat específica són més fàcils d'actualitzar. Eviteu duplicar massa lògica: utilitzeu el motor de consultes de Beancount o les funcions auxiliars existents sempre que sigui possible, en lloc de codificar càlculs que puguin ser sensibles als canvis del llibre major.

• Seguretat: Com que els vostres scripts poden gestionar dades sensibles i connectar-se a serveis externs, tracteu-los amb cura. No exposeu claus API i considereu executar la vostra automatització en una màquina segura. Si feu servir una solució allotjada o al núvol (com ara programar GitHub Actions o un servidor per executar Fava), assegureu-vos que les vostres dades del llibre major estiguin xifrades en repòs i que us sentiu còmodes amb les implicacions de privacitat.

Seguint aquestes pràctiques, us assegureu que el vostre flux de treball continuï sent fiable fins i tot a mesura que evolucionin les vostres finances (i les mateixes eines). Voleu scripts que pugueu reutilitzar any rere any, amb ajustos mínims.

Conclusió​

Beancount i Fava proporcionen una plataforma potent i flexible per a usuaris amb coneixements tècnics per personalitzar completament el seu seguiment de finances personals. Escrivint scripts en Python, podeu automatitzar tasques tedioses com conciliar estats de compte, produir informes rics adaptats a les vostres necessitats i estar al dia de les vostres finances amb alertes oportunes. Hem cobert una gamma d'exemples des de bàsics fins a avançats, començant amb consultes simples i imports CSV, i passant a complements complets de Fava i integracions amb API externes. A mesura que implementeu aquests, comenceu senzill i aneu construint gradualment. Fins i tot uns quants scripts d'automatització petits poden estalviar hores de feina i millorar molt la precisió. I recordeu, com que tot és text pla i Python, teniu el control total: el vostre sistema financer creix amb vosaltres, adaptant-se a les vostres necessitats específiques. Bona programació!

Fonts: Les tècniques anteriors s'han extret de la documentació de Beancount i de les experiències de la comunitat. Per aprofundir, vegeu els documents oficials de Beancount, guies i blocs de la comunitat, i el repositori Awesome Beancount per a enllaços a complements i eines útils.