espace-paie-odentas/SEPA_EXPORT_FEATURE.md

# Export SEPA XML pour Virements Salaires

**Date** : 2 novembre 2025  
**Contexte** : Faciliter les virements de salaires pour les clients

## 🎯 Fonctionnalité

Permet aux clients d'exporter un fichier XML au format **SEPA ISO 20022 "pain.001.001.03"** pour lancer facilement les virements de salaires depuis leur banque.

## ✨ Caractéristiques

### 1. Sélection des paies
- ✅ Checkbox sur chaque ligne de paie non payée
- ✅ Checkbox "Tout sélectionner" dans le header du tableau
- ✅ Bouton "Export fichier bancaire (SEPA)" apparaît quand des paies sont cochées
- ✅ Compteur de paies sélectionnées affiché

### 2. Regroupement automatique
- ✅ Si un salarié a plusieurs paies sélectionnées → **un seul virement** avec montant total
- ✅ Les références de contrats sont combinées dans le libellé du virement

### 3. Gestion des IBAN manquants
- ⚠️ Si un salarié n'a pas d'IBAN/BIC → il est **automatiquement exclu** de l'export
- ⚠️ Un modal d'avertissement liste les salariés exclus
- ✅ L'export se fait quand même pour les autres salariés

### 4. Format SEPA XML
Le fichier généré respecte la norme **ISO 20022 pain.001.001.03** :
- **Donneur d'ordre** : L'entreprise (IBAN depuis `organization_details`)
- **Bénéficiaires** : Les salariés (IBAN/BIC depuis la table `salaries`)
- **Montants** : Net à payer (`net_after_withholding`)
- **Libellés** : **"Nom organisation - Période"** (ex: "Atelier Moz - Octobre 2025")
  - Le nom de l'organisation est automatiquement tronqué si trop long (limite SEPA : 140 caractères)
  - La période est formatée au format "Mois Année" (ex: "Octobre 2025")
- **Date d'exécution** : Date du jour (modifiable par la banque)

## 📁 Fichiers modifiés

### 1. API Route
**`app/api/virements-salaires/export-sepa/route.ts`**
- Récupère les payslips sélectionnés
- Valide les IBAN (format basique)
- Regroupe les paiements par salarié
- Génère le XML SEPA
- Retourne le fichier + métadonnées

### 2. Page Client
**`app/(app)/virements-salaires/page.tsx`**
- Ajout d'états : `selectedPayslips`, `showExportModal`, `exportWarnings`, `isExporting`
- Ajout de fonctions : 
  - `togglePayslipSelection()`
  - `toggleSelectAll()`
  - `handleExportSepa()`
- Ajout de la colonne checkbox dans le tableau
- Ajout du bouton d'export
- Ajout du modal d'avertissement pour salariés sans IBAN

## 🗄️ Données requises

### Dans `organization_details`
- ✅ `iban` (IBAN de l'entreprise) - **REQUIS**
- ⚠️ `bic` (BIC de la banque) - Optionnel mais recommandé

### Dans `salaries`
- ✅ `iban` (IBAN du salarié) - **REQUIS pour inclusion**
- ⚠️ `bic` (BIC de la banque du salarié) - Optionnel

Si l'entreprise n'a pas d'IBAN → Erreur bloquante  
Si un salarié n'a pas d'IBAN → Exclusion automatique avec avertissement

## 🔄 Workflow utilisateur

1. Client va sur `/virements-salaires`
2. Client coche les paies à payer
3. Bouton "Export fichier bancaire" apparaît
4. Client clique sur le bouton
5. API génère le XML SEPA
6. Si des salariés n'ont pas d'IBAN → Modal d'avertissement
7. Fichier `virements_sepa_MSGXXX.xml` est téléchargé
8. Client importe le fichier dans son espace bancaire
9. Client valide les virements dans sa banque

## 📝 Exemple de fichier généré

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>MSG20251102143025ABC123</MsgId>
      <CreDtTm>2025-11-02T14:30:25Z</CreDtTm>
      <NbOfTxs>3</NbOfTxs>
      <CtrlSum>4250.50</CtrlSum>
      <InitgPty>
        <Nm>MA STRUCTURE</Nm>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>MSG20251102143025ABC123-001</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <NbOfTxs>3</NbOfTxs>
      <CtrlSum>4250.50</CtrlSum>
      <PmtTpInf>
        <SvcLvl><Cd>SEPA</Cd></SvcLvl>
      </PmtTpInf>
      <ReqdExctnDt>2025-11-02</ReqdExctnDt>
      <Dbtr><Nm>MA STRUCTURE</Nm></Dbtr>
      <DbtrAcct><Id><IBAN>FR7630001007941234567890185</IBAN></Id></DbtrAcct>
      <DbtrAgt><FinInstnId><BIC>BNPAFRPP</BIC></FinInstnId></DbtrAgt>
      <ChrgBr>SLEV</ChrgBr>
      
      <CdtTrfTxInf>
        <PmtId><EndToEndId>MSG20251102143025ABC123-001</EndToEndId></PmtId>
        <Amt><InstdAmt Ccy="EUR">1500.00</InstdAmt></Amt>
        <CdtrAgt><FinInstnId><BIC>CEPAFRPP</BIC></FinInstnId></CdtrAgt>
        <Cdtr><Nm>DUPONT Jean</Nm></Cdtr>
        <CdtrAcct><Id><IBAN>FR7612345678901234567890123</IBAN></Id></CdtrAcct>
        <RmtInf><Ustrd>Atelier Moz - Octobre 2025</Ustrd></RmtInf>
      </CdtTrfTxInf>
      
      <!-- Autres virements... -->
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>
```

## 🚀 Prochaines améliorations possibles

- [ ] Permettre de choisir la date d'exécution
- [ ] Enregistrer l'historique des exports SEPA
- [ ] Marquer automatiquement les paies comme "payées" après export
- [ ] Support du format pain.001.001.09 (version plus récente)
- [ ] Validation IBAN plus stricte avec module de contrôle
- [ ] Récupération automatique du BIC depuis l'IBAN (API externe)

## 📊 Impact

- **UX** : Les clients gagnent du temps sur la saisie manuelle des virements
- **Sécurité** : Moins d'erreurs de saisie d'IBAN
- **Traçabilité** : Libellés standardisés avec références de contrats
- **Conformité** : Format SEPA standard accepté par toutes les banques européennes