2 publicacions etiquetades amb "migració"

Fase 1: Exportació de dades des de QuickBooks​

Migrar cinc anys de dades comença per extreure tots els registres de QuickBooks en un format utilitzable. QuickBooks Desktop i QuickBooks Online tenen diferents opcions d'exportació:

1.1 QuickBooks Desktop – Opcions d'exportació​

IIF (Intuit Interchange Format): QuickBooks Desktop pot exportar llistes (com el pla de comptes, clients, proveïdors) a fitxers de text .IIF. A QuickBooks Desktop, aneu a File → Utilities → Export → Lists to IIF i, a continuació, seleccioneu les llistes que necessiteu (p. ex., Pla de comptes, Clients, Proveïdors). Això genera un fitxer de text que inclou noms de comptes, tipus i dades de les llistes. L'IIF és un format propietari però de text pla que és relativament fàcil d'analitzar. Utilitzeu-lo per capturar el vostre Pla de comptes i les llistes de contactes com a referència a Beancount.

Llibre major/Diari via CSV: Per a les dades de transaccions, QuickBooks Desktop no ofereix una exportació completa amb un sol clic, però podeu utilitzar informes. El mètode recomanat és exportar el General Journal (totes les transaccions) per al rang de dates desitjat. A QuickBooks Desktop, obriu Reports → Accountant & Taxes → Journal, establiu les dates des de la primera transacció fins avui i feu clic a Export → Excel. Deseu el resultat com a CSV després d'eliminar les capçaleres/peus de pàgina de l'informe i les columnes buides. Assegureu-vos que les dades numèriques estiguin netes: incloeu els cèntims (p. ex., 3.00, no 3), sense cometes addicionals i sense símbols de moneda o dobles negatius al CSV. El CSV hauria de tenir columnes com Date, Trans #, Name, Account, Memo, Debit, Credit, Balance (o una única columna Amount segons el format de l'informe).

Consell: QuickBooks Desktop 2015+ també pot exportar transaccions a través del diàleg Find. Utilitzeu Edit → Find → Advanced, establiu el rang de dates de cinc anys i després exporteu els resultats a CSV. Avís: Algunes versions limiten l'exportació a 32.768 línies. Si teniu dades molt grans, exporteu any per any (o en blocs més petits) per evitar el truncament i, posteriorment, combineu-los. Assegureu-vos que els rangs de dates no se superposin per evitar duplicats.

Altres formats (QBO/QFX/QIF): QuickBooks Desktop pot importar transaccions bancàries mitjançant fitxers .QBO (Web Connect) o .QFX/.OFX, però per exportar des de QuickBooks, aquests no són típics. Si el vostre objectiu és extreure només les transaccions bancàries, és possible que ja les tingueu en format QBO/OFX del vostre banc. No obstant això, per a una exportació completa del llibre major, utilitzeu IIF i CSV. QuickBooks Desktop no pot exportar directament a QIF (Quicken Interchange Format) sense eines de tercers. Si trobeu una manera d'obtenir QIF, tingueu en compte que algunes eines de llibres comptables (versions antigues de Ledger 2.x) podien llegir QIF, però és millor treballar amb CSV en el nostre procés.

1.2 QuickBooks Online – Opcions d'exportació​

Exportació integrada a Excel/CSV: QuickBooks Online (QBO) ofereix una eina d'Export Data. Aneu a Settings ⚙ → Tools → Export Data. Al diàleg d'exportació, utilitzeu la pestanya Reports per seleccionar les dades (p. ex., General Ledger o Transaction List) i la pestanya Lists per a les llistes (pla de comptes, etc.), trieu All dates i exporteu a Excel. QuickBooks Online descarregarà un ZIP que conté diversos fitxers Excel per als informes i llistes seleccionats (per exemple, Compte de Pèrdues i Guanys, Balanç de Situació, Llibre Major, Clients, Proveïdors, Pla de Comptes, etc.). Després podeu convertir aquests fitxers Excel a CSV per processar-los.

Informe de detall de transaccions: Si l'exportació per defecte de QBO no inclou un únic fitxer de Llibre Major, podeu executar manualment un informe detallat:

1. Aneu a Reports i cerqueu Transaction Detail by Account (o General Ledger en algunes versions de QBO).
2. Establiu el Report period al rang complet de cinc anys.
3. A les opcions de l'informe, establiu Group by = None (per llistar les transaccions individuals sense subtotals).
4. Personalitzeu les columnes per incloure com a mínim: Date, Transaction Type, Number, Name (Payee/Customer), Memo/Description, Account, Debit, Credit (o una única columna Amount) i Balance. Incloeu qualsevol classe o ubicació si s'utilitza.
5. Executeu l'informe i després feu clic a Export to Excel.

Això genera un llibre major detallat de totes les transaccions. Deseu-lo com a CSV. Cada línia representarà una partida (apunt) d'una transacció. Més endavant haureu d'agrupar les línies per transacció per a la conversió.

Pla de comptes i altres llistes: QuickBooks Online pot exportar el pla de comptes mitjançant Accounting → Chart of Accounts → Batch Actions → Export to Excel. Feu-ho per obtenir els noms i tipus de comptes. De la mateixa manera, exporteu Clients, Proveïdors, etc., si voleu traspassar els noms per a les metadades.

