Playbook di Migrazione da QuickBooks a Beancount

Fase 1: Esportazione dei Dati da QuickBooks​

Migrare cinque anni di dati inizia con l'ottenimento di tutti i record di QuickBooks in un formato utilizzabile. QuickBooks Desktop e QuickBooks Online hanno diverse opzioni di esportazione:

1.1 QuickBooks Desktop – Opzioni di Esportazione​

IIF (Intuit Interchange Format): QuickBooks Desktop può esportare elenchi (come piano dei conti, clienti, fornitori) in file di testo .IIF. In QuickBooks Desktop, vai su File → Utility → Esporta → Elenchi in IIF, quindi seleziona gli elenchi necessari (es. Piano dei Conti, Clienti, Fornitori). Questo produce un file di testo che include nomi conti, tipi e dati degli elenchi. IIF è un formato proprietario ma in testo semplice, relativamente facile da analizzare. Usalo per catturare il tuo Piano dei Conti e gli elenchi di contatti come riferimento in Beancount.

Registro Generale/Giornale tramite CSV: Per i dati delle transazioni, QuickBooks Desktop non fornisce un'esportazione completa con un clic, ma puoi usare i report. Il metodo consigliato è esportare il Giornale Generale (tutte le transazioni) nell'intervallo di date desiderato. In QuickBooks Desktop, apri Report → Commercialista e Tasse → Giornale, imposta le Date dalla transazione più remota a oggi e clicca Esporta → Excel. Salva il risultato come CSV dopo aver rimosso eventuali intestazioni/piè di pagina del report e colonne vuote. Assicurati che i dati numerici siano puliti: includi i centesimi (es. 3.00 non 3), nessuna virgoletta extra, e nessun simbolo di valuta o doppio negativo nel CSV. Il CSV dovrebbe avere colonne come Data, Trans. #, Nome, Conto, Nota, Dare, Avere, Saldo (o una singola colonna Importo a seconda del formato del report).

Suggerimento: QuickBooks Desktop 2015+ può anche esportare transazioni tramite la finestra di dialogo Trova. Usa Modifica → Trova → Avanzate, imposta l'intervallo di date per cinque anni, quindi esporta i risultati in CSV. Avvertenza: Alcune versioni limitano l'esportazione a 32.768 righe. Se hai dati molto grandi, esporta anno per anno (o in blocchi più piccoli) per evitare il troncamento, poi combinali successivamente. Assicurati che gli intervalli di date non si sovrappongano per evitare duplicati.

Altri Formati (QBO/QFX/QIF): QuickBooks Desktop può importare transazioni bancarie tramite file .QBO (Web Connect) o .QFX/.OFX, ma per esportare da QuickBooks, questi non sono tipici. Se il tuo obiettivo è estrarre solo transazioni bancarie, potresti già averle in QBO/OFX dalla tua banca. Tuttavia, per un'esportazione completa della contabilità generale, attieniti a IIF e CSV. QuickBooks Desktop non può esportare direttamente in QIF (Quicken Interchange Format) senza strumenti di terze parti. Se trovi un modo per ottenere QIF, nota che alcuni strumenti di contabilità generale (vecchi Ledger 2.x) potevano leggere QIF, ma è meglio lavorare con CSV nel nostro flusso di lavoro.

1.2 QuickBooks Online – Opzioni di Esportazione​

Esportazione Excel/CSV Integrata: QuickBooks Online (QBO) fornisce uno strumento Esporta Dati. Vai su Impostazioni ⚙ → Strumenti → Esporta Dati. Nella finestra di dialogo di esportazione, usa la scheda Report per selezionare i dati (es. Registro Generale o Elenco Transazioni) e la scheda Elenchi per gli elenchi (piano dei conti, ecc.), scegli Tutte le date ed esporta in Excel. QuickBooks Online scaricherà un file ZIP contenente più file Excel per i report e gli elenchi selezionati (ad esempio, Conto Economico, Stato Patrimoniale, Registro Generale, Clienti, Fornitori, Piano dei Conti, ecc.). Puoi quindi convertire questi file Excel in CSV per l'elaborazione.

Report Dettaglio Transazioni: Se l'esportazione predefinita di QBO non include un singolo file del Registro Generale, puoi eseguire manualmente un report dettagliato:

1. Vai su Report e trova Dettaglio Transazioni per Conto (o Registro Generale in alcune versioni di QBO).
2. Imposta Periodo del report sull'intero intervallo di cinque anni.
3. Nelle opzioni del report, imposta Raggruppa per = Nessuno (per elencare le singole transazioni senza subtotali).
4. Personalizza le colonne per includere almeno: Data, Tipo Transazione, Numero, Nome (Beneficiario/Cliente), Nota/Descrizione, Conto, Dare, Avere (o colonna Importo singolo), e Saldo. Includi eventuali classe o località se utilizzate.
5. Esegui il report e poi Esporta in Excel.

Questo produce un registro dettagliato di tutte le transazioni. Salvalo come CSV. Ogni riga rappresenterà una singola ripartizione (registrazione) di una transazione. Dovrai successivamente raggruppare le righe per transazione per la conversione.

Piano dei Conti e Altri Elenchi: QuickBooks Online può esportare il piano dei conti tramite Contabilità → Piano dei Conti → Azioni in Batch → Esporta in Excel. Fallo per ottenere nomi e tipi dei conti. Allo stesso modo, esporta Clienti, Fornitori, ecc., se desideri conservare i nomi per i metadati.

