Migrating from QuickBooks to Beancount: A Step-by-Step Guide

Fase 1: Gegevens Exporteren uit QuickBooks

Het migreren van vijf jaar aan gegevens begint met het exporteren van alle QuickBooks-records in een bruikbaar formaat. QuickBooks Desktop en QuickBooks Online hebben verschillende exportopties:

1.1 QuickBooks Desktop – Exportopties

IIF (Intuit Interchange Format): QuickBooks Desktop kan lijsten (zoals het rekeningschema, klanten, leveranciers) exporteren naar .IIF-tekstbestanden. Ga in QuickBooks Desktop naar File → Utilities → Export → Lists to IIF, en selecteer vervolgens de lijsten die u nodig heeft (bijv. Rekeningschema, Klanten, Leveranciers). Dit levert een tekstbestand op dat rekeningnamen, -types en lijstgegevens bevat. IIF is een eigen, maar platte-tekstformaat dat relatief eenvoudig te parsen is. Gebruik dit om uw Rekeningschema en contactlijsten vast te leggen ter referentie in Beancount.

Grootboek/Journaal via CSV: Voor transactiegegevens biedt QuickBooks Desktop geen volledige export met één klik, maar u kunt rapporten gebruiken. De aanbevolen methode is om het Algemeen Journaal (alle transacties) over de gewenste datumperiode te exporteren. Open in QuickBooks Desktop Reports → Accountant & Taxes → Journal, stel de datums in van de vroegste transactie tot vandaag, en klik op Export → Excel. Sla het resultaat op als CSV na het verwijderen van eventuele rapportkop- en voetteksten en lege kolommen. Zorg ervoor dat de numerieke gegevens schoon zijn: inclusief centen (bijv. 3.00 niet 3), geen extra aanhalingstekens en geen valutasymbolen of dubbele mintekens in de CSV. De CSV moet kolommen hebben zoals Date, Trans #, Name, Account, Memo, Debit, Credit, Balance (of een enkele kolom Amount, afhankelijk van het rapportformaat).

Tip: QuickBooks Desktop 2015+ kan ook transacties exporteren via het Find-dialoogvenster. Gebruik Edit → Find → Advanced, stel het datumbereik in op vijf jaar en exporteer de resultaten naar CSV. Waarschuwing: Sommige versies beperken de export tot 32.768 regels. Als u zeer grote datasets heeft, exporteer dan jaar na jaar (of in kleinere stukken) om afkapping te voorkomen, en voeg ze later samen. Zorg ervoor dat de datumbereiken niet overlappen om duplicaten te voorkomen.

Andere Formaten (QBO/QFX/QIF): QuickBooks Desktop kan banktransacties importeren via .QBO (Web Connect) of .QFX/.OFX-bestanden, maar voor het exporteren vanuit QuickBooks zijn dit geen gebruikelijke opties. Als uw doel is om alleen banktransacties te extraheren, heeft u deze mogelijk al in QBO/OFX van uw bank. Voor een volledige grootboekexport kunt u zich echter beter houden aan IIF en CSV. QuickBooks Desktop kan niet rechtstreeks naar QIF (Quicken Interchange Format) exporteren zonder tools van derden. Als u toch een manier vindt om QIF te verkrijgen, merk dan op dat sommige oudere grootboektools (Ledger 2.x) QIF konden lezen, maar het is beter om met CSV te werken in onze pijplijn.

1.2 QuickBooks Online – Exportopties

Ingebouwde Excel/CSV Export: QuickBooks Online (QBO) biedt een Export Data-tool. Ga naar Settings ⚙ → Tools → Export Data. Gebruik in het exportdialoogvenster het tabblad Reports om gegevens te selecteren (bijv. General Ledger of Transaction List) en het tabblad Lists voor lijsten (rekeningschema, etc.), kies All dates, en exporteer naar Excel. QuickBooks Online zal een ZIP-bestand downloaden met meerdere Excel-bestanden voor de geselecteerde rapporten en lijsten (bijvoorbeeld Winst & Verlies, Balans, Grootboek, Klanten, Leveranciers, Rekeningschema, etc.). U kunt deze Excel-bestanden vervolgens converteren naar CSV voor verwerking.

Transaction Detail Report: Als de standaardexport van QBO geen enkel Grootboek-bestand bevat, kunt u handmatig een gedetailleerd rapport genereren:

1. Navigeer naar Reports en zoek Transaction Detail by Account (of General Ledger in sommige QBO-versies).
2. Stel Report period in op het volledige bereik van vijf jaar.
3. Onder Rapportopties, stel Group by = None in (om individuele transacties zonder subtotalen te tonen).
4. Pas de kolommen aan om ten minste op te nemen: Date, Transaction Type, Number, Name (Payee/Customer), Memo/Description, Account, Debit, Credit (of een enkele Amount-kolom), en Balance. Neem ook eventuele klassen of locaties op als u die gebruikt.
5. Genereer het rapport en Export to Excel.

Dit levert een gedetailleerd grootboek op van alle transacties. Sla het op als CSV. Elke regel vertegenwoordigt één splitsing (boeking) van een transactie. U zult later de regels per transactie moeten groeperen voor de conversie.

Rekeningschema en Andere Lijsten: QuickBooks Online kan het rekeningschema exporteren via Accounting → Chart of Accounts → Batch Actions → Export to Excel. Doe dit om de rekeningnamen en -types te verkrijgen. Exporteer op dezelfde manier Klanten, Leveranciers, etc., als u de namen wilt overnemen voor metadata.

QuickBooks Online API (Optioneel): Voor een programmatische aanpak biedt Intuit een REST API voor QBO-gegevens. Gevorderde gebruikers kunnen een QuickBooks Online-app maken (vereist een ontwikkelaarsaccount) en de API gebruiken om gegevens in JSON op te halen. U kunt bijvoorbeeld de Account-endpoint opvragen voor het rekeningschema en de JournalEntry- of GeneralLedger-rapportendpoints voor transacties. Er zijn Python SDK's zoals python-quickbooks die de API wrappen. Het gebruik van de API omvat echter OAuth-authenticatie en is overdreven voor een eenmalige migratie, tenzij u de voorkeur geeft aan automatisering. In de meeste gevallen is de handmatige export naar CSV/Excel eenvoudiger en minder foutgevoelig.