API de QuickBooks Online (Opcional): Per a un enfocament programàtic, Intuit ofereix una API REST per a les dades de QBO. Els usuaris avançats poden crear una aplicació de QuickBooks Online (requereix un compte de desenvolupador) i utilitzar l'API per obtenir dades en format JSON. Per exemple, podríeu consultar l'endpoint Account per al pla de comptes i els endpoints de l'informe JournalEntry o GeneralLedger per a les transaccions. Hi ha SDKs de Python com python-quickbooks que encapsulen l'API. No obstant això, l'ús de l'API implica autenticació OAuth i és excessiu per a una migració única, tret que preferiu l'automatització. Per a la majoria dels casos, l'exportació manual a CSV/Excel és més senzilla i menys propensa a errors.

Fase 2: Transformació i neteja de dades​

Un cop teniu les dades de QuickBooks en CSV (i/o IIF), el següent pas és convertir-les al format de llibre comptable de text pla de Beancount. Això implica analitzar les exportacions, mapejar els comptes de QuickBooks a un pla de comptes de Beancount i formatar les transaccions en la sintaxi de Beancount.

2.1 Anàlisi d'exportacions de QuickBooks amb Python​

L'ús de Python garantirà la precisió i la reproductibilitat de la transformació. Descriurem scripts per a dues tasques clau: importar el pla de comptes i convertir les transaccions.

Importació i mapeig de comptes: És crucial configurar els vostres comptes a Beancount abans d'afegir transaccions. Els comptes de QuickBooks tenen tipus (Bank, Accounts Receivable, Expense, etc.) que mapejarem a la jerarquia de Beancount (Assets, Liabilities, Income, Expenses, etc.). Per exemple, podem utilitzar un mapeig com aquest:

# Mapeig del tipus de compte de QuickBooks a la categoria arrel de Beancount
AccountTypeMap = {
    'BANK': 'Assets',
    'CCARD': 'Liabilities',
    'AR': 'Assets',       # Comptes a cobrar com a actiu
    'AP': 'Liabilities',  # Comptes a pagar com a passiu
    'FIXASSET': 'Assets',
    'OASSET': 'Assets',   # Altres actius
    'OCASSET': 'Assets',  # Altres actius corrents
    'LTLIAB': 'Liabilities', # Passius a llarg termini
    'OCLIAB': 'Liabilities', # Altres passius corrents
    'EQUITY': 'Equity',
    'INC': 'Income',
    'EXP': 'Expenses',
    'EXINC': 'Income',    # Altres ingressos
    'EXEXP': 'Expenses',  # Altres despeses
}

Utilitzant l'exportació IIF de QuickBooks Desktop o el CSV de la llista de comptes de QBO, recuperem el nom i el tipus de cada compte. Després:

• Crear noms de compte de Beancount: QuickBooks de vegades utilitza dos punts (:) als noms de compte per denotar subcomptes (p. ex., "Current Assets:Checking"). Beancount utilitza la mateixa notació de dos punts per a la jerarquia. Sovint podeu reutilitzar el nom directament. Si els noms de compte de QuickBooks no comencen amb una categoria, afegiu-hi la categoria mapejada. Per exemple, un compte de QuickBooks de tipus BANK anomenat "Checking" es convertirà en Assets:Checking a Beancount. Un compte EXP (despesa) "Meals" es converteix en Expenses:Meals, etc.

• Assegurar una nomenclatura vàlida: Elimineu o substituïu qualsevol caràcter que pugui confondre Beancount. QuickBooks permet caràcters com & o / als noms. És aconsellable eliminar o substituir caràcters especials (p. ex., substituir & per and, eliminar barres o espais). A més, assegureu-vos que tots els noms de compte siguin únics després de la transformació: QuickBooks pot haver permès el mateix nom de subcompte sota diferents pares, la qual cosa és correcte, però a Beancount el nom complet (amb els pares) ha de ser únic. Si cal, canvieu el nom o afegiu un qualificador per distingir-los.

• Generar obertures de comptes: A Beancount, cada compte utilitzat ha de ser obert amb una directiva open. Podeu triar una data anterior a la vostra primera transacció (p. ex., si migreu dades de 2019 a 2023, utilitzeu 2018-12-31 o una data encara anterior per a totes les obertures). L'script escriurà línies com: 2018-12-31 open Assets:Checking USD 2018-12-31 open Expenses:Meals USD per a cada compte (suposant que l'USD és la moneda principal). Utilitzeu la moneda adequada per a cada compte (vegeu les notes sobre multidivisa a continuació).

Conversió de transaccions: El principal repte és convertir l'exportació de transaccions de QuickBooks (CSV) a assentaments de Beancount. Cada transacció de QuickBooks (factura, rebut, xec, assentament de diari, etc.) pot tenir múltiples partides (línies) que s'han d'agrupar en una única transacció de Beancount.

Utilitzarem el lector de CSV de Python per iterar sobre les línies exportades i acumular les partides:

import csv
from collections import defaultdict

# Llegeix totes les línies del CSV del Diari exportat de 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)

# Agrupa les línies per transacció (suposant que 'Trans #' identifica les transaccions)
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)

Ara transactions és un diccionari on cada clau és un ID/número de transacció i el valor és la llista de partides per a aquesta transacció. A continuació, convertim cada grup a Beancount:

