Importer un CSV bancaire dans Beancount avec bea

Un CSV bancaire ordinaire n'a pas besoin d'un importateur Python. Mettez en correspondance ses colonnes avec --csv, nommez le compte source avec --account, catégorisez les lignes avec --rules, puis prévisualisez et appliquez les écritures avec bea import.

Vous avez besoin d’un grand livre existant. Si vous commencez un nouveau livre, suivez le démarrage rapide CLI. Gardez l’export bancaire original pour pouvoir le comparer avec la prévisualisation.

1. Associer les colonnes CSV​

Sauvegardez cet exemple sous le nom statement.csv, puis exécutez les commandes ci-dessous depuis le même répertoire :

Date,Payee,Narration,Amount
2026-08-02,Whole Foods,groceries,-20.00
2026-08-03,Shell,gas,-40.00
2026-08-04,Unknown Shop,mystery,-9.99

Les montants utilisent la convention de signe bancaire : une dépense est négative et un dépôt est positif. La devise par défaut est celle du grand livre, donc ce fichier n'a pas besoin de colonne de devise. Mettez une colonne de description bancaire dans narration et gardez payee pour le commerçant.

Créez le grand livre et ouvrez le sous-compte carburant utilisé ci-dessous :

bea --no-input init books --currency USD --date 2026-08-01 \
  --opening-balance "Assets:Checking 1000"
bea --file books/main.bean add open --date 2026-08-01 --account Expenses:Transport:Fuel -c USD

Le modèle ouvre déjà Expenses:Groceries et les autres comptes courants. Il n'ouvre pas Expenses:Transport:Fuel, donc la seconde commande l’ouvre avant l’importation. Les options globales telles que --file se placent avant la sous-commande.

2. Prévisualiser les écritures​

Sauvegardez ces règles de catégorisation sous rules.toml, puis prévisualisez :

cat > rules.toml <<'EOF'
[[rule]]
match = "whole foods|trader joe|corner market"
account = "Expenses:Groceries"
 
[[rule]]
match = "shell|chevron|exxon"
account = "Expenses:Transport:Fuel"
EOF
bea --file books/main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee,narration=Narration --account Assets:Checking --rules rules.toml

Les règles correspondent d'abord au bénéficiaire, puis à la narration, en ignorant la casse. La première règle correspondante est retenue. Les lignes sans règle correspondante sont postées vers Expenses:Uncategorized avec le drapeau ! pour une revue ultérieure. Le guide produit IMPORTING documente la référence complète de correspondance, incluant la paire debit et credit, la colonne category, et la lecture des en-têtes --csv auto.

Rien n'est encore écrit dans le grand livre. La prévisualisation rapporte 3 ready, 0 exact duplicates, 0 possible duplicates et s’arrête avec le code 0. Sa colonne RULE nomme le motif gagnant par ligne, ou unmatched pour la ligne Unknown Shop. Vérifiez les dates, bénéficiaires, montants sources signés, comptes de destination, correspondances en double, et la proposition de différence de fichier. Corrigez une règle ou catégorie incorrecte, puis prévisualisez à nouveau. Ouvrez tous les comptes manquants avant d’appliquer l’import : une règle nommant un compte non ouvert par le grand livre échoue la validation.

3. Appliquer les écritures révisées​

bea --file books/main.bean import statement.csv --apply
bea --file books/main.bean check
bea --file books/main.bean list transaction --flag '!'
bea --file books/main.bean query "SELECT account, sum(position) WHERE account = 'Assets:Checking' GROUP BY account"

La correspondance des colonnes est mémorisée par grand livre, ligne d'en-tête et compte source, donc --apply est relancé sans options et rapporte en utilisant la correspondance des colonnes mémorisée. Il recalcule l'aperçu par rapport aux fichiers actuels, valide le grand livre candidat complet avant d'écrire, et écrit 3 écritures. bea check ne signale aucune erreur. La file d'attente ! liste la seule ligne non appariée : Unknown Shop avec mystery à -9.99 USD. Un contrôle réussi prouve seulement que le grand livre est équilibré et validé. Cela ne dit rien quant à savoir si cette ligne appartient à Expenses:Uncategorized, recatégorisez-la donc délibérément dans votre grand livre. Le contrôle s'arrête à 930.01 USD : le solde d'ouverture 1,000 USD moins 69.99 USD de dépenses.