---

Fase 2: Gegevens Transformeren en Opschonen

Zodra u de QuickBooks-gegevens in CSV (en/of IIF) hebt, is de volgende stap het omzetten naar Beancount's platte-tekst grootboekformaat. Dit omvat het parsen van de exports, het mappen van QuickBooks-rekeningen naar een Beancount-rekeningschema en het formatteren van transacties in Beancount-syntaxis.

2.1 QuickBooks Exports Parsen met Python

Het gebruik van Python zorgt voor nauwkeurigheid en reproduceerbaarheid van de transformatie. We zullen scripts schetsen voor twee belangrijke taken: het importeren van het rekeningschema en het converteren van transacties.

Rekeningen Importeren en Mappen: Het is cruciaal om uw rekeningen in Beancount op te zetten voordat u transacties toevoegt. QuickBooks-rekeningen hebben types (Bank, Accounts Receivable, Expense, etc.) die we zullen mappen naar de hiërarchie van Beancount (Assets, Liabilities, Income, Expenses, etc.). We kunnen bijvoorbeeld een mapping gebruiken zoals:

# QuickBooks-rekeningtype naar Beancount-hoofdcategorie
AccountTypeMap = {
    'BANK': 'Assets',
    'CCARD': 'Liabilities',
    'AR': 'Assets',       # Accounts Receivable (Debiteuren) als activa
    'AP': 'Liabilities',  # Accounts Payable (Crediteuren) als passiva
    'FIXASSET': 'Assets',
    'OASSET': 'Assets',   # Other Asset (Overige activa)
    'OCASSET': 'Assets',  # Other Current Asset (Overige vlottende activa)
    'LTLIAB': 'Liabilities', # Long Term Liability (Langlopende verplichting)
    'OCLIAB': 'Liabilities', # Other Current Liability (Overige kortlopende verplichting)
    'EQUITY': 'Equity',
    'INC': 'Income',
    'EXP': 'Expenses',
    'EXINC': 'Income',    # Other Income (Overige inkomsten)
    'EXEXP': 'Expenses',  # Other Expense (Overige uitgaven)
}

Met behulp van de QuickBooks Desktop IIF-export of de CSV met de rekeningenlijst van QBO, halen we de naam en het type van elke rekening op. Dan:

• Beancount-rekeningnamen aanmaken: QuickBooks gebruikt soms dubbele punten (:) in rekeningnamen om subrekeningen aan te duiden (bijv. “Current Assets:Checking”). Beancount gebruikt dezelfde dubbele-puntnotatie voor hiërarchie. U kunt de naam vaak direct hergebruiken. Als de QuickBooks-rekeningnamen niet met een categorie beginnen, voeg dan de gemapte categorie toe. Bijvoorbeeld, een QuickBooks-rekening van het type BANK genaamd "Checking" wordt Assets:Checking in Beancount. Een EXP (expense)-rekening "Meals" wordt Expenses:Meals, enz.

• Zorg voor geldige naamgeving: Verwijder of vervang alle tekens die Beancount kunnen verwarren. QuickBooks staat tekens zoals & of / in namen toe. Het is verstandig om speciale tekens te verwijderen of te vervangen (bijv. & vervangen door and, schuine strepen of spaties verwijderen). Zorg er ook voor dat alle rekeningnamen uniek zijn na transformatie – QuickBooks staat mogelijk dezelfde subrekeningnaam onder verschillende ouders toe, wat prima is, maar in Beancount moet de volledige naam (met ouders) uniek zijn. Hernoem indien nodig of voeg een kwalificator toe om ze te onderscheiden.