def format_date(qb_date):
    # Les dates de QuickBooks poden ser com "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():
    # Ordena les partides per ordre de línia si cal (normalment ja vénen en ordre)
    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()
    # Capçalera de la transacció
    output_lines.append(f"{date} * \"{payee}\" \"{memo}\"")
    if first.get('Num'):  # inclou el número de referència si està disponible
        output_lines.append(f"  number: \"{first['Num']}\"")
    # Itera sobre cada partida/apunt
    for split in splits:
        acct_name = split['Account'].strip()
        # Mapeja el nom del compte de QuickBooks al compte de Beancount (utilitzant el mapeig anterior)
        beancount_acct = account_map.get(acct_name, acct_name)
        # Determina l'import amb signe:
        amount = split.get('Amount') or ""
        debit = split.get('Debit') or ""
        credit = split.get('Credit') or ""
        if amount:
            # Algunes exportacions tenen una única columna Amount (negativa per als crèdits)
            amt_str = amount
        else:
            # Si hi ha columnes Debit/Credit separades
            amt_str = debit if debit else f"-{credit}"
        # Elimina les comes dels números per seguretat
        amt_str = amt_str.replace(",", "")
        # Afegeix la moneda
        currency = split.get('Currency') or "USD"
        amt_str = f"{amt_str} {currency}"
        # Concepte/descripció de la partida
        line_memo = split.get('Memo', "").strip()
        comment = f" ; {line_memo}" if line_memo else ""
        output_lines.append(f"  {beancount_acct:<40} {amt_str}{comment}")
    # Final de la transacció – línia en blanc
    output_lines.append("")

Aquesta lògica de l'script fa el següent:

• Formata la data a YYYY-MM-DD per a Beancount.

• Utilitza el beneficiari (Name) i el concepte (Memo) per a la narració de la transacció. Per exemple: 2020-05-01 * "ACME Corp" "Pagament de factura" (Si no hi ha beneficiari, podríeu utilitzar el Tipus de transacció de QuickBooks o deixar el beneficiari entre cometes buides).

• Afegeix una metadada number si hi ha un número de referència (núm. de xec, núm. de factura, etc.).