API di QuickBooks Online (Opzionale): Per un approccio programmatico, Intuit fornisce un'API REST per i dati QBO. Gli utenti avanzati possono creare un'app QuickBooks Online (richiede un account sviluppatore) e usare l'API per recuperare i dati in JSON. Ad esempio, potresti interrogare l'endpoint Account per il piano dei conti e gli endpoint del report JournalEntry o GeneralLedger per le transazioni. Esistono SDK Python come python-quickbooks che incapsulano l'API. Tuttavia, l'uso dell'API comporta l'autenticazione OAuth ed è eccessivo per una migrazione una tantum a meno che tu non preferisca l'automazione. Per la maggior parte dei casi, l'esportazione manuale in CSV/Excel è più semplice e meno soggetta a errori.

Fase 2: Trasformazione e Pulizia dei Dati​

Una volta ottenuti i dati di QuickBooks in CSV (e/o IIF), il passo successivo è convertirli nel formato di contabilità in testo semplice di Beancount. Questo comporta l'analisi delle esportazioni, la mappatura dei conti QuickBooks a un piano dei conti Beancount e la formattazione delle transazioni nella sintassi Beancount.

2.1 Analisi delle Esportazioni QuickBooks con Python​

Usare Python garantirà accuratezza e riproducibilità per la trasformazione. Delineeremo script per due attività chiave: importare il piano dei conti e convertire le transazioni.

Importazione e Mappatura dei Conti: È fondamentale impostare i tuoi conti in Beancount prima di aggiungere le transazioni. I conti QuickBooks hanno tipi (Banca, Crediti Commerciali, Costi, ecc.) che mapperemo nella gerarchia di Beancount (Attività, Passività, Ricavi, Costi, ecc.). Ad esempio, possiamo usare una mappatura come:

# Mappa dei tipi di conto QuickBooks alla categoria principale Beancount
AccountTypeMap = {
    'BANK': 'Assets',
    'CCARD': 'Liabilities',
    'AR': 'Assets',       # Crediti Commerciali come attività
    'AP': 'Liabilities',  # Debiti Commerciali come passività
    'FIXASSET': 'Assets',
    'OASSET': 'Assets',   # Altre Attività
    'OCASSET': 'Assets',  # Altre Attività Correnti
    'LTLIAB': 'Liabilities', # Passività a Lungo Termine
    'OCLIAB': 'Liabilities', # Altre Passività Correnti
    'EQUITY': 'Equity',
    'INC': 'Income',
    'EXP': 'Expenses',
    'EXINC': 'Income',    # Altri Ricavi
    'EXEXP': 'Expenses',  # Altri Costi
}

Usando l'esportazione IIF di QuickBooks Desktop o il CSV dell'elenco conti di QBO, recuperiamo il nome e il tipo di ogni conto. Quindi:

• Crea nomi conto Beancount: QuickBooks a volte usa i due punti (:) nei nomi dei conti per indicare i sottoconti (es., “Attività Correnti:Conto Corrente”). Beancount usa la stessa notazione con i due punti per la gerarchia. Spesso puoi riutilizzare il nome direttamente. Se i nomi dei conti QuickBooks non iniziano con una categoria, anteponi la categoria mappata. Ad esempio, un conto QuickBooks di tipo BANK chiamato "Conto Corrente" diventerà Assets:Conto Corrente in Beancount. Un conto EXP (costo) "Pranzi" diventa Expenses:Pranzi, ecc.

• Assicura nomi validi: Rimuovi o sostituisci eventuali caratteri che potrebbero confondere Beancount. QuickBooks consente caratteri come & o / nei nomi. È saggio rimuovere o sostituire i caratteri speciali (es., sostituisci & con e, rimuovi barre o spazi). Inoltre, assicurati che tutti i nomi dei conti siano univoci dopo la trasformazione – QuickBooks potrebbe aver consentito lo stesso nome di sottoconto sotto diversi genitori, il che va bene, ma in Beancount il nome completo (con i genitori) deve essere univoco. Se necessario, rinomina o aggiungi un qualificatore per distinguerli.

• Output delle aperture conti: In Beancount, ogni conto utilizzato deve essere aperto con una direttiva open. Puoi scegliere una data prima della tua prima transazione (es., se migri dati 2019–2023, usa 2018-12-31 o una data ancora precedente per tutte le aperture). Lo script scriverà righe come: 2018-12-31 open Assets:Conto Corrente USD 2018-12-31 open Expenses:Pranzi USD per ogni conto (supponendo che USD sia la valuta principale). Usa la valuta appropriata per ogni conto (vedi note sulla multi-valuta di seguito).

Conversione delle Transazioni: La sfida principale è convertire l'esportazione delle transazioni QuickBooks (CSV) in voci Beancount. Ogni transazione QuickBooks (fattura di vendita, fattura di acquisto, assegno, scrittura contabile, ecc.) può avere più ripartizioni (righe) che devono essere raccolte in un'unica transazione Beancount.

Useremo il lettore CSV di Python per iterare attraverso le righe esportate e accumulare le ripartizioni:

import csv
from collections import defaultdict
 
