Skill e-facture-rapprochement

Pipeline complet factures + banque → rapprochement → rapprochement.json, pour un ou

plusieurs clients. Cas d'usage dominant : photos de tickets de caisse et PDF côté

factures, exports bancaires (CSV/CAMT/OFX) ou PDF côté banque.

> Le moteur est dans scripts/main.py : ingestion (invoice_parsers.py,

> bank_parsers.py) + extraction LLM des pièces non structurées. Le **RAPPROCHEMENT

> lui-même est délégué au moteur unique et audité du skill rapprochement-paiements (⑤)**

> — un seul moteur pour les deux skills, donc des sorties identiques à entrées

> identiques (politique conservatrice unique : « payé » seulement sur montant serré,

> exclusions prudentes). Ce skill = comment le lancer + faire l'extraction LLM + rendre

> compte. Ne réimplémente pas le rapprochement et **n'écris jamais rapprochement.json

> à la main** : le format est contractuel (le backend l'ignore en silence s'il est malformé

> → le client perd ses données). main.py garantit le format et l'invariant.

> (reconcile.py reste présent pour ses tests unitaires mais n'écrit plus la sortie.)

Les 4 étapes (A → B → C → D)

• A. Ingestion factures — cascade : Factur-X (XML CII embarqué) → UBL/CII pur → **LLM

(texte/vision)** pour les tickets/PDF, avec score de confiance + validation humaine au-delà

d'un seuil. Voir references/invoice-extraction.md.

• B. Ingestion banque — CAMT.053 / OFX / CSV → transactions normalisées (montant signé).

PDF de relevé → extraction LLM. Voir references/bank-formats.md.

• C. Rapprochement — délégué au moteur partagé ⑤ (rapprochement-paiements) :

match montant + (référence/contrepartie/date), jamais le montant seul ; non matché →

unmatched_bank_lines ; non facturable (salaires, impôts, frais bancaires, retraits…) →

excluded_bank_lines. Politique conservatrice. Voir references/matching-rules.md.

• D. Sortie — company.json + rapprochement.json, invariant vérifié. Voir

references/output-contract.md.

Disposition d'entrée (par client)

<root>/<slug>/invoices|factures/    → factures (pdf, jpg, png, xml…)
<root>/<slug>/bank|releves|banque/  → relevés  (xml CAMT, ofx, csv, pdf…)
<root>/<slug>/company.json          → identité (optionnel ; sert à déduire achat/vente)

par défaut = sandbox ~/.openclaw/workspace/clients-test/ (pour ne pas écraser

d'autres sorties pendant la mise au point). Ajoute --real pour viser le vrai

~/.openclaw/workspace/clients/. Slug = minuscules-à-tirets ; dossiers _* ignorés.

Exécution — boucle en DEUX temps

Les tickets/PDF passent par TON extraction LLM, donc le run se fait en deux passes.

Passe 1 — lancer le moteur :

python3 scripts/main.py [<root>] [--client <slug>] [--today AAAA-MM-JJ]

Le script ingère tout ce qui est structuré. S'il reste des documents non structurés (photos,

PDF sans XML), il s'arrête et imprime une worklist : pour chacun, un chemin sidecar

où écrire le JSON extrait.

Passe 2 — extraire puis relancer :

Pour CHAQUE entrée de la worklist :

1. Lis le document (mode=text → couche texte via pdftotext -layout ; mode=vision →

lis l'image).

1. Extrais au schéma normalisé (references/invoice-extraction.md pour une facture,

references/bank-formats.md pour un relevé), avec un confidence honnête.

1. Écris le JSON dans le chemin sidecar indiqué (..invoice.json ou .bank.json).

Puis relance la même commande. Quand la worklist est vide, main.py rapproche, écrit les

2 fichiers, et imprime l'auto-contrôle. Les sidecars sont un cache : un doc déjà extrait

n'est pas redemandé.

Après l'exécution — rendre compte

Lis l'auto-contrôle et relaie au comptable un tableau lisible par client : factures

payées / en attente / partielles / en retard, paiements orphelins et factures manquantes,

relances. Mets en avant les factures listées pour validation humaine (_review.json :

montant élevé ou extraction peu sûre) — un humain doit les confirmer. Jamais de chemins

techniques bruts.

Règles critiques

• Format de sortie = contrat. N'écris pas rapprochement.json/company.json à la main ;

laisse main.py le faire (écriture atomique, snake_case exact). Pas de champ blocking

(supprimé du produit).

• Invariant non négociable. Pour chaque période,

rappr + unmatched + excluded == bank_transactions_count (aucune transaction oubliée).

main.py l'affiche (OK/KO) et sort en erreur si une période est KO — ne termine pas

sur un KO ni sur un JSON invalide.

• N'invente jamais un montant. Ticket illisible → sidecar confidence:0.0 sans montant →

anomalie facture_illisible (pièce à re-fournir). Mieux vaut une anomalie qu'un faux chiffre.

• Confiance honnête. Elle pilote la validation humaine (seuils dans normalize.py :

HUMAN_REVIEW_AMOUNT, HUMAN_REVIEW_CONFIDENCE).

• Sandbox d'abord. Sans --real, tout va dans clients-test/ ; on bascule sur le vrai

clients/ une fois validé.

• Si le script échoue, signale l'erreur exacte (stderr) ; ne rejoue pas le rapprochement à la main.

Tests

python3 scripts/test_reconcile.py   # moteur (montants, dates, matching, invariant, TVA)
python3 scripts/test_e2e.py         # bout-en-bout sur fixtures/ (UBL+CII+CAMT+CSV+ticket)

Périmètre

Ce skill produit seulement company.json + rapprochement.json ; il ne touche ni au

backend, ni au front, ni aux e-mails. Il complète l'écosystème compta existant (voir README)

en se concentrant sur l'ingestion e-facture/ticket structurée + LLM.