• Itera sobre cada línia de partida:

  • Mapeja el nom del compte de QuickBooks al compte de Beancount mitjançant un diccionari account_map (poblat a partir del pas del pla de comptes).
  • Determina l'import. Depenent de la vostra exportació, podeu tenir una única columna Amount (amb valors positius/negatius) o columnes de Dèbit i Crèdit separades. El codi anterior gestiona ambdós casos. Assegura que els crèdits es representin com a imports negatius per a Beancount (ja que a Beancount s'utilitza un únic número amb signe per apunt).
  • Afegeix la moneda (suposant USD tret que hi hagi una columna de moneda diferent).
  • Escriu la línia d'apunt de Beancount amb el compte, l'import i un comentari amb el concepte de la línia. Per exemple: Assets:Checking 500.00 USD ; Dipòsit Income:Sales -500.00 USD ; Dipòsit Això reflecteix un dipòsit de $500 (d'Ingressos a Compte Corrent).

• Després de llistar totes les partides, una línia en blanc separa la transacció.

Gestió de multidivisa: Si les vostres dades de QuickBooks inclouen múltiples monedes, incloeu el codi de la moneda a cada apunt (com es mostra a dalt). Assegureu-vos que els comptes en monedes estrangeres s'obrin amb aquesta moneda. Per exemple, si teniu un compte bancari en EUR, generaríeu open Assets:Bank:Checking EUR i les transaccions en aquest compte utilitzaran EUR. Beancount admet llibres comptables multidivisa i farà un seguiment de les conversions implícites, però potser haureu d'afegir entrades de preus per als tipus de canvi si voleu la conversió a una moneda base als informes. També es recomana declarar la vostra moneda operativa principal a la part superior del fitxer de Beancount (p. ex., option "operating_currency" "USD").

Execució de la conversió: Deseu l'script de Python (per exemple, com a qb_to_beancount.py) i executeu-lo sobre els vostres fitxers exportats. Hauria de produir un fitxer .beancount que contingui tots els comptes i transaccions.

2.2 Gestió de casos especials i neteja de dades​

Durant la transformació, tingueu en compte aquests problemes comuns i com abordar-los:

• Incongruències en els noms de comptes: QuickBooks pot tenir noms de comptes que entren en conflicte amb els noms jeràrquics de Beancount. Per exemple, QuickBooks podria tenir dos comptes pare diferents, cadascun amb un subcompte anomenat "Insurance". A Beancount, Expenses:Insurance ha de ser únic. Resoleu-ho canviant el nom d'un (p. ex., "Insurance-Vehicle" vs "Insurance-Health") abans de l'exportació o mapegeu-los a comptes de Beancount únics al vostre script. Unes convencions de nomenclatura coherents (sense caràcters especials i ús de la jerarquia) us estalviaran mals de cap. Utilitzeu l'enfocament del fitxer de remapeig si cal: mantingueu un CSV o diccionari de nom antic → nom nou de Beancount i apliqueu-lo durant la conversió (el nostre codi d'exemple utilitza un account_map i podria carregar substitucions des d'un fitxer).

• Dates i formats: Assegureu-vos que totes les dates estiguin formatades de manera consistent. L'script anterior normalitza M/D/Y al format ISO. A més, aneu amb compte amb els problemes d'any fiscal vs. any natural si el vostre període de cinc anys travessa un final d'any. A Beancount no li importen els límits de l'any fiscal, però potser més endavant voldreu dividir els fitxers per any per comoditat.

• Precisió numèrica: QuickBooks gestiona la moneda amb cèntims, així que treballar en cèntims sol ser correcte. Tots els imports haurien de tenir idealment dos decimals al CSV. Si alguns imports s'han convertit en enters (sense decimals) o tenen comes/parèntesis (per als negatius), netegeu-los a l'script (elimineu comes, convertiu (100.00) a -100.00, etc.). L'exportació a CSV, si es fa correctament (segons les instruccions), ja hauria d'evitar aquests problemes de format.

• Imports negatius i signes: Els informes de QuickBooks de vegades mostren els negatius com a -100.00 o (100.00) o fins i tot --100.00 en certes exportacions d'Excel. El pas de neteja hauria de gestionar-ho. Assegureu-vos que els dèbits i crèdits de cada transacció sumin zero. Beancount ho exigirà (si no està saldat, llançarà un error en importar).

• Duplicats de transaccions: Si heu hagut d'exportar transaccions per lots (p. ex., any per any o compte per compte), aneu amb compte de fusionar-los sense solapaments. Comproveu que la primera transacció d'un any no sigui també l'última del lot anterior, etc. És fàcil duplicar accidentalment algunes transaccions a les fronteres. Si sospiteu de duplicats, podeu ordenar els assentaments finals de Beancount per data i buscar entrades idèntiques, o utilitzar les etiquetes de transacció úniques de Beancount per detectar-los. Una estratègia és incloure els números de transacció de QuickBooks com a metadades (p. ex., utilitzar el Trans # o el número de factura com a etiqueta txn o metadada quickbooks_id) i després assegurar-se que no hi hagi duplicats d'aquests ID.

• Partides no saldades / Comptes pont: QuickBooks pot tenir casos estranys com una transacció amb un desequilibri que QuickBooks ajusta automàticament a un compte de "Opening Balance Equity" o "Retained Earnings". Per exemple, en configurar els saldos inicials dels comptes, QuickBooks sovint apunta les diferències a un compte de Patrimoni Net. Aquests apareixeran a les transaccions exportades. Beancount requerirà un saldat explícit. És possible que hàgiu d'introduir un compte de Patrimoni Net per als saldos inicials (comunament Equity:Opening-Balances) per reflectir QuickBooks. És una bona pràctica tenir un assentament de saldos inicials el primer dia del vostre llibre comptable que estableixi els saldos inicials de tots els comptes (vegeu la Fase 5).

• Casos especials de multidivisa: Si utilitzeu multidivisa, l'exportació de QuickBooks pot llistar tots els imports en la moneda local o en la seva moneda nativa. Idealment, obteniu les dades en la moneda nativa de cada compte (els informes de QuickBooks Online solen fer-ho). A Beancount, cada apunt porta una moneda. Si QuickBooks va proporcionar tipus de canvi o una conversió a la moneda local, podríeu ignorar-los i confiar en les entrades de preus de Beancount. Si QuickBooks no va exportar els tipus de canvi, potser voldreu afegir manualment registres de preus (p. ex., utilitzant la directiva price de Beancount) per a dates clau per igualar la valoració. No obstant això, per a la integritat bàsica del llibre comptable, n'hi ha prou que les transaccions saldin en les seves monedes originals; els guanys/pèrdues no realitzats no necessiten ser registrats explícitament tret que vulgueu els mateixos informes.

• Comptes a cobrar / Comptes a pagar: QuickBooks fa un seguiment dels detalls de factures i rebuts (dates de venciment, estat de pagament, etc.) que no es transferiran completament a un llibre comptable pla. Obtindreu les transaccions de Comptes a Cobrar (A/R) i Comptes a Pagar (A/P) (factures que augmenten A/R, pagaments que disminueixen A/R, etc.), però no els documents de les factures ni els saldos de clients per factura. Com a resultat, després de la migració, hauríeu de verificar que els saldos dels vostres comptes A/R i A/P a Beancount siguin iguals als saldos pendents de clients/proveïdors a QuickBooks. Si necessiteu fer un seguiment de les factures, podríeu utilitzar les metadades de Beancount (p. ex., incloure una etiqueta invoice o un enllaç). Els números de factura de QuickBooks haurien d'haver arribat a través dels camps Num o Memo; el nostre script preserva el Num com a number: "..." a les metadades de la transacció.

• Comptes inactius o tancats: L'exportació IIF pot incloure comptes inactius (si heu triat incloure'ls). Està bé importar-los (simplement no tindran transaccions i un saldo zero si són realment inactius). Podeu marcar-los com a tancats a Beancount després de la data de l'última transacció amb una directiva close. Això manté el vostre llibre comptable ordenat. Per exemple: 2023-12-31 close Expenses:OldAccount ; tancat després de la migració Això és opcional i principalment per neteja.

Netejant i mapejant acuradament les dades com s'ha descrit, tindreu un fitxer de llibre comptable de Beancount que reflecteix estructuralment les vostres dades de QuickBooks. El següent pas és verificar que també reflecteix numèricament QuickBooks.

Fase 3: Validació i conciliació de dades​

La validació és una fase crítica en una migració de dades comptables. Hem d'assegurar que el llibre comptable de Beancount coincideixi amb els llibres de QuickBooks fins a l'últim cèntim. Es poden utilitzar diverses estratègies i eines:

3.1 Conciliació del balanç de comprovació​

Un informe de balanç de comprovació (o balanç de sumes i saldos) llista els saldos finals de tots els comptes (amb dèbits i crèdits o positius/negatius indicats) i hauria de sumar zero. Executar un balanç de comprovació en ambdós sistemes per a la mateixa data és la manera més ràpida de confirmar la precisió general.

• A QuickBooks: Executeu un informe de Trial Balance per a l'últim dia de l'any final (p. ex., 31 de desembre de 2023). Aquest informe mostra el saldo de cada compte. Exporteu-lo o anoteu les xifres clau.

