Export des Paiements

Exports des paiements d'un transfert vers l'opérateur de paiement (fichier ST) ou vers Excel, et suivi de leur transmission. Le fichier de retour de l'opérateur (CT) est traité par la réconciliation.

Endpoints

Toutes les routes /api/export-paiements demandent la permission transferts.paiements_view et vérifient que le transfert est dans le périmètre de l'utilisateur (403 sinon).

Endpoint	Methode	Description
/api/export-paiements/generate-st/{cycleId}	POST	Génère le fichier ST de l'opérateur (archive ZIP protégée)
/api/export-paiements/generate/{cycleId}	POST	Télécharge directement un Excel des paiements
/api/export-paiements	GET	Historique des exports (cycle, limit 50 par défaut, offset)
/api/export-paiements/{id}	GET	Détail d'un export
/api/export-paiements/download/{id}	GET	Télécharge l'archive d'un export
/api/export-paiements/{id}/marquer-envoye	POST	Marque l'export comme transmis à l'opérateur
/api/export-paiements/{id}/confirmer	POST	Marque l'export comme confirmé par l'opérateur
/api/export/paiements	GET	Données de paiements en JSON pour les exports de rapport

Les deux routes de génération acceptent les mêmes filtres dans le corps JSON : region, secteur, localite (UUID) et statut. Sans paiement correspondant : 400 Aucun paiement trouvé avec ces filtres.

---

POST /api/export-paiements/generate-st/{cycleId}

{ "region": "<uuid>", "statut": "en_attente" }

Le SIG produit une archive ZIP protégée par mot de passe. Elle contient le fichier ST, un Excel et un PDF récapitulatifs. Les paiements exportés en en_attente passent en en_cours, et le transfert passe en en_cours s'il n'est pas terminé.

{
  "success": true,
  "data": {
    "id": "…",
    "nomFichier": "20260715_143000_ST_AGENCE.zip",
    "motDePasse": "…",
    "hashSha256": "…",
    "nombreBeneficiaires": 1200,
    "montantTotal": 18000000,
    "dateGeneration": "2026-07-15T14:30:00+00:00"
  }
}

Le mot de passe de l'archive est renvoyé dans cette réponse : il se transmet à l'opérateur par un autre canal que le fichier.

Format ST

Le fichier ST est à largeur fixe, une ligne par bénéficiaire :

Champ	Largeur	Contenu
Indicateur	2	ST
Nom agence	10	Complété par des espaces
Système de paiement	10	MM
Identifiant de l'ordre de transfert	50	Unique par transfert
Identifiant de téléchargement	10	Unique par bénéficiaire, complété par des zéros
Date	8	JJMMAAAA
Date de valeur	8	JJMMAAAA
Montant	10	Sans décimales, complété par des zéros
Téléphone	24	Complété par des espaces
Nom du bénéficiaire	50	Complété par des espaces

---

POST /api/export-paiements/generate/{cycleId}

Renvoie directement un fichier paiements_<code>_<horodatage>.xlsx (pas de JSON).

---

Suivi d'un export

POST /api/export-paiements/{id}/marquer-envoye
POST /api/export-paiements/{id}/confirmer

Corps optionnel : { "commentaire": "…" }. La confirmation supprime l'archive du serveur.

---

Workflow d'export operateur

┌────────────────────┐
│ 1. Valider le      │
│    transfert       │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 2. Générer le ST   │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 3. Transmettre a   │
│    l'operateur     │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 4. Recevoir le     │
│    fichier CT      │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 5. Réconciliation  │
└────────────────────┘

---

Exemple

curl -X POST "https://sig.example.com/api/export-paiements/generate-st/<cycleId>" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statut": "en_attente"}'

curl "https://sig.example.com/api/export-paiements/download/<exportId>" \
  -H "Authorization: Bearer TOKEN" \
  -o export_st.zip

Codes d'erreur

HTTP	Cas
400	Aucun paiement ne correspond aux filtres
401	Non authentifié
403	Permission manquante ou transfert hors périmètre
404	Transfert, export ou fichier introuvable
500	Échec de création de l'archive