Importer des exports bancaires avec la CLI

Utilisez bea import pour prévisualiser un export bancaire, examiner les doublons et ajouter les entrées validées à votre registre local.

Vous avez besoin d'un registre existant et d'un importateur Python pour le format exact d'export de votre banque. Si vous commencez une nouvelle comptabilité, suivez le démarrage rapide CLI. Conservez l'export bancaire original afin de pouvoir le comparer avec la prévisualisation.

1. Choisir un importateur​

Un importateur lit le fichier de la banque et fournit les comptes de transaction. Bea ne devine pas le format et ne catégorise pas les achats avec un modèle d'IA.

Votre configuration importers.py exporte CONFIG = [importer, ...]. Les importateurs utilisent l'interface Beangulp actuelle : identify(filepath), account(filepath) et extract(filepath, existing). Les écritures du compte source nécessitent des montants explicites pour la correspondance des doublons.

Pour un premier essai pratique, enregistrez la configuration CSV catégorisée d'exemple comme importers.py à côté de votre registre racine. Elle n'utilise que Beancount et la bibliothèque standard de Python, elle fonctionne donc avec l'installation Homebrew.

Enregistrez cet échantillon comme bank.csv dans le même répertoire :

Date,Payee,Narration,Amount,Currency,Category,BankID
2026-08-02,Cafe,Coffee,-5.25,USD,Expenses:Dining,bank-001
2026-08-03,Employer,Salary,1000,USD,Income:Salary,bank-002

L'échantillon utilise un montant signé pour le compte courant : les dépenses sont négatives et un dépôt est positif. Category fournit l'autre compte. Les deux catégories sont dans le modèle USD créé par bea init.

Utilisez un importateur écrit pour votre banque lors de l'importation de son CSV, OFX ou QIF natif. La configuration d'exemple attend exactement les colonnes ci-dessus. N'exécutez que des configurations Python en lesquelles vous avez confiance.

2. Prévisualiser les entrées​

Exécutez ceci depuis le répertoire contenant main.bean :

bea import bank.csv --config importers.py

Rien n'est encore écrit dans le registre. Examinez les dates, les bénéficiaires, les montants sources signés, les comptes de destination, les correspondances en double et le diff de fichier proposé dans la prévisualisation.

Pour l'échantillon, la prévisualisation doit contenir une dépense de restauration de 5,25 USD et un dépôt de salaire de 1 000 USD. Corrigez une catégorie incorrecte dans l'importateur ou les données sources, puis prévisualisez à nouveau. Ouvrez les comptes manquants avant d'appliquer l'importation.

Si plusieurs importateurs reconnaissent le fichier, sélectionnez-en un par son nom :

bea import bank.csv --config importers.py --importer categorized-checking

Un nom inconnu liste les noms configurés. Un importateur connu qui ne reconnaît pas le fichier le signale séparément.

3. Appliquer les entrées examinées​

bea import bank.csv --apply
bea check
bea list transaction --limit 10

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

--apply recalcule la prévisualisation par rapport aux fichiers actuels. Il valide le registre candidat complet avant d'écrire. Un échec de validation laisse le registre original inchangé et quitte avec le code 1. Une modification concurrente du registre quitte avec le code 4 ; examinez la modification et lancez une nouvelle prévisualisation avant de réessayer.

4. Résoudre les doublons possibles​

Répéter la même importation d'échantillon ignore ses entrées existantes. Un export qui se chevauche peut également contenir des lignes nécessitant une décision :

Un identifiant bancaire différent n'exclut pas un doublon. Les banques peuvent modifier les identifiants lors de téléchargements ultérieurs. Deux achats réels peuvent aussi partager une date, un bénéficiaire et un montant.

Après avoir examiné chaque correspondance possible, choisissez l'une de ces alternatives :

bea import bank.csv --apply --duplicates skip

bea import bank.csv --apply --duplicates include

La décision s'applique à toutes les correspondances possibles de cette invocation. Les doublons exacts restent ignorés. Les conflits d'identifiants bloquent toujours l'écriture.

Le --duplicates review par défaut refuse d'appliquer les correspondances non résolues. Il quitte avec le code 4 et nomme les lignes de prévisualisation concernées. --no-input et --yes ne contournent pas cet examen. Une décision intentionnelle d'ignorer chaque ligne quitte avec le code 0 sans ajout au registre.

Rendre les importations reproductibles​

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

La CLI écrit également des métadonnées bea_import_id pour identifier la ligne dans l'export original. Conservez-les lors de la modification des entrées importées. Les correspondances possibles sont vérifiées par rapport aux transactions existantes et aux lignes acceptées du même lot.

Les bénéficiaires, les narrations et les métadonnées de chaîne remplacent les sauts de ligne par des espaces avant la prévisualisation et l'écriture. Les guillemets et les barres obliques inversées conservent leur contenu. Le texte marchand importé reste donc lisible sur une seule ligne du registre.

L'importation ajoute des entrées ; elle ne met pas à jour ni ne supprime une transaction existante. Effectuez les corrections délibérément dans votre registre et exécutez bea check ensuite. L'ajout groupé d'entrées JSON avec bea add transactions ne comporte pas de détection des doublons.

Écrire dans un fichier inclus​

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

bea --file ~/my-books/main.bean import bank.csv --into 2026.bean
bea --file ~/my-books/main.bean import bank.csv --into 2026.bean --apply

2026.bean doit déjà exister et être inclus par le registre racine. Son chemin est relatif au répertoire racine. Le chemin d'export reste relatif à votre répertoire de travail. La prévisualisation identifie le fichier qui sera modifié.

Utiliser les importations dans un script​

bea --json --no-input import bank.csv --apply --duplicates skip

Choisissez skip uniquement si c'est votre politique prévue pour les correspondances possibles. JSON renvoie la prévisualisation et le nombre d'écritures dans data. Les applications refusées placent la prévisualisation dans error.result sur stderr, avec written: 0. Vérifiez toujours le code de sortie. Consultez la référence JSON et codes de sortie avant de planifier des importations non supervisées.

Dépanner un importateur​

Si la configuration importe des paquets tiers, ces paquets doivent être dans l'environnement Python exécutant bea. Par exemple :

uv run --with beancount-io --with beangulp \
  bea --file ~/my-books/main.bean import bank.ofx --config importers.py

Ajoutez --with YOUR_IMPORTER_PACKAGE pour un importateur bancaire installé séparément. Cela utilise un environnement distinct de celui de Homebrew.

Pour une exception d'importateur, placez --debug avant la commande pour afficher sa traceback :

bea --debug import bank.csv --config importers.py

La sortie de l'importateur est capturée dans importer_output afin de ne pas corrompre le JSON. En mode debug JSON, la traceback est error.traceback.

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