• A Beancount: Utilitzeu els informes de Beancount per generar un balanç de comprovació. Un mètode fàcil és a través de la línia de comandes:

  bean-report migrated.beancount balances
  

  L'informe balances és un balanç de comprovació que llista tots els comptes i els seus saldos. També podeu obrir el fitxer a Fava (la interfície web de Beancount) i mirar la secció Balances o Balance Sheet. Cada saldo de compte a Beancount hauria de coincidir amb el balanç de comprovació de QuickBooks. Per exemple, si QuickBooks mostra *Comptes a cobrar = $5.000*, llavors el compte Assets:Accounts Receivable de Beancount hauria de sumar$5.000 (dèbit). Si *Ingressos per vendes = $200.000*, el compte Income:Sales a Beancount hauria de mostrar$200.000 (crèdit, que podria aparèixer com a -200.000 si s'utilitza un balanç de comprovació que presenta els crèdits com a negatius).

Si hi ha discrepàncies, localitzeu-les:

• Comproveu si falta o sobra un compte sencer (hem oblidat un compte o n'hem inclòs un que ja estava tancat abans del període de migració?).
• Si un saldo no quadra, aprofundiu: QuickBooks pot executar un Account QuickReport o un detall de llibre major per a aquest compte, i podeu comparar-lo amb el registre de Beancount per a aquest compte (bean-report migrated.beancount register -a NomDelCompte). De vegades, les diferències provenen d'una transacció que falta o d'un duplicat.

Verifiqueu també que la suma de tots els comptes sigui zero al balanç de comprovació de Beancount (imprimeix un total que hauria de ser zero o molt proper a zero). Beancount aplica la partida doble, així que si teniu algun desequilibri diferent de zero, significa que actius menys passius i patrimoni net no sumen zero, la qual cosa indica un problema (que QuickBooks normalment tampoc permetria, però podria passar si es van perdre algunes dades).

3.2 Comparacions de saldos de comptes​

Més enllà del balanç de comprovació, podeu comparar estats financers específics:

• Balanç de situació: Executeu un Balanç de Situació de QuickBooks per a la data final i un balanç de situació de Beancount (bean-report migrated.beancount balsheet). Això és similar al balanç de comprovació però organitzat per Actius, Passius i Patrimoni Net. Els números haurien de coincidir per categories. Per a una comprovació més granular, compareu els totals dels comptes principals: tresoreria, comptes a cobrar, actius fixos, comptes a pagar, patrimoni net, etc.

• Compte de pèrdues i guanys (Compte de resultats): Executeu un Compte de Pèrdues i Guanys per al període de cinc anys (o any per any) a QuickBooks i a Beancount (bean-report migrated.beancount income per a un compte de resultats del període complet). El resultat net de Beancount hauria de ser igual al de QuickBooks per a cada període. Si heu migrat els cinc anys, el resultat net acumulat hauria de coincidir. També podeu comparar els totals d'ingressos i despeses individuals per assegurar-vos que no s'ha omès o duplicat cap categoria.

• Mostreig aleatori de transaccions: Trieu algunes transaccions a l'atzar (especialment de cada any i de cada compte principal) i verifiqueu que s'han migrat correctament. Per exemple, trobeu una factura de fa 3 anys a QuickBooks i després cerqueu el seu import o concepte al fitxer de Beancount (com que totes les transaccions són text, podeu obrir el fitxer .beancount en un editor de text o utilitzar eines de cerca). Comproveu que la data, els imports i els comptes coincideixin. Això ajuda a detectar problemes de format de data o comptes mal mapejats.

3.3 Comprovacions d'integritat automatitzades​

Aprofiteu les eines de validació pròpies de Beancount:

• bean-check: Executeu bean-check migrated.beancount. Això analitzarà el fitxer i informarà de qualsevol error de sintaxi o de saldat. Si l'script va ometre alguna cosa com un compte no obert o una transacció no saldada, bean-check ho marcarà. Una passada neta (sense sortida) significa que el fitxer és, com a mínim, internament consistent.

• Assercions de saldo: Podeu afegir assercions de saldo explícites al llibre comptable per a comptes clau com a comprovació addicional. Per exemple, si sabeu el saldo del compte bancari en una data determinada, afegiu una línia: 2023-12-31 balance Assets:Bank:Checking 10000.00 USD Aleshores, bean-check s'assegurarà que al llibre comptable, en aquesta data, el saldo sigui efectivament de $10.000. Això és opcional però pot ser útil per a comptes de gran importància. Podríeu agafar els saldos finals de QuickBooks (p. ex., al final de cada any) i afirmar-los al fitxer de Beancount. Si alguna asserció falla, Beancount informarà d'una diferència.

• Conciliació progressiva del balanç de comprovació: Si ho preferiu, podeu fer una comprovació període per període. Per a cada any, compareu el canvi net. Per exemple, el resultat net a QuickBooks 2020 vs. Beancount 2020, etc., per assegurar-vos que cada any es va tancar correctament contra el patrimoni net (QuickBooks traspassa automàticament el resultat net a Reserves cada nou any; a Beancount simplement veureu el patrimoni net acumulat). Si veieu diferències, pot indicar un problema a les dades d'un any específic.

• Recompte de transaccions i duplicats: Compteu el nombre de transaccions a QuickBooks vs. Beancount. QuickBooks no mostra un recompte directe fàcilment, però podeu estimar-lo comptant les línies al CSV (cada capçalera de transacció vs. les partides). A Beancount, una manera ràpida és comptar les ocurrències de txn o * " al fitxer. Haurien de ser iguals o lleugerament superiors a les de QuickBooks (si heu afegit transaccions de saldos inicials o ajustos). Una diferència significativa significa que alguna cosa podria haver estat omesa o duplicada. El nostre ús d'ID únics a les metadades pot ajudar: si sospiteu de duplicats, cerqueu al fitxer de Beancount el mateix número de xec o de factura que apareix dues vegades quan no hauria de fer-ho.

• Estat de conciliació: Vam incloure una metadada rec: "y" o "n" basada en l'estat de conciliat de QuickBooks al nostre script (com a rec a l'exemple). Això no és una característica estàndard de Beancount (Beancount no fa un seguiment de pendent/conciliat de la mateixa manera que Ledger), però pot ser una metadada útil. Podríeu verificar que totes les transaccions que estaven conciliades a QuickBooks hi són presents. En última instància, conciliar de nou els comptes bancaris a Beancount (utilitzant els vostres extractes) podria ser la prova final que no falta res.