4. Les importations répétées n’ajoutent rien​

bea --file books/main.bean import statement.csv --apply

L'aperçu rapporte 0 ready, 3 exact duplicates, et l'exécution écrit 0 écritures avec sortie 0. Chaque ligne écrite porte les métadonnées import-id avec un hachage de contenu, donc le fichier identique correspond à chaque ligne. Conservez ces métadonnées lors de la modification des écritures importées. L'importation ajoute des écritures ; elle ne met pas à jour et ne supprime pas une transaction existante. Apportez les corrections délibérément dans votre grand livre puis exécutez bea check ensuite. L’entrée JSON en masse avec bea add transactions ne détecte pas les doublons.

5. Résoudre les doublons possibles​

Un téléchargement ultérieur peut répéter une ligne avec une narration différente ou des identifiants bancaires différents. La date, le bénéficiaire normalisé et le montant source signé restent des indicateurs d’une correspondance possible :

Un ID bancaire différent n'exclut pas un doublon. Les banques peuvent changer d’ID lors de téléchargements ultérieurs. Deux achats réels peuvent aussi partager une date, un bénéficiaire et un montant, donc une correspondance possible est une preuve mais pas une certitude. Bea ne devine pas avec un modèle d’IA et ne catégorise jamais pour vous au-delà de vos règles.

Le --duplicates review par défaut refuse d'appliquer les correspondances non résolues. Lors d'une exécution de vérification, un second fichier répétant la ligne 2026-08-02 Whole Foods -20.00 USD sous une narration différente a été prévisualisé comme 1 doublon possible, et --apply s'est terminé avec 4 rien d'écrit. Après avoir examiné toutes les correspondances possibles, choisissez une de ces alternatives :

bea --file books/main.bean import statement.csv --apply --duplicates skip
bea --file books/main.bean import statement.csv --apply --duplicates include

Choisissez include pour préserver les achats répétés légitimes. La décision s'applique à toutes les correspondances possibles dans cette invocation. Les doublons exacts restent ignorés. Les conflits d'ID bloquent toujours l'écriture. --no-input et --yes ne contournent pas cette revue. Une décision intentionnelle d'ignorer chaque ligne se termine avec 0 sans ajouts au grand livre.

6. Utiliser un importateur Python pour d'autres formats​

Pour les formats que le mappage des colonnes ne peut exprimer, tels que OFX, QIF ou un CSV avec une disposition inhabituelle, bea import appelle un importateur configuré utilisant l'interface actuelle de Beangulp : identify(filepath), account(filepath) et extract(filepath, existing). L'importateur gère l'analyse et la catégorisation spécifiques à la banque. Il doit fournir des montants explicites sur les écritures du compte source afin que la correspondance des doublons utilise les montants bancaires réels. Un importateur Python reste la voie avancée pour ces formats. Pour un CSV natif d'une banque, essayez d'abord --csv.

Pour un premier essai pratique, enregistrez la configuration CSV catégorisée d'exemple sous importers.py à côté de votre grand livre racine. Elle utilise uniquement Beancount et la bibliothèque standard Python, donc elle fonctionne avec l'installation Homebrew. Son exemple bank.csv utilise un montant de compte-chèques signé : une dépense de restauration -5.25 USD et un dépôt de salaire 1,000 USD. La configuration d'exemple attend exactement ses colonnes documentées. N'exécutez que des configurations Python en lesquelles vous avez confiance.

bea --file books/main.bean import bank.csv --config importers.py
bea --file books/main.bean import bank.csv --config importers.py --importer categorized-checking
bea --file books/main.bean import bank.csv --config importers.py --apply

