Importer des relevés

Un relevé entier entre dans Badlen par une seule route, POST /api/v1/import, atteinte avec une clé API portant transactions:write. C’est toute la surface. Il n’y a pas d’analyseur CSV, pas de lecteur OFX ou QIF, pas de connexion bancaire, et aucun écran qui prenne un fichier de relevé : le seul formulaire d’opération de l’application web écrit une ligne à la fois.

En pratique, la route est pilotée par le serveur MCP, où votre propre Claude fait la lecture et l’extraction. La piloter depuis un script à vous, c’est la même route et la même clé.

Note

Réglages → Données dit aussi Importer, et c’est autre chose : celui-là restaure un export JSON de tout votre compte par POST /api/data/import. Voyez Sauvegarder.

Ce qu’une ligne doit être

La route ne prend aucun fichier brut. Elle prend un identifiant de compte et un tableau de lignes normalisées, et transformer un fichier de courtier en celles-ci est le travail de l’appelant.

Champ	Obligatoire	Forme
date	oui	YYYY-MM-DD
amount	oui	Chaîne décimale signée ; négatif pour l’argent qui sort
label	oui	Texte non vide
currency	non	Trois lettres ; EUR à défaut
fee	non	Chaîne décimale positive ou nulle
tax	non	Chaîne décimale positive ou nulle

L’argent voyage en chaîne décimale, jamais en nombre JSON : un nombre est devenu un flottant double le temps que l’API le lise, et une quantité perd ses derniers chiffres en chemin. Un corps qui en envoie un est refusé.

Le schéma accepte aussi type, counterparty et category, mais l’import ne les écrit pas sur la ligne. Les catégories d’un envoi sont seulement comptées : la simulation ci-dessous rapporte combien de lignes sont arrivées sans catégorie, pour que vous pressiez ensuite Recatégoriser sur Réglages → Catégories.

Les doublons

Chaque ligne reçoit une empreinte bâtie sur sa date, son montant et son libellé replié en minuscules. Une ligne dont le compte porte déjà l’empreinte est écartée, et c’est ce qui rend sans danger le renvoi du même relevé.

Deux opérations identiques le même jour (deux paiements par carte du même montant chez le même commerçant) ne sont pas doublons l’une de l’autre. Elles sont rangées séparément au sein de l’envoi, si bien que les deux atterrissent. Ce rang n’appartient qu’à l’envoi, ce qui a une conséquence qu’il vaut mieux connaître :

Un relevé, un seul envoi

Le rang dépend de l’envoi et jamais de ce qui est stocké. Deux lignes identiques réparties sur deux envois d’une ligne ressemblent à deux fois la même opération, et une seule est écrite. Envoyées ensemble, les deux le sont.

Une opération que vous avez supprimée après un import antérieur reste connue. Badlen garde une marque de suppression pour l’empreinte, et la même ligne dans un import ultérieur du même relevé n’est pas réécrite.

La simulation

POST /api/v1/import/reconcile prend exactement le même corps et n’écrit rien. Elle répond avec la répartition de l’envoi (combien de lignes sont nouvelles, combien sont déjà là, combien sont enterrées), plus sa plage de dates, les totaux entrants et sortants, combien d’opérations le compte porte déjà et jusqu’à quelle date, et les lignes qui correspondent à une date et à un montant existants sous un libellé différent. Elle renvoie aussi les questions qui valent d’être posées avant de valider.

Les deux appels comptent par la même fonction et l’import répond avec les mêmes chiffres, si bien que ce que la simulation annonce est ce que l’écriture fait.