Fent aquestes validacions, guanyareu confiança que la migració ha preservat les dades. Preneu-vos el vostre temps en aquesta fase: és més fàcil solucionar anomalies ara que mesos després, quan es podria confiar en els llibres. Problemes comuns si la validació falla: un saldo inicial de compte que falta, una transacció datada fora del rang o una inversió de signe en un apunt. Tots són solucionables un cop identificats.

Fase 4: Consolidació al llibre comptable de Beancount​

Després de netejar i validar, és hora de formalitzar les dades a l'estructura del vostre llibre comptable de Beancount. "Consolidar" aquí significa tant finalitzar els fitxers del llibre comptable com, potencialment, registrar-los en un sistema de control de versions per a l'auditoria.

4.1 Organització dels fitxers i configuració del llibre comptable​

Decidiu com estructurar els fitxers del llibre comptable de Beancount. Per a cinc anys de dades, podeu mantenir-ho tot en un sol fitxer o dividir-ho per any o categoria. Una estructura comuna i clara és:

• Fitxer principal del llibre comptable: p. ex., ledger.beancount – Aquest és el punt d'entrada que pot fer include d'altres fitxers. Podria contenir opcions globals i després incloure els fitxers anuals.
• Fitxer de comptes: Definiu el pla de comptes i els saldos inicials. Per exemple, accounts.beancount amb totes les directives open (generades per l'script). També podríeu llistar les mercaderies (monedes) aquí.
• Fitxers de transaccions: Un per any, p. ex., 2019.beancount, 2020.beancount, etc., contenint les transaccions d'aquell any. Això manté cada fitxer amb una mida manejable i us permet centrar-vos en un any si cal. Alternativament, podeu dividir per entitat o compte, però la divisió per temps és senzilla per a dades financeres.

Exemple de fitxer principal:

option "title" "El meu llibre comptable d'empresa"
option "operating_currency" "USD"

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

D'aquesta manera, totes les dades s'agreguen quan executeu informes, però manteniu l'ordre.

Beancount no requereix múltiples fitxers —podríeu tenir un sol fitxer gran— però l'estructura anterior millora la claredat i el control de versions. Segons les millors pràctiques de Beancount, és bo utilitzar capçaleres de secció clares i agrupar les entrades relacionades de manera lògica.

4.2 Establiment de saldos inicials i patrimoni net​

Si la vostra migració no parteix d'un inici absolutament des de zero, haureu de gestionar els saldos inicials. Dos escenaris:

• Llibres que comencen de zero: Si el període de cinc anys comença a la creació de l'empresa (p. ex., vau començar a utilitzar QuickBooks el gener de 2019 amb tots els comptes a zero excepte el patrimoni inicial), llavors potser no necessiteu una transacció de saldos inicials separada. Les primeres transaccions del 2019 (com el finançament inicial a un compte bancari) establiran naturalment els saldos inicials. Només assegureu-vos que qualsevol capital inicial o reserves anteriors es comptabilitzin mitjançant transaccions de patrimoni net.

• Llibres a mig camí (historial parcial): Si vau començar amb QuickBooks abans i el 2019 és un punt intermedi, llavors a l'1 de gener de 2019 cada compte tenia un saldo que venia de l'exercici anterior. QuickBooks tindria aquests saldos com a saldos d'obertura o reserves. A Beancount, és típic crear un assentament de Saldos Inicials el dia abans de la vostra data d'inici:

  • Utilitzeu un compte de patrimoni anomenat Equity:Opening-Balances (o similar) per compensar la suma de tots els imports inicials.
  • Exemple: si el 31/12/2018, la Tresoreria era de $10.000, els Comptes a Cobrar de$5.000 i els Comptes a Pagar de $3.000 (crèdit), escriuríeu una transacció: `2018-12-31 * "Saldos Inicials"` ` Assets:Cash 10000.00 USD ` ` Assets:Accounts Receivable 5000.00 USD ` ` Liabilities:Accounts Payable -3000.00 USD ` ` Equity:Opening-Balances -12000.00 USD ` Això deixa Opening-Balances amb la suma negativa (–$12k) que salda l'assentament. Ara tots els comptes d'actiu/passiu comencen el 2019 amb els saldos correctes. Això hauria de reflectir qualsevol "Reserva" o saldos arrossegats de QuickBooks.
  • Alternativament, utilitzeu les directives pad i balance de Beancount: Per a cada compte, podeu fer-li pad des de Opening-Balances i afirmar el saldo. Aquesta és una manera més automatitzada. Per exemple: 2018-12-31 pad Assets:Cash Equity:Opening-Balances 2018-12-31 balance Assets:Cash 10000.00 USD Això diu a Beancount que insereixi qualsevol assentament necessari (a Opening-Balances) perquè Tresoreria sigui igual a 10000 USD en aquesta data. Feu això per a cada compte. El resultat és similar, però escriure una transacció explícita com en el primer mètode també és senzill.

• Reserves (Retained Earnings): QuickBooks no exporta explícitament una transacció de "Reserves"; simplement la calcula. Després de la migració, potser noteu que Equity:Retained Earnings és zero si no el vau crear. A Beancount, les reserves són simplement els beneficis d'anys anteriors. Podeu optar per crear un compte de Reserves i transferir-hi els beneficis anteriors el primer dia de cada nou any, o simplement deixar que el patrimoni net sigui la suma de tots els ingressos/despeses (que apareix a la secció de Patrimoni Net als informes). Per transparència, alguns usuaris fan assentaments de tancament anuals. Això és opcional i principalment per a la presentació. Com que hem migrat totes les transaccions, el benefici de cada any s'acumularà naturalment si executeu un informe per any.

• Comprovacions comparatives: Després d'establir els saldos inicials, executeu un balanç de situació a la data d'inici per assegurar-vos que tot és correcte (hauria de mostrar aquests saldos inicials contra el Patrimoni Inicial sumant zero).

4.3 Finalització i control de versions​

Ara que les dades estan en format Beancount i estructurades, és aconsellable consolidar els fitxers en un repositori de control de versions (p. ex., git). Cada canvi al llibre comptable es pot seguir, i teniu un rastre d'auditoria de totes les modificacions. Aquest és un avantatge important de la comptabilitat en text pla. Per exemple, a QuickBooks els canvis poden no ser fàcilment comparables, però a Beancount podeu veure les diferències línia per línia. Com alguns usuaris assenyalen, amb Beancount obteniu transparència i la capacitat de revertir canvis si cal: cada assentament es pot vincular a un historial de canvis.

Considereu etiquetar el commit d'aquesta migració inicial com a v1.0 o similar, perquè sapigueu que representa l'estat dels llibres tal com es van importar de QuickBooks. A partir d'ara, introduireu noves transaccions directament a Beancount (o les importareu de fonts bancàries, etc.), i podeu utilitzar pràctiques normals de desenvolupament de programari (fent commits mensuals o diaris, utilitzant branques per a experiments, etc.).

Configuració de Fava o altres eines: Fava és una interfície web per a Beancount que facilita la visualització d'informes. Després de consolidar, executeu fava ledger.beancount per navegar pels estats financers i comparar-los amb els vostres informes de QuickBooks una última vegada. Podríeu detectar petites diferències més fàcilment en una interfície gràfica (per exemple, un compte que hauria de ser zero però que mostra un petit saldo indica un assentament de tancament que falta o una transacció perduda).

Convencions de nomenclatura i consistència: Ara teniu el control total, així que assegureu-vos de la consistència:

• Tots els comptes han de tenir noms clars, començant amb noms de categoria en majúscula (Assets, Liabilities, etc.). Si algun sembla estrany (p. ex., Assets:assets:SomeAccount a causa d'una diferència de majúscules/minúscules de QuickBooks), canvieu-los el nom al fitxer de comptes i actualitzeu les transaccions (una cerca/substitució ràpida al fitxer pot fer-ho, o utilitzar bean-format de Beancount o el multicursor de l'editor).
• Els símbols de mercaderia (codis de moneda) han de ser consistents. Per a USD, utilitzeu USD a tot arreu (no $ o US$). Per a altres, utilitzeu codis estàndard (EUR, GBP, etc.). Aquesta consistència és important per a les cerques de preus i els informes de Beancount.
• Elimineu qualsevol compte temporal o de prova que s'hagi pogut crear (per exemple, si heu utilitzat Expenses:Miscellaneous per a comptes desconeguts a l'script com a comodí, intenteu eliminar-los mapejant correctament tots els comptes).

