shield_lock
JinDaGe
← Back to skills
extension
Category: OtherNo API key required

Rapprochement Bancaire

Moteur comptable quotidien du cabinet. Analyse les dossiers clients déjà classés par organisation-documents, rapproche les paiements avec les factures, valid...

personAuthor: trendexhubclawhub
open_in_newRepositorydownloadDownload package

Skill rapprochement-bancaire

Moteur d'état. Travaille uniquement sur l'arborescence clients/<slug>/... produite par organisation-documents. Le travail réel est fait par scripts/main.py (qui appelle scripts/extract.py pour toute l'extraction de texte). Ce skill = quand le lancer + comment rendre compte.

⚠️ Règle absolue — EXÉCUTION DU SCRIPT (non négociable)

Pour chaque invocation, la SEULE action correcte est d'exécuter la commande :

python3 scripts/main.py <racine_clients>

puis de lire les followup.json / relances.json / anomalies.json par client + le compta_batch_report_<date>.json consolidé, et de relayer au comptable.

❌ INTERDIT

  • Réimplémenter le rapprochement en Python inline / pseudo-code. La logique (Pass 1 par référence, Pass 2 fuzzy, validation TVA, détection des anomalies, statuts overdue/partial, génération des relances) est dans scripts/main.py. La refaire à la main est garanti de diverger.
  • Écrire followup.json / relances.json / anomalies.json à la main. C'est le script qui le fait, dans son format exact (liste d'objets avec les champs invoice_id, type, amount, status, bank_matched, matched_tx, …). Toute autre forme (dict keyé, champs payments / amount_paid ad hoc) casse les lectures ultérieures.
  • Modifier le format des fichiers de sortie. Le format est contractuel entre ce skill et d'éventuels skills aval (relances, dashboards).

✅ OBLIGATOIRE

  1. Exécuter la commande shell ci-dessus.
  2. Lire les fichiers produits.
  3. Relayer au comptable un tableau lisible par client (factures payées / en attente / partielles / overdue, anomalies — en mettant en avant les bloquantes).

Si le script échoue

Signale l'erreur exacte (stderr). Ne rejoue PAS le batch à la main.

Pourquoi : on a déjà eu un run où l'agent a produit un followup.json au mauvais format (dict avec clés "in/N", champs payments/amount_paid/amount_remaining au lieu de bank_matched/status). Conséquence : aucun outil ni skill aval ne pouvait l'exploiter. Le script génère le bon format à tous les coups.

Exécution

python3 scripts/main.py [<racine_clients>]
# racine_clients par défaut : ~/.openclaw/workspace/clients

À lancer :

  • une fois par jour (idéalement la nuit), sur tous les clients ;
  • ou immédiatement après un trigger rapprochement-bancaire émis par organisation-documents.

Le script :

  1. Parcourt clients/* en ignorant les dossiers techniques _* (_a-identifier, _incomplet, _non-attribue, _cabinet).
  2. Périodes traitées : mois courant + mois précédent, plus tout mois ancien non verrouillé (batch.lock.json absent). Un mois verrouillé n'est pas retraité.
  3. Factures : nom de fichier conventionnel (AAAA-MM-JJ_N°Facture_Contrepartie_MontantTTC.pdf) → invoice_id + montant. Si le nom n'est pas exploitable, lecture du contenu via extract.py. Si toujours rien → anomalie facture_illisible.
  4. Relevés bancaires : transactions extraites ligne par ligne via extract.py (DATE | LIBELLÉ | MONTANT | CR/DB), avec la référence facture si le libellé contient REF <id> ou FACT <id>. Aucune transaction extractible → anomalie releve_non_parseable.
  5. Rapprochement (montant comparé en valeur absolue : une facture out est encaissée par un crédit, une in réglée par un débit) :
    • Pass 1 — réf facture : transaction dont invoice_ref == facture.invoice_id. Montant exact (±1 €) → paid ; montant inférieur → partial (conserve amount_paid, amount_remaining) ; supérieur → paid + overpaid_by.
    • Pass 2 — fuzzy : |montant| ±1 € ET similarité libellé / contrepartie ≥ 0.6.
    • aucun match + échéance dépassée → overdue.
  6. Validation TVA de chaque facture : si |TVA déclarée − TVA attendue| / TVA attendue > 5 % (TVA attendue = TOTAL HT × taux) → anomalie tva_incorrecte (TVA 0 % / exonération ignorée).
  7. Anomalies : voir tableau ci-dessous.
  8. Relances : overdue / partial / unpaid hors délai → step selon ancienneté.
  9. Écrit clients/<slug>/followup.json, relances.json, anomalies.json, et un rapport consolidé compta_batch_report_<date>.json.

Après l'exécution, lire le rapport et relayer au comptable un tableau lisible par client (factures payées / en attente, relances, anomalies — en mettant en avant les anomalies bloquantes). Jamais de chemins techniques.

Statuts de facture (followup.json)

| Statut | Sens | |--------|------| | unpaid | non échue, aucun paiement | | paid | paiement confirmé (rapprochement réussi) | | partial | paiement partiel — amount_paid + amount_remaining conservés | | overdue | échéance dépassée, aucun paiement |

Anomalies (anomalies.json)

Bloquantes (empêchent la clôture de la période) :

| Type | Condition | |------|-----------| | doublon_paiement | même date + montant + libellé | | tva_incorrecte | écart TVA calculée / déclarée > 5 % | | facture_manquante | une ligne du relevé cite un n° de facture (REF/FACT) absent du dossier, montant > 1 000 € | | paiement_orphelin | crédit > 1 000 € sans aucune référence ni facture |

Non bloquantes (signalées, clôture possible) :

| Type | Condition | |------|-----------| | facture_manquante | n° de facture cité au relevé mais absent, montant ≤ 1 000 € | | paiement_orphelin | crédit ≤ 1 000 € sans référence | | releve_non_parseable | aucune transaction extractible d'un relevé | | facture_illisible | facture dont ni le nom ni le contenu ne donnent n° + montant | | invoice_overdue | facture non payée, échéance dépassée |

facture_manquante ≠ paiement_orphelin : le premier = paiement qui cite un n° de facture qu'on n'a pas reçu (le client a oublié de transmettre la pièce) ; le second = encaissement sans aucune référence.

Relances (relances.json)

| Ancienneté du retard | Step | |----------------------|------| | ≤ 30 j | 1 | | ≤ 60 j | 2 | | ≤ 90 j | 3 | | > 90 j | escalation |

Pour partial : mention explicite "Solde restant dû : X,XX €".

Clôture de période

Le script crée clients/<slug>/<AAAA>/<MM>/batch.lock.json quand : aucune anomalie bloquante sur la période, hash des fichiers stable depuis 7 jours, aucun statut unpaid/overdue non justifié. Les périodes verrouillées ne sont jamais retraitées sauf changement de hash.

Règles critiques

  • Ne jamais supprimer de données. Ne jamais retraiter un mois verrouillé.
  • followup.json est un cache reconstructible : les PDFs classés restent la vérité. Le batch peut tout recalculer depuis zéro.
  • clients.json est lu seulement (maintenu par organisation-documents), jamais écrit ici.
  • Toute l'extraction de texte passe par scripts/extract.py — source unique, pas de logique de parsing dupliquée ici.

Philosophie

organisation-documents  →  classe les pièces, déduit clients.json
rapprochement-bancaire            →  rapproche, valide, reconstruit l'état comptable  (scripts/main.py)
relances                →  décision différée

Le système doit pouvoir être recalculé intégralement à partir des documents classés.