• Rekeningopeningen uitvoeren: In Beancount moet elke gebruikte rekening worden geopend met een open-directive. U kunt een datum kiezen vóór uw eerste transactie (bijv. als u gegevens van 2019–2023 migreert, gebruik dan 2018-12-31 of een nog eerdere datum voor alle openingen). Het script schrijft dan regels zoals: 2018-12-31 open Assets:Checking USD 2018-12-31 open Expenses:Meals USD voor elke rekening (ervan uitgaande dat USD de hoofdvaluta is). Gebruik de juiste valuta voor elke rekening (zie notities over meerdere valuta's hieronder).

Transactieconversie: De belangrijkste uitdaging is het converteren van de QuickBooks-transactie-export (CSV) naar Beancount-boekingen. Elke QuickBooks-transactie (factuur, rekening, cheque, journaalpost, etc.) kan meerdere splitsingen (regels) hebben die moeten worden samengevoegd tot één Beancount-transactie.

We gebruiken de CSV-lezer van Python om door de geëxporteerde regels te itereren en splitsingen te verzamelen:

import csv
from collections import defaultdict

# Lees alle regels uit de QuickBooks Journaal CSV
rows = []
with open('quickbooks_geexporteerd_journaal.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    for line in reader:
        rows.append(line)

# Groepeer regels per transactie (ervan uitgaande dat 'Trans #' transacties identificeert)
transactions = defaultdict(list)
for line in rows:
    trans_id = line.get('Trans #') or line.get('Transaction ID') or line.get('Num')
    transactions[trans_id].append(line)

Nu is transactions een dictionary waarbij elke sleutel een transactie-ID/nummer is en de waarde de lijst met splitsingen voor die transactie is. Vervolgens converteren we elke groep naar Beancount:

def format_date(qb_date):
    # QuickBooks-datums kunnen eruitzien als "12/31/2019"
    m, d, y = qb_date.split('/')
    return f"{y}-{int(m):02d}-{int(d):02d}"

output_lines = []
for trans_id, splits in transactions.items():
    # Sorteer splitsingen op regelvolgorde indien nodig (ze komen meestal in de juiste volgorde)
    splits = sorted(splits, key=lambda x: x.get('Line') or 0)
    first = splits[0]
    date = format_date(first['Date'])
    payee = first.get('Name', "").strip()
    memo = first.get('Memo', "").strip()
    # Transactiekop
    output_lines.append(f'{date} * "{payee}" "{memo}"')
    if first.get('Num'):  # voeg referentienummer toe indien beschikbaar
        output_lines.append(f'  number: "{first["Num"]}"')
    # Loop door elke splitsing/boeking
    for split in splits:
        acct_name = split['Account'].strip()
        # Map QuickBooks-rekeningnaam naar Beancount-rekening (met eerdere mapping)
        beancount_acct = account_map.get(acct_name, acct_name)
        # Bepaal bedrag met teken:
        amount = split.get('Amount') or ""
        debit = split.get('Debit') or ""
        credit = split.get('Credit') or ""
        if amount:
            # Sommige exports hebben een enkele Amount-kolom (negatief voor credits)
            amt_str = amount
        else:
            # Indien aparte Debit/Credit-kolommen
            amt_str = debit if debit else f"-{credit}"
        # Verwijder eventuele komma's in getallen voor de zekerheid
        amt_str = amt_str.replace(",", "")
        # Voeg valuta toe
        currency = split.get('Currency') or "USD"
        amt_str = f"{amt_str} {currency}"
        # Memo/omschrijving voor de splitsing
        line_memo = split.get('Memo', "").strip()
        comment = f" ; {line_memo}" if line_memo else ""
        output_lines.append(f"  {beancount_acct:<40} {amt_str}{comment}")
    # Einde van transactie – lege regel
    output_lines.append("")

Deze scriptlogica doet het volgende:

• Formatteert de datum naar JJJJ-MM-DD voor Beancount.

• Gebruikt de begunstigde (Name) en memo voor de transactieomschrijving. Bijvoorbeeld: 2020-05-01 * "ACME Corp" "Factuurbetaling" (Als er geen begunstigde is, kunt u het QuickBooks-transactietype gebruiken of de begunstigde leeg laten).

• Voegt number-metadata toe als er een referentienummer is (cheque #, factuur #, etc.).

• Itereert door elke splitsingsregel:

  • Mapt de QuickBooks-rekeningnaam naar de Beancount-rekening met behulp van een dictionary account_map (gevuld vanuit de stap van het rekeningschema).
  • Bepaalt het bedrag. Afhankelijk van uw export, heeft u mogelijk een enkele Amount-kolom (met positieve/negatieve waarden) of afzonderlijke Debit- en Credit-kolommen. De bovenstaande code behandelt beide gevallen. Het zorgt ervoor dat credits worden weergegeven als negatieve bedragen voor Beancount (aangezien in Beancount een enkel getal met een teken per boeking wordt gebruikt).
  • Voegt de valuta toe (uitgaande van USD, tenzij er een andere valutakolom aanwezig is).
  • Schrijft de Beancount-boekingsregel met de rekening, het bedrag en een opmerking met de regelmemo. Bijvoorbeeld: Assets:Checking 500.00 USD ; Storting Income:Sales -500.00 USD ; Storting Dit weerspiegelt een storting van $500 (van Income naar Checking).

• Na het opsommen van alle splitsingen, scheidt een lege regel de transactie.

Omgaan met meerdere valuta's: Als uw QuickBooks-gegevens meerdere valuta's bevatten, neem dan de valutacode op bij elke boeking (zoals hierboven getoond). Zorg ervoor dat rekeningen in vreemde valuta's worden geopend met die valuta. Als u bijvoorbeeld een bankrekening in EUR heeft, zou u open Assets:Bank:Checking EUR uitvoeren en de transacties op die rekening gebruiken EUR. Beancount ondersteunt grootboeken met meerdere valuta's en houdt impliciete conversies bij, maar u moet mogelijk prijsboekingen voor wisselkoersen toevoegen als u conversie naar een basisvaluta in rapporten wilt. Het wordt ook aanbevolen om uw belangrijkste operationele valuta bovenaan het Beancount-bestand te declareren (bijv. option "operating_currency" "USD").

De conversie uitvoeren: Sla het Python-script op (bijvoorbeeld als qb_naar_beancount.py) en voer het uit op uw geëxporteerde bestanden. Het zou een .beancount-bestand moeten produceren dat alle rekeningen en transacties bevat.

2.2 Omgaan met Randgevallen en Gegevensopschoning

Houd tijdens de transformatie rekening met deze veelvoorkomende valkuilen en hoe u ze kunt aanpakken:

• Mismatch in Rekeningnamen: QuickBooks kan rekeningnamen hebben die botsen met de hiërarchische namen van Beancount. QuickBooks kan bijvoorbeeld twee verschillende bovenliggende rekeningen hebben met elk een subrekening genaamd "Insurance". In Beancount moet Expenses:Insurance uniek zijn. Los dit op door er een te hernoemen (bijv. "Insurance-Vehicle" vs "Insurance-Health") vóór de export of map ze naar unieke Beancount-rekeningen in uw script. Consistente naamgevingsconventies (geen speciale tekens en gebruik van hiërarchie) zullen hoofdpijn besparen. Gebruik de remapping-bestandsbenadering indien nodig: onderhoud een CSV of dictionary van oude naam → nieuwe Beancount-naam en pas deze toe tijdens de conversie (ons voorbeeldcode gebruikt een account_map en kan overschrijvingen uit een bestand laden).

• Datums en Formaten: Zorg ervoor dat alle datums consistent zijn geformatteerd. Het bovenstaande script normaliseert M/D/J naar ISO-formaat. Pas ook op voor problemen met fiscaal jaar vs kalenderjaar als uw periode van vijf jaar een jaareinde overschrijdt. Beancount geeft niet om grenzen van fiscale jaren, maar u wilt misschien later bestanden per jaar splitsen voor het gemak.

• Numerieke Precisie: QuickBooks behandelt valuta met centen, dus werken in centen is meestal prima. Alle bedragen moeten idealiter twee decimalen hebben in de CSV. Als bedragen zijn omgezet in gehele getallen (geen decimaal) of komma's/haakjes hebben (voor negatieven), schoon die dan op in het script (verwijder komma's, converteer (100.00) naar -100.00, etc.). De CSV-export, indien correct uitgevoerd (volgens de instructies), zou die opmaakproblemen al moeten vermijden.

• Negatieve Bedragen en Tekens: QuickBooks-rapporten tonen negatieven soms als -100.00 of als (100.00) of zelfs --100.00 in bepaalde Excel-exports. De opschoningsstap moet hiermee omgaan. Zorg ervoor dat de debet- en creditbedragen van elke transactie op nul uitkomen. Beancount zal dit afdwingen (indien niet in evenwicht, zal het een fout geven bij het importeren).

• Dubbele Transacties: Als u transacties in batches moest exporteren (bijv. jaar na jaar of rekening per rekening), wees dan voorzichtig met het samenvoegen zonder overlap. Controleer of de eerste transactie van een jaar niet ook de laatste is van de vorige batch, enz. Het is gemakkelijk om per ongeluk een paar transacties op de grenzen te dupliceren. Als u duplicaten vermoedt, kunt u de uiteindelijke Beancount-boekingen op datum sorteren en zoeken naar identieke boekingen, of Beancount's unieke transactietags gebruiken om ze te vangen. Een strategie is om QuickBooks-transactienummers op te nemen als metadata (bijv. gebruik de Trans # of factuurnummer als een txn-tag of quickbooks_id-metadata) en dan te zorgen dat er geen duplicaten van die ID's bestaan.

• Ongebalanceerde Splitsingen / Tussenrekeningen: QuickBooks kan vreemde gevallen hebben zoals een transactie met een onbalans die QuickBooks automatisch heeft aangepast naar een "Opening Balance Equity" of "Retained Earnings". Bij het instellen van de beginbalansen van rekeningen boekt QuickBooks bijvoorbeeld vaak verschillen naar een Eigen Vermogen-rekening. Deze zullen verschijnen in de geëxporteerde transacties. Beancount vereist expliciet evenwicht. Mogelijk moet u een Eigen Vermogen-rekening voor beginbalansen introduceren (meestal Equity:Opening-Balances) om QuickBooks te spiegelen. Het is een goede gewoonte om een beginbalansboeking te hebben op de eerste dag van uw grootboek die de startsaldi van alle rekeningen vaststelt (zie Fase 5).

• Randgevallen met Meerdere Valuta's: Als u meerdere valuta's gebruikt, kan de export van QuickBooks alle bedragen in de thuisvaluta of in hun oorspronkelijke valuta vermelden. Idealiter krijgt u de gegevens in de oorspronkelijke valuta voor elke rekening (de rapporten van QuickBooks Online doen dit meestal). In Beancount heeft elke boeking een valuta. Als QuickBooks wisselkoersen of een thuisvaluta-conversie heeft geleverd, kunt u die negeren en vertrouwen op de prijsboekingen van Beancount. Als QuickBooks geen wisselkoersen heeft geëxporteerd, wilt u misschien handmatig prijsrecords toevoegen (bijv. met de price-directive van Beancount) voor belangrijke datums om de waardering te evenaren. Voor de basisintegriteit van het grootboek is het echter voldoende dat transacties in hun oorspronkelijke valuta's in evenwicht zijn – ongerealiseerde winsten/verliezen hoeven niet expliciet te worden geregistreerd, tenzij u dezelfde rapporten wilt.

• Debiteuren / Crediteuren: QuickBooks houdt factuur- en rekeningdetails bij (vervaldata, betaalstatus, etc.) die niet volledig zullen worden overgedragen in een plat grootboek. U krijgt de A/R- en A/P-transacties (facturen die A/R verhogen, betalingen die A/R verlagen, etc.), maar niet de factuurdocumenten of klantensaldi per factuur. Als gevolg hiervan moet u na de migratie controleren of uw A/R- en A/P-rekeningsaldi in Beancount gelijk zijn aan de openstaande saldi van klanten/leveranciers in QuickBooks. Als u facturen moet volgen, kunt u de metadata van Beancount gebruiken (bijv. een invoice-tag of link opnemen). De QuickBooks-factuurnummers zouden via de Num- of Memo-velden moeten zijn meegekomen – ons script bewaart de Num als number: "..." in de transactiemetadata.

• Inactieve of Gesloten Rekeningen: De IIF-export kan inactieve rekeningen bevatten (als u ervoor koos deze op te nemen). Het is prima om ze te importeren (ze zullen gewoon geen transacties en een nulsaldo hebben als ze echt inactief zijn). U kunt ze in Beancount als gesloten markeren na de laatste transactiedatum met een close-directive. Dit houdt uw grootboek opgeruimd. Bijvoorbeeld: 2023-12-31 close Expenses:OldAccount ; gesloten na migratie Dit is optioneel en voornamelijk voor de netheid.

Door de gegevens zorgvuldig op te schonen en te mappen zoals hierboven beschreven, krijgt u een Beancount-grootboekbestand dat structureel uw QuickBooks-gegevens weerspiegelt. De volgende stap is om te verifiëren dat het ook numeriek QuickBooks weerspiegelt.

---

Fase 3: Gegevensvalidatie en Afstemming

Validatie is een kritieke fase in een migratie van boekhoudgegevens. We moeten ervoor zorgen dat het Beancount-grootboek tot op de cent nauwkeurig overeenkomt met de QuickBooks-boekhouding. Er kunnen verschillende strategieën en hulpmiddelen worden gebruikt:

3.1 Afstemming van de Proefbalans

Een proefbalans-rapport toont de eindsaldi van alle rekeningen (met debet- en creditbedragen of positief/negatief aangegeven) en zou op nul moeten uitkomen. Het draaien van een proefbalans in beide systemen voor dezelfde datum is de snelste manier om de algehele nauwkeurigheid te bevestigen.

• In QuickBooks: Genereer een Trial Balance-rapport voor de laatste dag van het laatste jaar (bijv. 31 december 2023). Dit rapport toont het saldo van elke rekening. Exporteer het of noteer de belangrijkste cijfers.

• In Beancount: Gebruik de rapportage van Beancount om een proefbalans te genereren. Een eenvoudige methode is via de opdrachtregel:

  bean-report gemigreerd.beancount balances

  Het balances-rapport is een proefbalans die alle rekeningen en hun saldi vermeldt. U kunt het bestand ook openen in Fava (de web-UI van Beancount) en kijken naar de sectie Balances of Balance Sheet. Elk rekeningsaldo in Beancount moet overeenkomen met de proefbalans van QuickBooks. Als QuickBooks bijvoorbeeld Accounts Receivable = $5,000 toont, dan moet de rekening Assets:Accounts Receivable van Beancount een totaal van $5,000 (debet) hebben. Als Sales Income = $200,000, dan zou de Income:Sales in Beancount $200,000 (credit) moeten tonen (wat mogelijk als -200,000 wordt weergegeven als u een proefbalans gebruikt die credits als negatieven presenteert).

Als er discrepanties zijn, spoor ze dan op:

• Controleer of een hele rekening ontbreekt of extra is (zijn we een rekening vergeten of hebben we er een opgenomen die al voor de migratieperiode was gesloten?).
• Als een saldo niet klopt, ga dan dieper: QuickBooks kan een Account QuickReport of grootboekdetail voor die rekening genereren, en u kunt dit vergelijken met het register van Beancount voor die rekening (bean-report gemigreerd.beancount register -a RekeningNaam). Soms komen verschillen door een ontbrekende of dubbele transactie.

Verifieer ook dat de som van alle rekeningen nul is in de proefbalans van Beancount (het drukt een totaal af dat nul of zeer dicht bij nul zou moeten zijn). Beancount dwingt dubbel boekhouden af, dus als u een onbalans heeft die niet nul is, betekent dit dat activa min passiva-eigen vermogen niet op nul uitkwam, wat duidt op een probleem (wat QuickBooks normaal gesproken ook niet zou toestaan, maar kan gebeuren als er gegevens zijn weggelaten).

3.2 Vergelijkingen van Rekeningensaldi

Naast de proefbalans kunt u specifieke financiële overzichten vergelijken:

• Balans: Genereer een QuickBooks Balans voor de einddatum en een Beancount-balans (bean-report gemigreerd.beancount balsheet). Dit is vergelijkbaar met de proefbalans, maar georganiseerd per Activa, Passiva, Eigen Vermogen. De cijfers moeten per categorie overeenkomen. Voor een meer gedetailleerde controle, vergelijk de totalen van de belangrijkste rekeningen: kas, debiteuren, vaste activa, crediteuren, eigen vermogen, etc.

• Winst- en Verliesrekening (Resultatenrekening): Genereer een W&V voor de periode van vijf jaar (of jaar na jaar) in QuickBooks en in Beancount (bean-report gemigreerd.beancount income voor een resultatenrekening over de volledige periode). Het netto-inkomen van Beancount moet gelijk zijn aan dat van QuickBooks voor elke periode. Als u alle vijf jaar hebt gemigreerd, moet het cumulatieve netto-inkomen overeenkomen. U kunt ook individuele omzet- en kostentotalen vergelijken om ervoor te zorgen dat er geen categorie is gemist of verdubbeld.

• Steekproef van Willekeurige Transacties: Kies een paar willekeurige transacties (vooral uit elk jaar en van elke belangrijke rekening) en controleer of ze correct zijn gemigreerd. Zoek bijvoorbeeld een factuur van 3 jaar geleden in QuickBooks en zoek vervolgens naar het bedrag of de memo ervan in het Beancount-bestand (aangezien alle transacties tekst zijn, kunt u het .beancount-bestand in een teksteditor openen of zoekhulpmiddelen gebruiken). Controleer of de datum, bedragen en rekeningen overeenkomen. Dit helpt bij het opsporen van problemen met datumnotatie of verkeerd gemapte rekeningen.

3.3 Geautomatiseerde Integriteitscontroles

Maak gebruik van de eigen validatietools van Beancount:

• bean-check: Voer bean-check gemigreerd.beancount uit. Dit zal het bestand parsen en eventuele fouten in syntaxis of balancering rapporteren. Als het script iets heeft gemist, zoals een niet-geopende rekening of een niet-gebalanceerde transactie, zal bean-check dit signaleren. Een schone doorgang (geen uitvoer) betekent dat het bestand op zijn minst intern consistent is.

• Saldo-asserties: U kunt expliciete saldo-asserties toevoegen in het grootboek voor belangrijke rekeningen als extra controle. Als u bijvoorbeeld het saldo van de bankrekening op een bepaalde datum weet, voeg dan een regel toe: 2023-12-31 balance Assets:Bank:Checking 10000.00 USD Dan zal bean-check ervoor zorgen dat in het grootboek, op die datum, het saldo inderdaad $10.000 is. Dit is optioneel, maar kan nuttig zijn voor zeer belangrijke rekeningen. U kunt eindsaldi uit QuickBooks halen (bijv. aan het einde van elk jaar) en deze in het Beancount-bestand affirmeren. Als een assertie mislukt, zal Beancount een verschil rapporteren.

• Proefbalans doorrollen: Als u dat liever heeft, kunt u een periode-voor-periode controle uitvoeren. Vergelijk voor elk jaar de nettoverandering. Bijvoorbeeld, netto-inkomen in QuickBooks 2020 versus Beancount 2020, etc., om ervoor te zorgen dat elk jaar correct is afgesloten naar het eigen vermogen (QuickBooks rolt het netto-inkomen automatisch door naar Ingehouden Winsten elk nieuw jaar; in Beancount ziet u gewoon het cumulatieve eigen vermogen). Als u verschillen ziet, kan dit duiden op een probleem in de gegevens van een specifiek jaar.

• Transactietellingen en Duplicaten: Tel het aantal transacties in QuickBooks versus Beancount. QuickBooks toont niet gemakkelijk een directe telling, maar u kunt dit inschatten door regels in de CSV te tellen (elke transactiekop versus splitsingen). In Beancount is een snelle manier om het aantal keren txn of * " in het bestand te tellen. Ze moeten gelijk zijn aan of iets hoger zijn dan QuickBooks (als u beginbalanstransacties of aanpassingen heeft toegevoegd). Een significant verschil betekent dat er iets weggelaten of gedupliceerd kan zijn. Ons gebruik van unieke ID's in metadata kan helpen: als u duplicaten vermoedt, zoek dan in het Beancount-bestand naar hetzelfde chequenummer of factuurnummer dat twee keer voorkomt waar dat niet zou moeten.

• Afstemmingsstatus: We hebben een rec: "y" of "n" metadata opgenomen op basis van de afgestemde status van QuickBooks in ons script (als rec in het voorbeeld). Dit is geen standaard Beancount-functie (Beancount houdt afgestemd/in behandeling niet op dezelfde manier bij als Ledger), maar het kan nuttige metadata zijn. U kunt controleren of alle transacties die in QuickBooks zijn afgestemd, aanwezig zijn. Uiteindelijk kan het opnieuw afstemmen van bankrekeningen in Beancount (met uw afschriften) het laatste bewijs zijn dat er niets ontbreekt.

Door deze validaties uit te voeren, bouwt u vertrouwen op dat de migratie de gegevens heeft behouden. Neem de tijd voor deze fase – het is gemakkelijker om afwijkingen nu te corrigeren dan maanden later wanneer er mogelijk op de boeken wordt vertrouwd. Veelvoorkomende problemen als de validatie mislukt: een ontbrekend beginsaldo van een rekening, een transactie met een datum buiten het bereik, of een tekeomkering bij een boeking. Allemaal oplosbaar zodra ze zijn geïdentificeerd.

---

Fase 4: Vastleggen in het Beancount Grootboek

Na het opschonen en valideren is het tijd om de gegevens te formaliseren in uw Beancount-grootboekstructuur. "Vastleggen" betekent hier zowel het finaliseren van de grootboekbestanden als het mogelijk inchecken ervan in een versiebeheersysteem voor auditeerbaarheid.

4.1 Organiseren van Grootboekbestanden en Configuratie

Beslis hoe u de Beancount-grootboekbestanden structureert. Voor vijf jaar aan gegevens kunt u alles in één bestand bewaren of splitsen per jaar of categorie. Een veelvoorkomende, duidelijke structuur is:

• Hoofdgrootboekbestand: bijv. ledger.beancount – Dit is het startpunt dat andere bestanden kan include. Het kan globale opties bevatten en vervolgens jaarlijkse bestanden opnemen.
• Rekeningenbestand: Definieer het rekeningschema en de beginbalansen. Bijvoorbeeld, accounts.beancount met alle open-directieven (zoals gegenereerd door het script). U kunt hier ook commodities (valuta's) vermelden.
• Transactiebestanden: Eén per jaar, bijv. 2019.beancount, 2020.beancount, etc., met de transacties voor dat jaar. Dit houdt elk bestand beheersbaar van omvang en stelt u in staat om u op een jaar te concentreren indien nodig. U kunt ook splitsen op entiteit of rekening, maar splitsen op tijd is eenvoudig voor financiële gegevens.

Voorbeeld hoofd-bestand:

option "title" "Mijn Bedrijfsgrootboek"
option "operating_currency" "USD"

include "accounts.beancount"
include "2019.beancount"
include "2020.beancount"
...
include "2023.beancount"

Op deze manier worden alle gegevens geaggregeerd wanneer u rapporten genereert, maar behoudt u de orde.

Beancount vereist niet meerdere bestanden – u kunt één groot bestand hebben – maar de bovenstaande structuur verbetert de duidelijkheid en het versiebeheer. Volgens de best practices van Beancount is het goed om duidelijke sectiekoppen te gebruiken en gerelateerde boekingen logisch te groeperen.

4.2 Instellen van Beginbalansen en Eigen Vermogen

Als uw migratie niet vanaf een absoluut nulpunt begint, moet u omgaan met beginbalansen. Twee scenario's:

• Boeken beginnen vanaf nul: Als de periode van vijf jaar begint bij de oprichting van het bedrijf (bijv. u begon QuickBooks te gebruiken in jan 2019 met alle rekeningen op nul, behalve het initiële eigen vermogen), dan heeft u mogelijk geen aparte beginbalanstransactie nodig. De eerste transacties in 2019 (zoals de initiële financiering van een bankrekening) zullen op natuurlijke wijze de beginbalansen vaststellen. Zorg er alleen voor dat eventueel startkapitaal of eerdere ingehouden winsten worden verantwoord via eigen-vermogenstransacties.

• Boeken halverwege (gedeeltelijke geschiedenis): Als u eerder met QuickBooks begon en 2019 een middenpunt is, dan had elke rekening per 1 jan 2019 een overgedragen saldo. QuickBooks zou die als beginbalansen of ingehouden winsten hebben. In Beancount is het gebruikelijk om een Beginbalansen-boeking te maken op de dag vóór uw startdatum:

  • Gebruik een eigen-vermogenrekening genaamd Equity:Opening-Balances (of iets dergelijks) om de som van alle openingsbedragen te compenseren.
  • Voorbeeld: als op 2018-12-31, Kas $10.000 was en Debiteuren $5.000 en Crediteuren $3.000 (credit), zou u een transactie schrijven: 2018-12-31 * "Beginbalansen" Assets:Cash 10000.00 USD Assets:Accounts Receivable 5000.00 USD Liabilities:Accounts Payable -3000.00 USD Equity:Opening-Balances -12000.00 USD Dit laat Opening-Balances achter met de negatieve som (–$12k) die de boeking balanceert. Nu beginnen alle activa/passiva-rekeningen 2019 met de juiste saldi. Dit moet eventuele QuickBooks "Retained Earnings" of overgedragen saldi weerspiegelen.
  • Alternatief, gebruik de pad- en balance-directieven van Beancount: Voor elke rekening kunt u deze pad (aanvullen) vanuit Opening-Balances en het saldo affirmeren. Dit is een meer geautomatiseerde manier. Bijvoorbeeld: 2018-12-31 pad Assets:Cash Equity:Opening-Balances 2018-12-31 balance Assets:Cash 10000.00 USD Dit vertelt Beancount om de benodigde boeking in te voegen (naar Opening-Balances) zodat Kas gelijk is aan 10000 USD op die datum. Doe dit voor elke rekening. Het resultaat is vergelijkbaar, maar het schrijven van een expliciete transactie zoals in de eerste methode is ook eenvoudig.

• Ingehouden Winsten: QuickBooks exporteert niet expliciet een "Ingehouden Winsten"-transactie – het berekent deze gewoon. Na de migratie merkt u misschien dat Equity:Retained Earnings nul is als u deze niet heeft aangemaakt. In Beancount zijn ingehouden winsten gewoon de winst van voorgaande jaren. U kunt ervoor kiezen om een rekening Ingehouden Winsten aan te maken en de winsten van voorgaande jaren daarheen over te boeken op de eerste dag van elk nieuw jaar, of u kunt het eigen vermogen gewoon de som van alle inkomsten/uitgaven laten zijn (wat onder de sectie Eigen Vermogen in rapporten verschijnt). Voor de transparantie maken sommige gebruikers jaarlijks sluitingsboekingen. Dit is optioneel en voornamelijk voor presentatiedoeleinden. Aangezien we alle transacties hebben gemigreerd, zal de winst voor elk jaar op natuurlijke wijze worden opgeteld als u een rapport per jaar genereert.

• Vergelijkende Controles: Na het instellen van de beginbalansen, genereer een balans op de startdatum om ervoor te zorgen dat alles correct is (deze zou die beginbalansen versus het Opening Equity moeten tonen die op nul uitkomen).

4.3 Finaliseren en Versiebeheer

Nu de gegevens in Beancount-formaat zijn en gestructureerd, is het verstandig om de bestanden vast te leggen in een versiebeheerrepository (bijv. git). Elke wijziging in het grootboek kan worden gevolgd, en u heeft een audittrail van alle aanpassingen. Dit is een groot voordeel van platte-tekstboekhouding. In QuickBooks zijn wijzigingen bijvoorbeeld misschien niet gemakkelijk te vergelijken, maar in Beancount kunt u regel-voor-regel verschillen zien. Zoals sommige gebruikers opmerken, krijgt u met Beancount transparantie en de mogelijkheid om wijzigingen terug te draaien indien nodig – elke boeking kan worden gekoppeld aan een wijzigingsgeschiedenis.

Overweeg om de commit van deze initiële migratie te taggen als v1.0 of iets dergelijks, zodat u weet dat het de staat van de boeken vertegenwoordigt zoals geïmporteerd uit QuickBooks. In de toekomst zult u nieuwe transacties rechtstreeks in Beancount invoeren (of importeren uit bankfeeds, etc.), en kunt u normale softwareontwikkelingspraktijken gebruiken (maandelijks of dagelijks committen, branches gebruiken voor experimenten, etc.).

Fava of andere tools instellen: Fava is een webinterface voor Beancount die het gemakkelijk maakt om rapporten te bekijken. Voer na het committen fava ledger.beancount uit om door de financiële overzichten te bladeren en ze een laatste keer te vergelijken met uw QuickBooks-rapporten. U kunt kleine verschillen gemakkelijker opmerken in een UI (bijvoorbeeld, een rekening die nul zou moeten zijn maar een klein saldo toont, duidt op een ontbrekende sluitingsboeking of een verdwaalde transactie).

Naamgevingsconventies en consistentie: U heeft nu volledige controle, dus zorg voor consistentie:

• Alle rekeningen moeten duidelijke namen hebben, beginnend met gecapitaliseerde categorienamen (Assets, Liabilities, etc.). Als er een vreemd uitziet (bijv. Assets:assets:SomeAccount door een hoofdletterverschil uit QuickBooks), hernoem deze dan in het rekeningenbestand en werk de transacties bij (een snelle zoek/vervang-actie op het bestand kan dit doen, of gebruik Beancount's bean-format of de multi-cursor van een editor).
• Commodity-symbolen (valutacodes) moeten consistent zijn. Gebruik voor USD overal USD (niet $ of US$). Gebruik voor andere standaardcodes (EUR, GBP, etc.). Deze consistentie is belangrijk voor de prijsopzoekingen en rapporten van Beancount.
• Verwijder eventuele tijdelijke of dummy-rekeningen die mogelijk zijn aangemaakt (als u bijvoorbeeld Expenses:Miscellaneous gebruikte voor onbekende rekeningen in het script als een vangnet, probeer die dan te elimineren door alle rekeningen correct te mappen).

QuickBooks afsluiten: Op dit punt zou u parallelle boeken in Beancount moeten hebben die overeenkomen met QuickBooks. Sommigen kiezen ervoor om beide systemen een korte periode parallel te laten draaien om er zeker van te zijn dat er niets is gemist. Maar als de validatie solide is, kunt u de QuickBooks-boeken "afsluiten":

• Als dit een bedrijfsomgeving is, overweeg dan om alle QuickBooks-brondocumenten (facturen, rekeningen, bonnen) te exporteren voor uw administratie, aangezien die niet in Beancount zullen bestaan tenzij u ze handmatig bijvoegt.
• Bewaar een back-up van de QuickBooks-gegevens (zowel het bedrijfsbestand als de exportbestanden).
• Houd voortaan het Beancount-grootboek aan als het primaire registratiesysteem.

Door de gegevens vast te leggen in het Beancount-grootboek, heeft u de migratiepijplijn voltooid. De laatste stap is het uitvoeren van een audit en het aantonen van de consistentie van de financiële overzichten, om uzelf (en eventuele belanghebbenden of auditors) ervan te overtuigen dat de migratie succesvol was.

---

Fase 5: Audit na Migratie en Voorbeelden

Om het succes van de migratie te illustreren, bereidt u een voor-en-na vergelijking van financiële overzichten en mogelijk een diff van transacties voor. Dit levert bewijs dat de boeken consistent zijn.

5.1 Verifiëren van Financiële Overzichten

Produceer belangrijke financiële rapporten van zowel QuickBooks als Beancount voor dezelfde data en vergelijk ze:

• Balans per 31 dec 2023: Vergelijk de totalen van Activa, Passiva en Eigen Vermogen regel voor regel. Ze moeten overeenkomen. Als QuickBooks bijvoorbeeld Totaal Activa = $150.000 en Totaal Passiva + Eigen Vermogen = $150.000 toonde, moet de Beancount-balans dezelfde totalen tonen. Als u de rekeningen iets anders heeft gestructureerd (bijvoorbeeld enkele subrekeningen samengevoegd), pas daar dan op aan bij de vergelijking of ga een niveau dieper om ervoor te zorgen dat de sommen gelijk zijn.

• Winst & Verlies 2019–2023: Zorg ervoor dat de totale Inkomsten, totale Uitgaven en Nettowinst voor elk jaar (of de hele periode) identiek zijn. Kleine verschillen kunnen ontstaan als QuickBooks afrondingen deed op rapporten, maar transacties dragen meestal centen exact over, dus de nettowinst zou exact moeten zijn. Als de winst van een jaar verschilt, onderzoek dan de gegevens van dat jaar – vaak een indicator van een ontbrekende of dubbele boeking in die periode.

• Verschillen in Proefbalans: Maak indien mogelijk een spreadsheet waarin u elke rekening en het saldo van QuickBooks versus Beancount opsomt. Aangezien we verwachten dat ze overeenkomen, zou dit een kolom met allemaal nullen moeten zijn. Dit is in wezen de kruiscontrole van de proefbalans die we hebben besproken, maar het uitschrijven ervan helpt bij de documentatie.

5.2 Voorbeeldvergelijking (Voor vs Na)

Hieronder volgt een voorbeeldfragment dat de gegevensconsistentie aantoont. Stel dat onze QuickBooks-proefbalans voor 31 dec 2023 was:

Rekening	QuickBooks Saldo (31 dec 2023)
Activa
Assets:Bank:Checking	$12.500,00 (debet)
Assets:Accounts Receivable	$3.200,00 (debet)
Passiva
Liabilities:Credit Card	$-1.200,00 (credit)
Liabilities:Loans Payable	$-5.000,00 (credit)
Eigen Vermogen
Equity:Opening-Balances	$-7.500,00 (credit)
Equity:Retained Earnings	$-2.000,00 (credit)
Equity:Current Year Profit	$0,00

In Beancount, na het importeren en boeken van alle transacties tot 2023, geeft een bean-report balances (proefbalans) het volgende weer:

Rekening	Beancount Saldo (31 dec 2023)
Activa
Assets:Bank:Checking	12,500.00 USD (debet)
Assets:Accounts Receivable	3,200.00 USD (debet)
Passiva
Liabilities:Credit Card	-1,200.00 USD (credit)
Liabilities:Loans Payable	-5,000.00 USD (credit)
Eigen Vermogen
Equity:Opening-Balances	-7,500.00 USD (credit)
Equity:Retained Earnings	-2,000.00 USD (credit)
Equity:Winst (2019-2023)	0.00 USD

(Opmerking: Eigen Vermogen-secties kunnen anders gestructureerd zijn; de sleutel is dat de totalen overeenkomen. Hier speelt "Winst (2019-2023)" in Beancount de rol van de winst van het lopende jaar/ingehouden winsten gecombineerd, en toont nul omdat de winst is afgesloten naar Ingehouden Winsten.)

Zoals te zien is, komt elke rekening tot op de cent overeen. De som van de debetbedragen is gelijk aan de som van de creditbedragen aan beide kanten.

Bovendien, als we een Winst & Verlies voor 2023 genereren:

• QuickBooks: Inkomsten $50.000, Uitgaven $48.000, Nettowinst $2.000.
• Beancount: Inkomsten $50.000, Uitgaven $48.000, Nettowinst $2.000 (die vervolgens werd afgesloten naar Ingehouden Winsten of verschijnt onder Eigen Vermogen in de eindejaarsbalans).

U kunt indien nodig een diff van transacties maken, maar aangezien QuickBooks-gegevens niet in grootboekvorm zijn, is het effectiever om op rapporten te vertrouwen. Men zou zowel de QuickBooks CSV als de Beancount-transacties op datum kunnen sorteren en belangrijke velden vergelijken als een laatste controle (dit kan in Excel of met een script). Echter, aangezien we vertrouwen op onze eerdere validatie, is de controle van de financiële overzichten meestal voldoende.

5.3 Audittips

• Als een auditor of belanghebbende geruststelling nodig heeft, presenteer dan de voor-en-na financiële overzichten naast elkaar. De transparantie van Beancount kan audits zelfs vereenvoudigen omdat u elk getal van een overzicht snel kunt terugvoeren naar de bronboeking (vooral met de drill-down functionaliteit van Fava).
• Bewaar de QuickBooks-back-up en geëxporteerde CSV's als onderdeel van uw audittrail. Documenteer eventuele aanpassingen die tijdens de migratie zijn gemaakt (bijvoorbeeld "Rekening X hernoemd naar Y voor consistentie" of "Transactie Z opgesplitst in twee boekingen voor duidelijkheid" als u dergelijke wijzigingen heeft aangebracht).
• Implementeer in de toekomst regelmatige controles in Beancount. Bijvoorbeeld, maandelijkse afstemming van bankrekeningen en een assertie van hun eindsaldo helpt bij het opsporen van eventuele gegevensproblemen of fouten bij het invoeren. De migratie geeft een goede basis; discipline handhaven in het nieuwe systeem zal voortdurende nauwkeurigheid garanderen.

Vier tot slot de voltooiing van de migratie: u heeft met succes vijf jaar aan boekhoudgegevens overgezet van QuickBooks naar Beancount. De gegevens zijn nu in een lichtgewicht, versiebeheerd tekstformaat met volledige dubbel boekhouden-integriteit. U heeft de gegevens geëxporteerd, getransformeerd met Python-scripts, de integriteit gevalideerd via proefbalansen en rapporten, en vastgelegd in een goed georganiseerd Beancount-grootboek. Dit uitgebreide proces zorgt ervoor dat het Beancount-grootboek een nauwkeurige, getrouwe replica is van uw QuickBooks-boeken over de periode van vijf jaar, wat u voorbereidt op een gestroomlijnde boekhouding in de toekomst.