Tancament de QuickBooks: En aquest punt, hauríeu de tenir llibres paral·lels a Beancount que coincideixin amb QuickBooks. Alguns opten per executar ambdós sistemes en paral·lel durant un període curt per assegurar-se que no s'ha omès res. Però si la validació és sòlida, podeu "tancar" els llibres de QuickBooks:

• Si es tracta d'un entorn corporatiu, considereu exportar tots els documents font de QuickBooks (factures, rebuts) per als registres, ja que aquests no existiran a Beancount tret que els adjunteu manualment.
• Conserveu una còpia de seguretat de les dades de QuickBooks (tant el fitxer de l'empresa com els fitxers d'exportació).
• A partir d'ara, mantingueu el llibre comptable de Beancount com el sistema de registre principal.

En consolidar les dades al llibre comptable de Beancount, heu completat el procés de migració. El pas final és realitzar una auditoria i demostrar la consistència dels estats financers, per satisfer-vos a vosaltres mateixos (i a qualsevol part interessada o auditor) que la migració ha estat un èxit.

Fase 5: Auditoria postmigració i exemples​

Per il·lustrar l'èxit de la migració, prepareu una comparació abans i després dels estats financers i, possiblement, una diferència de transaccions. Això proporciona proves que els llibres són consistents.

5.1 Verificació dels estats financers​

Produïu informes financers clau tant de QuickBooks com de Beancount per a les mateixes dates i compareu-los:

• Balanç de situació a 31 de desembre de 2023: Compareu els totals d'Actius, Passius i Patrimoni Net línia per línia. Haurien de coincidir. Per exemple, si QuickBooks mostrava Total Actius = $150.000** i **Total Passius + Patrimoni Net =$150.000, el balanç de situació de Beancount hauria de mostrar els mateixos totals. Si heu estructurat els comptes de manera lleugerament diferent (diguem que heu fusionat alguns subcomptes), ajusteu-ho en la comparació o desglosseu fins al següent nivell per assegurar-vos que les sumes siguin iguals.

