Utilitaire SEPA : lecture d'un fichier bancaire et import des personnes

Emplacement dans l'application : Comptabilité > Utilitaires > menu “Afficher un fichier sepa” (statut Beta).

Ne pas confondre avec l'entrée “Prélèvement SEPA” du même menu, qui elle génère un fichier XML de virements/prélèvements à envoyer à la banque depuis une multi-ligne comptable (module logeas-grid-export-xml). L'utilitaire décrit ici fait l'inverse : il lit un fichier SEPA déjà reçu/existant (XML pain.001, pain.008, pain.002 ou camt.054), affiche son contenu de façon lisible, le valide, puis propose de rapprocher les personnes qu'il contient avec les fiches Personne déjà en base.

L'écran app-sepa-viewer se compose de trois onglets :

1. Visualisation : dépose/charge un fichier XML SEPA, affiche l'en-tête du message, les paramètres de paiement, les mandats (le cas échéant) et le détail de chaque transaction, avec un contrôle de cohérence du fichier.
2. Récupération information *(l'utilitaire d'import à proprement parler)* : extrait la liste des créditeurs (virements) et débiteurs (prélèvements) du fichier, tente de les rapprocher automatiquement d'une personne existante dans l'annuaire, et permet de reporter l'IBAN/BIC/RUM lus dans le fichier sur la fiche de la personne rapprochée.
3. Informations émetteur : affiche en lecture seule l'identité, l'adresse, le compte et le contact du donneur d'ordre / créancier tel que déclaré dans le fichier (InitgPty). Purement informatif, aucune action de sauvegarde sur cet onglet.

• Dépôt d'un fichier XML par glisser-déposer ou sélection, ou chargement d'un des deux jeux de démonstration intégrés (pain.001 / pain.008).
• Le type de message est détecté automatiquement (espace de noms XML + présence de CstmrCdtTrfInitn/CstmrDrctDbtInitn).
• Une fois chargé, l'écran affiche :
  • des cartes de statistiques (nombre de transactions, montant total, nombre de groupes de paiement, date de création, et pour les prélèvements : nombre de mandats / mandats amendés) ;
  • un bloc de validation (voir §4) ;
  • les sections dépliables : en-tête du message, Identifiant Créancier SEPA (ICS, prélèvements uniquement), paramètres de paiement par groupe, mandats SEPA, puis le détail des transactions groupe par groupe.

C'est la partie utile pour mettre à jour l'annuaire à partir d'un relevé/fichier bancaire.

Chaque transaction du fichier est aplatie en une ligne de grille, séparée en deux listes :

• Créditeurs : bénéficiaires des virements (méthode TRF), typiquement les fournisseurs ou adhérents remboursés ;
• Débiteurs : payeurs des prélèvements (méthode DD), typiquement les adhérents prélevés, avec leurs informations de mandat (RUM, date de signature, type FRST/RCUR/FNAL/OOFF) si présentes dans le fichier.

Pour chaque ligne, l'utilitaire recherche la personne la plus proche dans l'annuaire par comparaison nom / prénom uniquement (algorithme de similarité Jaro-Winkler, service générique de rapprochement de doublons partagé avec le reste de l'application).

• L'IBAN, le RUM et l'adresse ne sont volontairement pas utilisés pour ce rapprochement : ce sont justement les informations que cet écran sert à récupérer ou corriger sur la personne — les utiliser en entrée serait circulaire.
• Seuil par défaut : 85/100, réglable directement à l'écran (champ “Rapprochement automatique accepté si score > ”). Ce seuil a été calé empiriquement : en dessous, des homonymes partiels français (ex. deux noms de famille différents sans lien) obtiennent facilement 55 à 76 points, alors que les vrais doublons avec faute de frappe ou accent (ex. variante orthographique d'un même nom) restent au-dessus de 91.
• Le nom brut du fichier (souvent “NOM Prénom” pour un particulier) est découpé de façon approximative en nom/prénom pour la comparaison ; ce découpage n'est pas fiable pour une personne morale et n'est de toute façon jamais persisté tel quel — il ne sert qu'à la comparaison.

Pour chaque ligne, le meilleur candidat (score le plus haut, au-dessus de 30 points, et au-dessus du seuil pour être retenu) est proposé, avec le détail des raisons du score.

Deux grilles (Créditeurs / Débiteurs) affichent : nom, statut de rapprochement, personne rapprochée (modifiable manuellement via une liste déroulante), score, IBAN, BIC, et pour les débiteurs le RUM, la date de signature du mandat et le type de mandat.

Le statut de rapprochement affiché est calculé en comparant les données lues dans le fichier à celles déjà enregistrées sur la personne rapprochée :

• Pas de correspondance : aucune personne trouvée au-dessus du seuil ;
• Même information : IBAN/BIC (et, pour un prélèvement, RUM/date de signature) identiques à ce qui est déjà en base ;
• Information divergente : au moins un de ces champs diffère.

Un clic sur une ligne (hors colonne “Personne rapprochée”) ouvre un détail (master-detail) comparant champ par champ la donnée lue dans le fichier et la donnée en base sur la personne actuellement rapprochée (recalculé à chaque clic, donc reflète un rapprochement corrigé manuellement dans la liste déroulante).

Depuis le détail d'une ligne, le bouton “Mettre à jour la fiche de la personne” reporte sur la fiche de la personne rapprochée :

• l'IBAN et le BIC lus dans le fichier ;
• pour un prélèvement uniquement : active l'indicateur “utilise le prélèvement”, le RUM (référence du mandat) et la date de signature du mandat, ainsi que le type de mandat si présent.

L'adresse n'est volontairement pas reportée : elle n'est plus comparée ni proposée à la mise à jour dans cet écran. La sauvegarde passe par le service Personne existant de l'application (mêmes règles métier que la fiche Personne standard).

Après mise à jour, le statut de la ligne est recalculé immédiatement (repasse normalement à “Même information”).

Un contrôle de cohérence est exécuté à chaque chargement de fichier et distingue erreurs et avertissements :

Un fichier peut donc être chargé et affiché même s'il comporte des erreurs de validation ; celles-ci sont listées à titre d'alerte pour l'utilisateur, sans bloquer la consultation ni le rapprochement.

• Le rapprochement se fait uniquement sur nom/prénom : deux personnes homonymes restent une source d'erreur potentielle, à corriger manuellement via la liste déroulante “Personne rapprochée”.
• Le découpage nom/prénom à partir du nom brut du fichier est approximatif, en particulier pour les raisons sociales (personnes morales) ; à vérifier/corriger au cas par cas.
• L'onglet “Informations émetteur” est purement consultatif : aucune action ne permet aujourd'hui de créer/mettre à jour une organisation ou un compte bancaire d'établissement depuis cet onglet.
• Statut expérimental de l'écran (“Beta”) : formats pain.002 et camt.054 sont détectés mais ne sont pas encore aplatis dans les grilles de rapprochement (traités comme “générique”, en-tête seulement).

Code source : src/app/Comptabilite/Utilitaire/decode-sepa/

Dépendances notables : DGService (chargement/sauvegarde), PersonneService (annuaire des personnes, source de données du rapprochement et de la sauvegarde), UniversalDuplicateService (moteur de similarité générique déjà utilisé ailleurs pour la détection de doublons).

Historique : ce module provenait à l'origine du dossier logeas-gestion-sepa/decode-sepa ; il a été extrait dans son propre dossier decode-sepa à la racine de Comptabilite/Utilitaire, indépendant du module d'export XML (logeas-grid-export-xml) avec lequel il ne partage pas de code.