Votre configuration importers.py exporte CONFIG = [importer, ...]. Si plusieurs importateurs reconnaissent le fichier, sélectionnez-en un par son nom. Un nom inconnu liste les noms configurés. Un importateur connu qui ne reconnaît pas le fichier le signale séparément.

L'interface CLI mémorise le chemin de configuration pour ce grand livre racine. Les futures exécutions choisissent le --config explicite, puis le chemin mémorisé, puis importers.py à côté de la racine. La sortie nomme le chemin et sa provenance.

--apply recalculates l'aperçu en fonction des fichiers actuels. Il valide le grand livre candidat complet avant d'écrire. Un échec de validation laisse le grand livre original inchangé et retourne 1. Une modification concurrente du grand livre retourne 4 ; inspectez la modification et lancez un nouvel aperçu avant de réessayer.

Garder les importations répétables​

Par défaut, la détection des doublons vérifie la métadonnée bank_id, fitid, transaction_id et imported_id dans le compte source de l'importateur. Utilisez des options --id-key KEY répétées pour remplacer cet ensemble.

Une ligne avec un ID bancaire stable est écrite avec des métadonnées import-id désignant son type, telles qu'un préfixe bank: ou ofx:. Une ligne sans ID est écrite avec un hash de contenu csv:sha256: sur sa date, son montant, sa description et son compte, ainsi la réimportation du même fichier ignore chaque ligne. Les entrées écrites avant cette convention peuvent toujours contenir des métadonnées bea_import_id, qui sont toujours utilisées pour la correspondance à la réimportation. Les correspondances possibles sont vérifiées par rapport aux transactions existantes et aux lignes acceptées dans le même lot.

Les bénéficiaires, narrations et métadonnées de type chaîne remplacent les sauts de ligne par des espaces avant l'aperçu et l'écriture. Les guillemets et antislashs conservent leur contenu. Le texte marchand importé reste ainsi lisible sur une seule ligne du grand livre.

Écrire dans un fichier inclus​

Gardez --file pointant vers la racine et sélectionnez la destination avec --into :

bea --file books/main.bean import statement.csv --into 2026.bean
bea --file books/main.bean import statement.csv --into 2026.bean --apply

2026.bean doit déjà exister et être inclus par la racine. Son chemin est relatif au répertoire racine. Le chemin d'export reste relatif à votre répertoire de travail. L'aperçu identifie le fichier qui sera modifié.

Utiliser les importations dans un script​

bea --file books/main.bean --json --no-input import statement.csv --apply --duplicates skip

Choisissez skip uniquement si c'est votre politique voulue pour les correspondances possibles. JSON renvoie l'aperçu et le compte d'écriture dans data. Les applications refusées placent l'aperçu dans error.result sur stderr, avec written: 0. Vérifiez toujours le statut de sortie. Consultez la référence JSON et code de sortie avant de planifier des importations sans surveillance.

Dépannage d'un importateur​

Les configurations d'importateur s'exécutent dans le moteur géré. Si une configuration importe Beangulp, installez la bibliothèque système libmagic et activez Beangulp une fois là-bas :

bea engine enable beangulp
bea --file books/main.bean import bank.ofx --config importers.py
bea --debug --file books/main.bean import bank.csv --config importers.py

bea engine status rapporte les fonctionnalités activées. L'installation d'un importateur bancaire avec le frontend bea ne le rend pas disponible dans le moteur. Une configuration qui importe des packages supplémentaires a besoin de ces dépendances dans le moteur ; activer Beangulp seul ne les installe pas. Utilisez le mappeur CSV ou les convertisseurs ci-dessous lorsque ces dépendances d'importateur ne sont pas disponibles.

Pour une exception d'importateur, placez --debug avant la commande pour afficher sa trace. La sortie de l'importateur est capturée dans importer_output afin de ne pas corrompre le JSON. En mode débogage JSON, la trace est error.traceback.

Pour une conversion ponctuelle sans importateur Python, essayez le convertisseur CSV ou le convertisseur OFX et QIF. Vérifiez les entrées générées avant de les ajouter à vos livres.