Gestion des transferts de paiement

Ces routes sous /api/paiements/cycles sont une seconde entrée vers les transferts (cycles), orientée paiements. La gestion complète d'un transfert (création, circuit de validation multi-niveaux, génération des paiements) est décrite dans Transferts sous /api/cycles.

Endpoint	Methode	Permission	Description
/api/paiements/cycles	GET	transferts.cycles_view	Liste des transferts
/api/paiements/cycles	POST	transferts.cycles_create	Créer un transfert et générer ses paiements
/api/paiements/cycles/{id}/validate	POST	transferts.cycles_validate	Validation simple
/api/paiements/cycles/{id}/execute	POST	transferts.paiements_execute	Exécuter les paiements
/api/paiements/cycles/{id}/paiements	GET	transferts.paiements_view	Paiements du transfert (statut, search, page, limit 50 par défaut)
/api/paiements/cycles/{id}/indicateurs-odp	GET	transferts.paiements_view	Indicateurs de l'ordre de paiement
/api/paiements/cycles/{id}/export-beneficiaires	GET	transferts.paiements_view	Liste des bénéficiaires
/api/paiements/cycles/{id}/export-paiements-pdf	POST	transferts.paiements_view	État des paiements en PDF
/api/paiements/cycles/{id}/export-sms	GET	transferts.paiements_view	Liste pour l'envoi de SMS
/api/paiements/cycles/{id}/send-transfer-letter	POST	transferts.paiements_view	Envoi de la lettre de transfert
/api/paiements/cycles/{id}/generer-arrieres	POST	transferts.paiements_view	Génère les arriérés
/api/paiements/cycles/{id}/import-reconciliation	POST	transferts.paiements_view	Import du fichier de retour

Lister les transferts

Récupère la liste des transferts de paiement avec filtres optionnels.

Endpoint

GET /api/paiements/cycles

Paramètres de requête

Paramètre	Type	Requis	Description
programme	UUID	Non	Filtrer par programme
projet_id	UUID	Non	Filtrer par projet (projet.id accepté)
statut	string	Non	Filtrer par statut
search	string	Non	Recherche textuelle
date_debut, date_fin	date	Non	Période
montant_min, montant_max	number	Non	Montant par bénéficiaire
nb_beneficiaires_min, nb_beneficiaires_max	int	Non	Nombre de bénéficiaires prévus

Exemple de requête

curl -X GET "https://sig.example.com/api/paiements/cycles?statut=valide" \
  -H "Authorization: Bearer <token>"

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "code": "PCH-C001",
      "nom": "Transfert janvier 2025",
      "numero": 1,
      "programme": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "nom": "Programme Capital Humain"
      },
      "dateDebut": "2025-01-01",
      "dateFin": "2025-01-31",
      "statut": "valide",
      "nbBeneficiairesPrevu": 3500,
      "nbBeneficiairesPaye": 3450,
      "montantTotalPrevu": 87500000,
      "montantTotalPaye": 86250000,
      "tauxExecution": 98.57
    }
  ]
}

---

Créer un transfert

Crée un nouveau transfert et génère automatiquement les paiements.

Endpoint

POST /api/paiements/cycles

Corps de la requête

{
  "programme_id": "550e8400-e29b-41d4-a716-446655440000",
  "periode_debut": "2025-02-01",
  "periode_fin": "2025-02-28"
}

Paramètres

Paramètre	Type	Requis	Description
programme_id	UUID	Oui	ID du programme
periode_debut	date	Oui	Date de début (YYYY-MM-DD)
periode_fin	date	Oui	Date de fin (YYYY-MM-DD)

Réponse

{
  "success": true,
  "data": {
    "cycle_id": "550e8400-e29b-41d4-a716-446655440002",
    "code": "PCH-C002",
    "paiements_generes": {
      "total": 3500,
      "montant_total": 87500000
    }
  }
}

Codes de réponse

Code	Description
200	Cycle créé avec succès
400	Données invalides
401	Non authentifié
403	Non autorisé (rôle insuffisant)
404	Programme non trouvé

---

Valider un transfert

Valide un transfert pour permettre son exécution.

Endpoint

POST /api/paiements/cycles/{id}/validate

Paramètres

Paramètre	Type	Requis	Description
id	UUID	Oui	ID du transfert (dans l'URL)

Exemple de requête

curl -X POST "https://sig.example.com/api/paiements/cycles/550e8400-e29b-41d4-a716-446655440002/validate" \
  -H "Authorization: Bearer <token>"

Réponse

{
  "success": true,
  "data": {
    "statut": "valide"
  }
}

Erreurs possibles

Code	Message	Description
400	Cycle déjà validé ou en cours	Le transfert n'est pas en statut preparation
404	Cycle non trouvé	ID invalide