# Leggi tutte le righe dal CSV del Giornale QuickBooks
rows = []
with open('quickbooks_exported_journal.csv', 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    for line in reader:
        rows.append(line)
 
# Raggruppa le righe per transazione (supponendo che 'Trans. #' identifichi le transazioni)
transactions = defaultdict(list)
for line in rows:
    trans_id = line.get('Trans. #') or line.get('ID Transazione') or line.get('Num')
    transactions[trans_id].append(line)

Ora transactions è un dizionario in cui ogni chiave è un ID/numero di transazione e il valore è l'elenco delle ripartizioni per quella transazione. Successivamente, convertiamo ogni gruppo in Beancount:

def format_date(qb_date):
    # Le date QuickBooks potrebbero essere come "31/12/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():
    # Ordina le ripartizioni per numero di riga se necessario (di solito escono in ordine)
    splits = sorted(splits, key=lambda x: x.get('Riga') or 0)
    first = splits[0]
    date = format_date(first['Data'])
    payee = first.get('Nome', "").strip()
    memo = first.get('Nota', "").strip()
    # Intestazione transazione
    output_lines.append(f"{date} * \"{payee}\" \"{memo}\"")
    if first.get('Num'):  # include il numero di riferimento se disponibile
        output_lines.append(f"  number: \"{first['Num']}\"")
    # Cicla su ogni ripartizione/registrazione
    for split in splits:
        acct_name = split['Conto'].strip()
        # Mappa il nome conto QuickBooks al conto Beancount (usando la mappatura precedente)
        beancount_acct = account_map.get(acct_name, acct_name)
        # Determina l'importo con segno:
        amount = split.get('Importo') or ""
        debit = split.get('Dare') or ""
        credit = split.get('Avere') or ""
        if amount:
            # Alcune esportazioni hanno una singola colonna Importo (negativo per gli avere)
            amt_str = amount
        else:
            # Se ci sono colonne Dare/Avere separate
            amt_str = debit if debit else f"-{credit}"
        # Rimuovi eventuali virgole dai numeri per sicurezza
        amt_str = amt_str.replace(",", "")
        # Allega la valuta
        currency = split.get('Valuta') or "USD"
        amt_str = f"{amt_str} {currency}"
        # Nota/descrizione per la ripartizione
        line_memo = split.get('Nota', "").strip()
        comment = f" ; {line_memo}" if line_memo else ""
        output_lines.append(f"  {beancount_acct:<40} {amt_str}{comment}")
    # Fine della transazione – riga vuota
    output_lines.append("")

Questa logica dello script fa quanto segue:

• Formatta la data in AAAA-MM-GG per Beancount.

• Usa il beneficiario (Nome) e la nota per la narrazione della transazione. Ad esempio: 2020-05-01 * "ACME Corp" "Pagamento fattura" (Se non c'è beneficiario, potresti usare il Tipo di transazione QuickBooks o lasciare il beneficiario tra virgolette vuote).

• Aggiunge un metadato number se c'è un numero di riferimento (numero assegno, numero fattura, ecc.).

• Itera su ogni riga di ripartizione:

  • Mappa il nome conto QuickBooks al conto Beancount usando un dizionario account_map (popolato dal passaggio del piano dei conti).
  • Determina l'importo. A seconda della tua esportazione, potresti avere una singola colonna Importo (con valori positivi/negativi) o colonne Dare e Avere separate. Il codice sopra gestisce entrambi i casi. Assicura che gli avere siano rappresentati come importi negativi per Beancount (poiché in Beancount, viene utilizzato un singolo numero con segno per registrazione).
  • Allega la valuta (supponendo USD a meno che non sia presente una colonna valuta diversa).
  • Scrive la riga di registrazione Beancount con il conto, l'importo e un commento con la nota di riga. Ad esempio: Assets:Conto Corrente 500.00 USD ; Deposito Income:Vendite -500.00 USD ; Deposito Questo riflette un deposito di $500 (da Ricavi a Conto Corrente).

• Dopo aver elencato tutte le ripartizioni, una riga vuota separa la transazione.

Gestione multi-valuta: Se i tuoi dati QuickBooks coinvolgono più valute, includi il codice valuta su ogni registrazione (come mostrato sopra). Assicurati che i conti in valute estere siano aperti con quella valuta. Ad esempio, se hai un conto corrente in EUR, dovresti emettere open Assets:Banca:Conto Corrente EUR e le transazioni in quel conto useranno EUR. Beancount supporta contabilità multi-valuta e terrà traccia delle conversioni implicite, ma potresti dover aggiungere voci di prezzo per i tassi di cambio se desideri la conversione in una valuta base nei report. Si consiglia anche di dichiarare la tua valuta operativa principale all'inizio del file Beancount (es., option "operating_currency" "USD").

Esecuzione della conversione: Salva lo script Python (ad esempio, come qb_to_beancount.py) ed eseguilo sui tuoi file esportati. Dovrebbe produrre un file .beancount contenente tutti i conti e le transazioni.

2.2 Gestione dei Casi Limite e Pulizia dei Dati​

Durante la trasformazione, tieni presente questi problemi comuni e come affrontarli:

• Disallineamenti dei Nomi Conto: QuickBooks potrebbe avere nomi di conto che entrano in conflitto con i nomi gerarchici di Beancount. Ad esempio, QuickBooks potrebbe avere due diversi conti genitori, ciascuno con un sottoconto chiamato "Assicurazione". In Beancount, Expenses:Assicurazione deve essere univoco. Risolvi rinominando uno (es., "Assicurazione-Veicolo" vs "Assicurazione-Salute") prima dell'esportazione o mappandoli a conti Beancount univoci nel tuo script. Convenzioni di denominazione coerenti (nessun carattere speciale e uso della gerarchia) ti faranno risparmiare mal di testa. Usa l'approccio file di rimappatura se necessario: mantieni un CSV o un dizionario di vecchio nome → nuovo nome Beancount e applicalo durante la conversione (il nostro codice di esempio usa un account_map e potrebbe caricare override da un file).

• Date e Formati: Assicurati che tutte le date siano formattate in modo coerente. Lo script sopra normalizza M/G/A in formato ISO. Inoltre, fai attenzione ai problemi tra anno fiscale e anno solare se il tuo periodo di cinque anni attraversa la fine di un anno. A Beancount non interessa dei confini dell'anno fiscale, ma potresti successivamente voler dividere i file per anno per comodità.

• Precisione Numerica: QuickBooks gestisce la valuta con i centesimi, quindi lavorare con i centesimi di solito va bene. Tutti gli importi dovrebbero idealmente avere due cifre decimali nel CSV. Se alcuni importi sono diventati interi (nessun decimale) o hanno virgole/parentesi (per i negativi), puliscili nello script (rimuovi virgole, converti (100.00) in -100.00, ecc.). L'esportazione CSV se eseguita correttamente (come da istruzioni) dovrebbe già evitare questi problemi di formattazione.

• Importi Negativi e Segni: I report QuickBooks a volte mostrano i negativi come -100.00 o come (100.00) o anche --100.00 in certe esportazioni Excel. Il passaggio di pulizia dovrebbe gestirli. Assicurati che i dare e gli avere di ogni transazione si compensino a zero. Beancount lo applicherà (se non bilanciato, genererà un errore all'importazione).

• Duplicati di Transazioni: Se hai dovuto esportare le transazioni in lotti (es., anno per anno o conto per conto), fai attenzione a unirli senza sovrapposizioni. Controlla che la prima transazione di un anno non sia anche l'ultima del lotto precedente, ecc. È facile duplicare accidentalmente alcune transazioni ai confini. Se sospetti duplicati, puoi ordinare le voci Beancount finali per data e cercare voci identiche, o usare i tag univoci delle transazioni di Beancount per individuarli. Una strategia è includere i numeri di transazione QuickBooks come metadati (es., usa Trans. # o il numero fattura come tag txn o metadato quickbooks_id) e quindi assicurarti che non esistano duplicati di tali ID.

• Ripartizioni Non Bilanciate / Conti Transitori: QuickBooks potrebbe avere casi particolari come una transazione con uno sbilanciamento che QuickBooks ha auto-aggiustato a un conto "Saldo di Apertura Patrimonio Netto" o "Utili Portati a Nuovo". Ad esempio, quando si impostano i saldi iniziali dei conti, QuickBooks spesso registra le differenze in un conto Patrimonio Netto. Questi appariranno nelle transazioni esportate. Beancount richiederà un bilanciamento esplicito. Potresti dover introdurre un conto Patrimonio Netto per i saldi di apertura (comunemente Equity:Saldi-Apertura) per rispecchiare QuickBooks. È buona pratica avere una voce di saldo di apertura nel primo giorno della tua contabilità che stabilisca i saldi iniziali di tutti i conti (vedi Fase 5).

• Casi Limite Multi-Valuta: Se si utilizza multi-valuta, l'esportazione di QuickBooks potrebbe elencare tutti gli importi in valuta domestica o nella loro valuta nativa. Idealmente, ottieni i dati in valuta nativa per ogni conto (i report di QuickBooks Online di solito lo fanno). In Beancount, ogni registrazione porta una valuta. Se QuickBooks ha fornito tassi di cambio o una conversione in valuta domestica, potresti ignorarli e fare affidamento sulle voci di prezzo di Beancount. Se QuickBooks non ha esportato i tassi di cambio, potresti voler aggiungere manualmente record di prezzo (es., usando la direttiva price di Beancount) per date chiave per abbinare la valutazione. Tuttavia, per l'integrità di base della contabilità generale, è sufficiente che le transazioni siano bilanciate nelle loro valute originali – le plusvalenze/minusvalenze non realizzate non devono essere registrate esplicitamente a meno che tu non voglia gli stessi report.

• Crediti Commerciali / Debiti Commerciali: QuickBooks tiene traccia dei dettagli di fatture di vendita e acquisto (date di scadenza, stato pagato, ecc.) che non verranno trasferiti completamente in una contabilità semplice. Otterrai le transazioni di Crediti/Debiti Commerciali (fatture che aumentano i Crediti, pagamenti che li diminuiscono, ecc.), ma non i documenti delle fatture o i saldi dei clienti per fattura. Di conseguenza, dopo la migrazione, dovresti verificare che i saldi dei tuoi conti Crediti Commerciali e Debiti Commerciali in Beancount siano uguali ai saldi aperti di clienti/fornitori in QuickBooks. Se devi tenere traccia delle fatture, potresti usare i metadati di Beancount (es., includere un tag invoice o un link). I numeri delle fatture QuickBooks dovrebbero essere arrivati attraverso i campi Num o Nota – il nostro script preserva Num come number: "..." nei metadati della transazione.

• Conti Inattivi o Chiusi: L'esportazione IIF potrebbe includere conti inattivi (se hai scelto di includerli). Va bene importarli (avranno solo zero transazioni e saldo zero se veramente inattivi). Puoi contrassegnarli come chiusi in Beancount dopo l'ultima data di transazione con una direttiva close. Questo mantiene la tua contabilità in ordine. Ad esempio: 2023-12-31 close Expenses:VecchioConto ; chiuso dopo la migrazione Questo è facoltativo e principalmente per pulizia.

Pulendo e mappando attentamente i dati come sopra, avrai un file di contabilità Beancount che rispecchia strutturalmente i tuoi dati QuickBooks. Il passo successivo è verificare che rispecchi anche numericamente QuickBooks.

Fase 3: Convalida e Riconciliazione dei Dati​

La convalida è una fase critica in una migrazione di dati contabili. Dobbiamo assicurarci che la contabilità Beancount corrisponda ai libri QuickBooks al centesimo. Diverse strategie e strumenti possono essere utilizzati:

3.1 Riconciliazione del Bilancio di Verifica​

Un report bilancio di verifica elenca i saldi finali di tutti i conti (con dare/avere o positivo/negativo indicati) e dovrebbe dare zero. Eseguire un bilancio di verifica in entrambi i sistemi per la stessa data è il modo più rapido per confermare l'accuratezza complessiva.

• In QuickBooks: Esegui un report Bilancio di Verifica per l'ultimo giorno dell'anno finale (es., 31 dicembre 2023). Questo report mostra il saldo di ogni conto. Esportalo o prendi nota delle cifre chiave.

• In Beancount: Usa i report di Beancount per generare un bilancio di verifica. Un metodo semplice è tramite la riga di comando:

  bean-report migrated.beancount balances

  Il report balances è un bilancio di verifica che elenca tutti i conti e i loro saldi. Puoi anche aprire il file in Fava (l'interfaccia web di Beancount) e guardare la sezione Saldi o Stato Patrimoniale. Ogni saldo conto in Beancount dovrebbe corrispondere al bilancio di verifica di QuickBooks. Ad esempio, se QuickBooks mostra Crediti Commerciali = $5.000, allora il conto Assets:Crediti Commerciali in Beancount dovrebbe totalizzare $5.000 (dare). Se Ricavi di Vendita = $200.000, il conto Income:Vendite in Beancount dovrebbe mostrare $200.000 (avere, che potrebbe apparire come -200.000 se si utilizza un bilancio di verifica che presenta gli avere come negativi).

Se ci sono discrepanze, individua:

• Controlla se un intero conto manca o è extra (abbiamo dimenticato un conto o ne abbiamo incluso uno già chiuso prima del periodo di migrazione?).
• Se un saldo è sballato, approfondisci: QuickBooks può eseguire un Report Rapido o dettaglio contabile per quel conto, e puoi confrontarlo con il registro di Beancount per quel conto (bean-report migrated.beancount register -a NomeConto). A volte le differenze derivano da una transazione mancante o da un duplicato.

Verifica anche che la somma di tutti i conti sia zero nel bilancio di verifica di Beancount (stampa un totale che dovrebbe essere zero o molto vicino a zero). Beancount applica la partita doppia, quindi se hai uno sbilanciamento diverso da zero, significa che attività meno passività-patrimonio netto non danno zero, indicando un problema (che QuickBooks normalmente non consentirebbe, ma potrebbe accadere se alcuni dati sono stati persi).

3.2 Confronti dei Saldi dei Conti​

Oltre al bilancio di verifica, puoi confrontare specifici bilanci:

• Stato Patrimoniale: Esegui uno Stato Patrimoniale QuickBooks per la data finale e uno stato patrimoniale Beancount (bean-report migrated.beancount balsheet). Questo è simile al bilancio di verifica ma organizzato per Attività, Passività, Patrimonio Netto. I numeri dovrebbero allinearsi per categoria. Per un controllo più granulare, confronta i totali dei conti principali: cassa, Crediti Commerciali, immobilizzazioni, debiti commerciali, patrimonio netto, ecc.

• Conto Economico: Esegui un Conto Economico per il periodo di cinque anni (o anno per anno) in QuickBooks e in Beancount (bean-report migrated.beancount income per un conto economico dell'intero periodo). L'utile netto di Beancount dovrebbe essere uguale a quello di QuickBooks per ogni periodo. Se hai migrato tutti e cinque gli anni, l'utile netto cumulativo dovrebbe corrispondere. Puoi anche confrontare i totali delle singole voci di ricavo e costo per assicurarti che nessuna categoria sia stata persa o duplicata.

• Campionatura Casuale di Transazioni: Scegli alcune transazioni casuali (soprattutto da ogni anno e da ogni conto principale) e verifica che siano migrate correttamente. Ad esempio, trova una fattura di 3 anni fa in QuickBooks e poi cerca il suo importo o nota nel file Beancount (poiché tutte le transazioni sono testo, puoi aprire il file .beancount in un editor di testo o usare strumenti di ricerca). Controlla che data, importi e conti corrispondano. Questo aiuta a individuare eventuali problemi di formattazione della data o conti mappati erroneamente.

3.3 Controlli di Integrità Automatizzati​

Sfrutta gli strumenti di convalida di Beancount:

• bean-check: Esegui bean-check migrated.beancount. Questo analizzerà il file e segnalerà eventuali errori di sintassi o bilanciamento. Se lo script ha perso qualcosa come un conto non aperto o una transazione non bilanciata, bean-check lo segnalerà. Un passaggio pulito (nessun output) significa che il file è almeno internamente coerente.

• Asserzioni di Saldo: Puoi aggiungere asserzioni di saldo esplicite nella contabilità per i conti chiave come controllo aggiuntivo. Ad esempio, se conosci il saldo del conto corrente bancario in una certa data, aggiungi una riga: 2023-12-31 balance Assets:Banca:Conto Corrente 10000.00 USD Quindi bean-check garantirà che, nella contabilità, a partire da quella data, il saldo sia effettivamente di $10.000. Questo è facoltativo ma può essere utile per conti di alta importanza. Potresti prendere i saldi finali da QuickBooks (es., fine di ogni anno) e affermarli nel file Beancount. Se una qualsiasi asserzione fallisce, Beancount segnalerà una differenza.

• Avanzamento del Bilancio di Verifica: Se preferisci, puoi fare un controllo periodo per periodo. Per ogni anno, confronta la variazione netta. Ad esempio, l'utile netto in QuickBooks 2020 vs Beancount 2020, ecc., per assicurarti che ogni anno si sia chiuso correttamente nel patrimonio netto (QuickBooks sposta automaticamente l'utile netto negli Utili Portati a Nuovo ogni nuovo anno; in Beancount vedrai solo il patrimonio netto cumulativo). Se vedi differenze, potrebbe indicare un problema nei dati di un anno specifico.

• Conteggio Transazioni e Duplicati: Conta il numero di transazioni in QuickBooks vs Beancount. QuickBooks non mostra un conteggio diretto facilmente, ma puoi valutarlo contando le righe nel CSV (ogni intestazione di transazione vs ripartizioni). In Beancount, un modo rapido è contare le occorrenze di txn o * " nel file. Dovrebbero essere uguali o leggermente superiori a QuickBooks (se hai aggiunto transazioni di saldo di apertura o aggiustamenti). Una discrepanza significativa significa che qualcosa potrebbe essere stato omesso o duplicato. Il nostro uso di ID univoci nei metadati può aiutare: se sospetti duplicati, cerca nel file Beancount lo stesso numero di assegno o fattura che appare due volte quando non dovrebbe.

• Stato di Riconciliazione: Abbiamo incluso un metadato rec: "y" o "n" basato sullo stato di riconciliazione di QuickBooks nel nostro script (come rec nell'esempio). Questa non è una funzionalità standard di Beancount (Beancount non tiene traccia di riconciliato/in sospeso allo stesso modo di Ledger), ma può essere un metadato utile. Potresti verificare che tutte le transazioni che sono state riconciliate in QuickBooks siano presenti. In definitiva, riconciliare nuovamente i conti bancari in Beancount (usando i tuoi estratti conto) potrebbe essere la prova finale che non manca nulla.

Eseguendo queste validazioni, acquisisci fiducia che la migrazione abbia preservato i dati. Prenditi il tuo tempo con questa fase – è più facile correggere le anomalie ora che mesi dopo, quando i libri potrebbero essere di riferimento. Problemi comuni se la convalida fallisce: saldo di apertura di un conto mancante, transazione datata al di fuori dell'intervallo o inversione di segno su una voce. Tutti sono risolvibili una volta identificati.

Fase 4: Impegno nella Contabilità Beancount​

Dopo la pulizia e la convalida, è il momento di formalizzare i dati nella struttura della tua contabilità Beancount. "Impegnarsi" qui significa sia finalizzare i file di contabilità che potenzialmente inserirli in un sistema di controllo versione per la verificabilità.

4.1 Organizzazione dei File di Contabilità e Configurazione​

Decidi come strutturare i file di contabilità Beancount. Per cinque anni di dati, puoi mantenere tutto in un file o dividerlo per anno o categoria. Una struttura comune e chiara è:

• File di Contabilità Principale: es., ledger.beancount – Questo è il punto di ingresso che può includere altri file. Potrebbe contenere opzioni globali e poi includere file annuali.
• File dei Conti: Definisci il piano dei conti e i saldi di apertura. Ad esempio, accounts.beancount con tutte le direttive open (come generate dallo script). Potresti anche elencare le merci (valute) qui.
• File delle Transazioni: Uno per anno, es., 2019.beancount, 2020.beancount, ecc., contenenti le transazioni per quell'anno. Questo mantiene ogni file di dimensioni gestibili e ti permette di concentrarti su un anno se necessario. In alternativa, puoi dividere per entità o conto, ma la suddivisione basata sul tempo è semplice per i dati finanziari.

Esempio di file principale:

option "title" "La Mia Contabilità Aziendale"
option "operating_currency" "USD"
 
include "accounts.beancount"
include "2019.beancount"
include "2020.beancount"
...
include "2023.beancount"

In questo modo, tutti i dati vengono aggregati quando esegui i report, ma mantieni l'ordine.

Beancount non richiede file multipli – potresti avere un file unico grande – ma la struttura sopra migliora la chiarezza e il controllo versione. Secondo le migliori pratiche di Beancount, è bene usare intestazioni di sezione chiare e raggruppare le voci correlate in modo logico.

4.2 Impostazione dei Saldi di Apertura e del Patrimonio Netto​

Se la tua migrazione non parte da zero assoluto, dovrai gestire i saldi di apertura. Due scenari:

• Libri che iniziano da zero: Se il periodo di cinque anni inizia con l'inizio dell'attività (es., hai iniziato a usare QuickBooks a gennaio 2019 con tutti i conti azzerati tranne il patrimonio netto iniziale), potresti non aver bisogno di una transazione di saldo di apertura separata. Le prime transazioni nel 2019 (come il finanziamento iniziale a un conto bancario) stabiliranno naturalmente i saldi di apertura. Assicurati solo che qualsiasi capitale iniziale o utili portati a nuovo precedenti siano contabilizzati tramite transazioni di patrimonio netto.

• Libri a metà percorso (storia parziale): Se hai iniziato QuickBooks prima e il 2019 è un punto intermedio, allora al 1° gennaio 2019 ogni conto aveva un saldo riportato. QuickBooks li avrà come saldi di apertura o utili portati a nuovo. In Beancount, è tipico creare una voce di Saldi di Apertura il giorno prima della data di inizio:

  • Usa un conto di patrimonio netto chiamato Equity:Saldi-Apertura (o simile) per compensare la somma di tutti gli importi di apertura.
  • Esempio: se al 31-12-2018, la Cassa era di $10.000 e i Crediti Commerciali di $5.000 e i Debiti Commerciali di $3.000 (avere), scriveresti una transazione: 2018-12-31 * "Saldi di Apertura" Assets:Cassa 10000.00 USD Assets:Crediti Commerciali 5000.00 USD Liabilities:Debiti Commerciali -3000.00 USD Equity:Saldi-Apertura -12000.00 USD Questo lascia Saldi-Apertura con la somma negativa (–$12k) che bilancia la voce. Ora tutti i conti di attività/passività iniziano il 2019 con i saldi corretti. Questo dovrebbe rispecchiare qualsiasi "Utili Portati a Nuovo" o saldi riportati di QuickBooks.
  • In alternativa, usa le direttive pad e balance di Beancount: Per ogni conto, puoi pad da Saldi-Apertura e asserire il saldo. Questo è un modo più automatizzato. Ad esempio: 2018-12-31 pad Assets:Cassa Equity:Saldi-Apertura 2018-12-31 balance Assets:Cassa 10000.00 USD Questo dice a Beancount di inserire qualsiasi voce necessaria (a Saldi-Apertura) in modo che Cassa sia uguale a 10000 USD a quella data. Fallo per ogni conto. Il risultato è simile, ma scrivere una transazione esplicita come nel primo metodo è semplice.

• Utili Portati a Nuovo: QuickBooks non esporta esplicitamente una transazione "Utili Portati a Nuovo" – lo calcola e basta. Dopo la migrazione, potresti notare che Equity:Utili Portati a Nuovo è zero se non l'hai creato. In Beancount, gli utili portati a nuovo sono semplicemente gli utili degli anni precedenti. Puoi scegliere di creare un conto Utili Portati a Nuovo e trasferire gli utili precedenti in esso il primo giorno di ogni nuovo anno, o semplicemente lasciare che il patrimonio netto sia la somma di tutti i ricavi/costi (che appare nella sezione Patrimonio Netto nei report). Per trasparenza, alcuni utenti registrano scritture di chiusura annualmente. Questo è facoltativo e principalmente per presentazione. Poiché abbiamo migrato tutte le transazioni, l'utile per ogni anno si accumulerà naturalmente se esegui un report per anno.

• Controlli Comparativi: Dopo aver impostato i saldi di apertura, esegui uno stato patrimoniale alla data di inizio per assicurarti che tutto sia corretto (dovrebbe mostrare quei saldi di apertura che si azzerano con il Patrimonio Netto di Apertura).

4.3 Finalizzazione e Controllo Versione​

Ora che i dati sono in formato Beancount e strutturati, è saggio impegnare i file in un repository di controllo versione (es., git). Ogni modifica alla contabilità può essere tracciata e hai una traccia di controllo di tutte le modifiche. Questo è un grande vantaggio della contabilità in testo semplice. Ad esempio, in QuickBooks le modifiche potrebbero non essere facilmente differenziabili, ma in Beancount puoi vedere le differenze riga per riga. Come notano alcuni utenti, con Beancount ottieni trasparenza e la possibilità di annullare le modifiche se necessario – ogni voce può essere collegata a una cronologia delle modifiche.

Considera di taggare il commit di questa migrazione iniziale come v1.0 o simile, in modo da sapere che rappresenta lo stato dei libri come importato da QuickBooks. D'ora in poi, inserirai nuove transazioni direttamente in Beancount (o le importerai da feed bancari, ecc.) e potrai usare normali pratiche di sviluppo software (committing mensile o giornaliero, usando rami per esperimenti, ecc.).

Configurazione di Fava o altri strumenti: Fava è un'interfaccia web per Beancount che rende facile visualizzare i report. Dopo il commit, esegui fava ledger.beancount per navigare nei bilanci e confrontarli un'ultima volta con i tuoi report QuickBooks. Potresti individuare piccole differenze più facilmente in un'interfaccia utente (ad esempio, un conto che dovrebbe essere zero ma mostra un piccolo saldo indica una voce di chiusura mancante o una transazione fuori posto).

Convenzioni di denominazione e coerenza: Ora hai il controllo totale, quindi assicurati la coerenza:

• Tutti i conti dovrebbero avere nomi chiari, che iniziano con nomi di categoria in maiuscolo (Assets, Liabilities, ecc.). Se alcuni sembrano strani (es., Assets:assets:QualcheConto a causa di una discrepanza tra maiuscole e minuscole da QuickBooks), rinominali nel file dei conti e aggiorna le transazioni (una rapida ricerca e sostituzione sul file può farlo, o usa bean-format di Beancount o il multi-cursore dell'editor).
• I simboli delle merci (codici valuta) dovrebbero essere coerenti. Per USD, usa USD ovunque (non $ o US$). Per altri, usa codici standard (EUR, GBP, ecc.). Questa coerenza è importante per le ricerche di prezzo e i report di Beancount.
• Rimuovi eventuali conti temporanei o fittizi che potrebbero essere stati creati (ad esempio, se hai usato Expenses:Varie per conti sconosciuti nello script come contenitore, cerca di eliminarli mappando correttamente tutti i conti).

Chiusura di QuickBooks: A questo punto, dovresti avere libri paralleli in Beancount che corrispondono a QuickBooks. Alcuni scelgono di eseguire entrambi i sistemi in parallelo per un breve periodo per assicurarsi che nulla sia stato perso. Ma se la convalida è solida, puoi "chiudere" i libri QuickBooks:

• Se questo è un ambiente aziendale, considera di esportare tutti i documenti sorgente di QuickBooks (fatture di vendita, fatture di acquisto, ricevute) per i registri, poiché non esisteranno in Beancount a meno che non li alleghi manualmente.
• Mantieni un backup dei dati QuickBooks (sia il file aziendale che i file di esportazione).
• D'ora in poi, mantieni la contabilità Beancount come sistema di registrazione principale.

Impegnando i dati nella contabilità Beancount, hai completato il flusso di lavoro di migrazione. Il passo finale è eseguire un audit e dimostrare la coerenza dei bilanci, per soddisfare te stesso (e qualsiasi stakeholder o revisore) che la migrazione è stata un successo.

Fase 5: Audit Post-Migrazione ed Esempi​

Per illustrare il successo della migrazione, prepara un confronto prima e dopo dei bilanci e possibilmente un diff delle transazioni. Questo fornisce la prova che i libri sono coerenti.

5.1 Verifica dei Bilanci​

Produci i principali report finanziari sia da QuickBooks che da Beancount per le stesse date e confronta:

• Stato Patrimoniale al 31 Dicembre 2023: Confronta i totali di Attività, Passività e Patrimonio Netto riga per riga. Dovrebbero corrispondere. Ad esempio, se QuickBooks mostrava Totale Attività = $150.000 e Totale Passività + Patrimonio Netto = $150.000, lo stato patrimoniale Beancount dovrebbe mostrare gli stessi totali. Se hai strutturato i conti leggermente diversamente (diciamo che hai fuso alcuni sottoconti), aggiusta per il confronto o suddividi al livello successivo per assicurarti che le somme siano uguali.

• Conto Economico 2019–2023: Assicurati che il totale dei Ricavi, il totale dei Costi e l'Utile Netto per ogni anno (o l'intero intervallo) siano identici. Potrebbero sorgere piccole differenze se QuickBooks ha fatto degli arrotondamenti nei report, ma le transazioni di solito portano i centesimi esattamente, quindi l'utile netto dovrebbe essere esatto. Se l'utile di un anno differisce, approfondisci i dati di quell'anno – spesso è un indicatore di una voce mancante o duplicata in quel periodo.

• Differenze nel Bilancio di Verifica: Se possibile, crea un foglio di calcolo in cui elenchi ogni conto e il saldo da QuickBooks vs Beancount. Poiché ci aspettiamo che corrispondano, questa potrebbe essere una colonna di differenza tutta zero. Questo è essenzialmente il controllo incrociato del bilancio di verifica di cui abbiamo discusso, ma scriverlo aiuta a documentarlo.

5.2 Esempio di Confronto (Prima vs Dopo)​

Di seguito è riportato un esempio frammento che dimostra la coerenza dei dati. Supponiamo che il nostro bilancio di verifica QuickBooks al 31 Dicembre 2023 fosse:

In Beancount, dopo aver importato e registrato tutte le transazioni fino al 2023, un bean-report balances (bilancio di verifica) produce:

(Nota: Le sezioni del Patrimonio Netto potrebbero essere strutturate diversamente; il punto chiave è che i totali si allineano. Qui, "Utile (2019-2023)" in Beancount svolge il ruolo di utile anno corrente/utili portati a nuovo combinati, mostrando zero perché l'utile è stato chiuso negli Utili Portati a Nuovo.)

Come mostrato, ogni conto corrisponde al centesimo. La somma dei dare è uguale alla somma degli avere in entrambi i lati.

Inoltre, se eseguiamo un Conto Economico per il 2023:

• QuickBooks: Ricavi $50.000, Costi $48.000, Utile Netto $2.000.
• Beancount: Ricavi $50.000, Costi $48.000, Utile Netto $2.000 (che poi è stato chiuso negli Utili Portati a Nuovo o appare sotto Patrimonio Netto nello stato patrimoniale di fine anno).

Puoi creare un diff delle transazioni se necessario, ma poiché i dati QuickBooks non sono in formato contabile, è più efficace fare affidamento sui report. Si potrebbero ordinare sia il CSV QuickBooks che le transazioni Beancount per data e confrontare i campi chiave come controllo finale (questo può essere fatto in Excel o con uno script). Tuttavia, dato che ci fidiamo della nostra convalida precedente, il controllo dei bilanci è di solito sufficiente.

5.3 Suggerimenti per l'Audit​

• Se un revisore o uno stakeholder ha bisogno di rassicurazioni, presenta i bilanci prima e dopo affiancati. La trasparenza di Beancount può effettivamente semplificare gli audit perché puoi tracciare ogni numero da un bilancio alla voce sorgente rapidamente (soprattutto usando la funzionalità di drill-down di Fava).
• Mantieni il backup di QuickBooks e i CSV esportati come parte della tua traccia di audit. Documenta eventuali aggiustamenti effettuati durante la migrazione (ad esempio, "Conto X rinominato in Y per coerenza" o "Transazione Z suddivisa in due voci per chiarezza" se hai apportato tali modifiche).
• D'ora in poi, implementa controlli regolari in Beancount. Ad esempio, la riconciliazione mensile dei conti bancari e un'asserzione del loro saldo finale aiutano a individuare eventuali problemi di dati o errori di inserimento. La migrazione fornisce una buona base di partenza; mantenere la disciplina nel nuovo sistema garantirà un'accuratezza continua.

Infine, celebra il completamento della migrazione: hai trasferito con successo cinque anni di dati contabili da QuickBooks a Beancount. I dati sono ora in un formato di testo leggero e controllato da versione con piena integrità della partita doppia. Hai esportato i dati, li hai trasformati con script Python, hai convalidato l'integrità attraverso bilanci di verifica e report, e li hai impegnati in una contabilità Beancount ben organizzata. Questo processo completo garantisce che la contabilità Beancount sia una replica accurata e fedele dei tuoi libri QuickBooks per il periodo di cinque anni, preparandoti per una contabilità semplificata in futuro.