• Compte de pèrdues i guanys 2019–2023: Assegureu-vos que el total d'Ingressos, el total de Despeses i el Benefici Net de cada any (o de tot el rang) siguin idèntics. Podrien sorgir diferències menors si QuickBooks va fer algun arrodoniment als informes, però les transaccions normalment porten els cèntims exactament, de manera que el benefici net hauria de ser exacte. Si el benefici d'algun any difereix, aprofundiu en les dades d'aquell any; sovint és un indicador d'un assentament que falta o duplicat en aquell període.

• Diferències en el balanç de comprovació: Si és possible, creeu un full de càlcul on llisteu cada compte i el saldo de QuickBooks vs. Beancount. Com que esperem que coincideixin, aquesta hauria de ser una columna de diferències tot a zero. Això és essencialment la comprovació creuada del balanç de comprovació que vam discutir, però escriure-ho ajuda a documentar-ho.

5.2 Exemple de comparació (Abans vs. Després)​

A continuació es mostra un fragment d'exemple que demostra la consistència de les dades. Diguem que el nostre balanç de comprovació de QuickBooks per al 31 de desembre de 2023 era:

A Beancount, després d'importar i registrar totes les transaccions fins al 2023, un bean-report balances (balanç de comprovació) mostra:

(Nota: les seccions de Patrimoni Net poden estar estructurades de manera diferent; la clau és que els totals coincideixin. Aquí, "Benefici (2019-2023)" a Beancount fa el paper del benefici de l'any actual/reserves combinades, mostrant zero perquè el benefici es va tancar contra Reserves.)

Com es mostra, cada compte coincideix fins al cèntim. La suma dels dèbits és igual a la suma dels crèdits a banda i banda.

A més, si executem un Compte de Pèrdues i Guanys per al 2023:

• QuickBooks: Ingressos $50.000, Despeses$48.000, Benefici Net $2.000.
• Beancount: Ingressos $50.000, Despeses$48.000, Benefici Net $2.000 (que després es va tancar a Reserves o apareix sota Patrimoni Net al balanç de final d'any).

Podeu crear una diferència de transaccions si cal, però com que les dades de QuickBooks no estan en format de llibre comptable, és més efectiu confiar en els informes. Es podria ordenar tant el CSV de QuickBooks com les transaccions de Beancount per data i comparar camps clau com a comprovació final (això es pot fer a Excel o amb un script). No obstant això, donat que confiem en la nostra validació anterior, la comprovació dels estats financers sol ser suficient.

5.3 Consells d'auditoria​

• Si un auditor o una part interessada necessita tranquil·litat, presenteu els estats financers abans i després un al costat de l'altre. La transparència de Beancount pot simplificar les auditories perquè podeu rastrejar cada número d'un estat financer fins a l'assentament original ràpidament (especialment utilitzant la funcionalitat de desglossament de Fava).
• Conserveu la còpia de seguretat de QuickBooks i els CSV exportats com a part del vostre rastre d'auditoria. Documenteu qualsevol ajust fet durant la migració (per exemple, "S'ha canviat el nom del compte X a Y per coherència" o "S'ha dividit la transacció Z en dos assentaments per claredat" si vau fer aquests canvis).
• A partir d'ara, implementeu comprovacions regulars a Beancount. Per exemple, la conciliació mensual dels comptes bancaris i una asserció del seu saldo final ajuda a detectar qualsevol problema de dades o error en l'entrada. La migració ofereix una bona base; mantenir la disciplina en el nou sistema garantirà la precisió contínua.

Finalment, celebreu la finalització de la migració: heu transferit amb èxit cinc anys de dades comptables de QuickBooks a Beancount. Les dades es troben ara en un format de text lleuger, amb control de versions i amb integritat total de partida doble. Heu exportat les dades, les heu transformat amb scripts de Python, heu validat la integritat mitjançant balanços de comprovació i informes, i les heu consolidat en un llibre comptable de Beancount ben organitzat. Aquest procés exhaustiu assegura que el llibre comptable de Beancount sigui una rèplica precisa i fidel dels vostres llibres de QuickBooks durant el període de cinc anys, preparant-vos per a una comptabilitat simplificada en el futur.

Resum de l'incident​

El 2021-08-03 a les 14:35 PST, un dels nostres enginyers va realitzar una migració de base de dades incorrecta que va causar discrepàncies entre les dades indexades i la font de veritat a la base de dades. Va afectar 39 usuaris, i vam restaurar les dades i vam resoldre el problema a les 16:46 PST.

Impacte​

Aquests 39 usuaris afectats podrien perdre dades afegides entre el 2021-08-03 a les 14:35 PST i les 16:46 PST. Vam restaurar les dades, però no podem garantir una recuperació del 100%.

Causa arrel​

La causa arrel és la nostra nova migració de base de dades per reorganitzar l'estructura de fitxers i preparar la integració amb Dropbox. Malauradament, vam subestimar el nombre d'usuaris que visitaven aquest servei durant el desplegament.

Lliçons apreses​

La pròxima vegada, en situacions similars, farem el següent:

1. Ser més prudents amb la migració de la base de dades. Ser conscients que hi ha insercions de dades durant la migració.
2. Posar el lloc en mode de manteniment quan necessitem aturar tot el trànsit i les condicions de competició.