API Cycles de Paiement

L'API Cycles permet de gerer les transferts de paiement du programme de transferts monetaires. Dans l'interface, un cycle s'appelle un « transfert » ; les routes gardent le nom technique /api/cycles. Les reponses suivent le format { success, data } ; chaque endpoint verifie le perimetre de l'utilisateur (403 si le cycle est hors de ses projets).

Vue d'ensemble

Endpoint	Methode	Description
/api/cycles	GET	Liste des transferts
/api/cycles/detail/{id}	GET	Detail d'un transfert
/api/cycles	POST	Creer un transfert
/api/cycles/{id}	PUT, PATCH	Modifier un transfert
/api/cycles/{id}/generate-payments	POST	Generer les paiements
/api/cycles/{id}/validate	POST	Valider un transfert
/api/cycles/{id}/execute	POST	Executer les paiements
/api/cycles/{id}/stats	GET	Statistiques du transfert
/api/cycles/{id}/operators-stats	GET	Stats par operateur
/api/cycles/{id}/paiements	GET	Liste des paiements
/api/cycles/{id}/soumettre	POST	Soumettre pour validation
/api/cycles/{id}/valider	POST	Valider un niveau
/api/cycles/{id}/rejeter	POST	Rejeter le transfert
/api/cycles/{id}/validation-status	GET	Statut de validation

---

Liste des transferts

Endpoint

GET /api/cycles

Parametres de requete

Parametre	Type	Requis	Description
statut	string	Non	Filtrer par statut
search	string	Non	Recherche textuelle
projet_id	UUID	Non	Filtrer par projet

Statuts disponibles

Statut	Description
planifie	Cycle planifie, pas de paiements
preparation	Paiements generes
valide	Valide pour execution
en_cours	Execution en cours
termine	Execution terminee
rejete	Cycle rejete
annule	Cycle annule

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "PCH-GB-C001",
      "nom": "Cycle Janvier 2025",
      "description": "Paiement mensuel janvier",
      "dateDebut": "2025-01-01",
      "dateFin": "2025-01-31",
      "montantParBeneficiaire": "15000",
      "statut": "valide",
      "nbBeneficiairesPrevu": 3500,
      "nbBeneficiairesPaye": 0,
      "montantTotalPrevu": "52500000",
      "montantTotalPaye": "0",
      "tauxExecution": 0,
      "genereAutomatiquement": false,
      "numeroSequence": 1,
      "programmeId": "...",
      "programmeCode": "PCH-GB-001",
      "projet": {
        "id": "...",
        "code": "PCH-2025"
      },
      "createdAt": "2025-01-01T08:00:00+00:00"
    }
  ]
}

---

Detail d'un transfert

Endpoint

GET /api/cycles/detail/{id}

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "PCH-GB-C001",
    "nom": "Cycle Janvier 2025",
    "description": "Paiement mensuel janvier",
    "dateDebut": "2025-01-01",
    "dateFin": "2025-01-31",
    "montantParBeneficiaire": "15000",
    "statut": "valide",
    "nbBeneficiairesPrevu": 3500,
    "nbBeneficiairesProgramme": 3500,
    "nbBeneficiairesPaye": 0,
    "montantTotalPrevu": "52500000",
    "montantTotalPaye": "0",
    "tauxExecution": 0,
    "dateValidation": "2025-01-05T10:00:00+00:00",
    "soumisPourValidation": true,
    "dateSoumission": "2025-01-04T14:00:00+00:00",
    "niveauValidation": 2,
    "niveauxRequis": 3,
    "statutValidation": "en_attente",
    "commentaireValidation": null,
    "historiqueValidations": [
      {
        "action": "soumission",
        "niveau": 0,
        "niveauNom": "Soumission",
        "date": "2025-01-04T14:00:00+00:00",
        "commentaire": null,
        "utilisateur": {"email": "agent@pch.gw"}
      },
      {
        "action": "validation",
        "niveau": 1,
        "niveauNom": "Verification",
        "date": "2025-01-04T16:00:00+00:00",
        "commentaire": "Montants verifies",
        "utilisateur": {"email": "superviseur@pch.gw"}
      }
    ],
    "programme": {
      "id": "...",
      "code": "PCH-GB-001",
      "nom": "PCH Guinee-Bissau"
    },
    "compteOperateur": {
      "id": "...",
      "code": "OM-001",
      "libelle": "Compte Orange Money Principal",
      "operateur": "orange_money",
      "letterSettings": {...}
    }
  }
}

---

Creer un transfert

Endpoint

POST /api/cycles

Corps de la requete

{
  "nom": "Cycle Fevrier 2025",
  "description": "Paiement mensuel fevrier",
  "dateDebut": "2025-02-01",
  "dateFin": "2025-02-28",
  "programme": "550e8400-e29b-41d4-a716-446655440001",
  "montantUnitaire": "15000",
  "nbBeneficiairesPrevu": 3500,
  "compteOperateur": "550e8400-e29b-41d4-a716-446655440002"
}

Champs requis

• nom : Nom du transfert
• dateDebut : Date de debut
• programme : ID du programme

Reponse

{
  "success": true,
  "message": "Cycle cree avec succes",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "code": "PCH-GB-C002",
    "nom": "Cycle Fevrier 2025",
    "programme": {
      "id": "...",
      "nom": "PCH Guinee-Bissau"
    }
  }
}

---

Generer les paiements

Endpoint

POST /api/cycles/{id}/generate-payments

Description

Genere les paiements pour tous les beneficiaires actifs du programme.

Contraintes

• Le transfert doit etre en statut planifie, valide, ou en_cours
• Aucun paiement ne doit exister pour ce transfert
• Le programme ne doit pas etre cloture ou termine

Reponse

{
  "success": true,
  "message": "Paiements generes avec succes",
  "data": {
    "nbPaiementsGeneres": 3500,
    "montantTotal": 52500000
  }
}

---

Valider un transfert

Endpoint

POST /api/cycles/{id}/validate

Description

Valide le transfert pour permettre l'execution des paiements (validation simple).

Contraintes

• Le transfert doit etre en statut preparation
• Le programme ne doit pas etre cloture

Reponse

{
  "success": true,
  "message": "Cycle valide avec succes"
}

---

Executer les paiements

Endpoint

POST /api/cycles/{id}/execute

Description

Execute les paiements du transfert. En mode dev/test, les paiements sont simules avec 85% de reussite.

Contraintes

• Le transfert doit etre en statut valide ou en_cours
• Le programme doit etre actif

Reponse

{
  "success": true,
  "message": "3500 paiements traites (2975 reussis, 525 echoues)",
  "data": {
    "total": 3500,
    "reussis": 2975,
    "echoues": 525,
    "details": [
      {
        "id": "...",
        "beneficiaire": "Mamadou Diallo",
        "montant": "15000",
        "statut": "reussi"
      }
    ]
  },
  "cycle": {
    "id": "...",
    "statut": "termine",
    "nbBeneficiairesPaye": 2975,
    "montantTotalPaye": "44625000"
  }
}

---

Statistiques du transfert

Endpoint

GET /api/cycles/{id}/stats

Reponse

{
  "success": true,
  "data": {
    "cycle": {
      "code": "PCH-GB-C001",
      "statut": "termine"
    },
    "byStatus": {
      "reussi": {"count": 2975, "montant": 44625000},
      "echoue": {"count": 525, "montant": 7875000}
    },
    "total": {
      "count": 3500,
      "montant": 52500000
    }
  }
}

---

Statistiques par operateur

Endpoint

GET /api/cycles/{id}/operators-stats

Reponse

{
  "success": true,
  "data": {
    "cycle": {
      "id": "...",
      "code": "PCH-GB-C001",
      "nom": "Cycle Janvier 2025"
    },
    "operators": [
      {
        "operateur": "orange_money",
        "operateurOriginal": "mobile_money",
        "operateurLabel": "Orange Money",
        "count": 2500,
        "montantBrut": 37500000,
        "fraisTransaction": 187500,
        "taxeAdministrative": 37500,
        "montant": 37725000,
        "compteOperateur": {
          "id": "...",
          "code": "OM-001",
          "libelle": "Orange Money Principal",
          "letterSettings": {...}
        }
      },
      {
        "operateur": "mtn",
        "operateurLabel": "MTN Mobile Money",
        "count": 1000,
        "montant": 15000000
      }
    ],
    "comptesDisponibles": [...]
  }
}

---

Liste des paiements d'un transfert

Endpoint

GET /api/cycles/{id}/paiements

Parametres de requete

Parametre	Type	Requis	Description
page	int	Non	Numero de page (defaut: 1)
limit	int	Non	Elements par page (defaut: 20)
statut	string	Non	Filtrer par statut
region	UUID	Non	Filtrer par region
secteur	UUID	Non	Filtrer par secteur
localite	UUID	Non	Filtrer par localite
pagination	string	Non	false pour desactiver

Reponse

{
  "success": true,
  "data": [
    {
      "id": "...",
      "reference": "PAY-PCH-GB-C001-A1B2C3D4",
      "beneficiaire": {
        "id": "...",
        "code": "BEN-OIO-2025-000001",
        "codeBeneficiaire": "BEN-OIO-2025-000001",
        "nom": "Mamadou Diallo",
        "nomComplet": "Mamadou Diallo",
        "sexe": "M",
        "telephone": "+245955123456",
        "modePaiement": "mobile_money",
        "compteMobile": "+245955123456",
        "menage": {
          "id": "...",
          "code": "MEN-OIO-001",
          "region": {"id": "...", "nom": "Oio"},
          "secteur": {"id": "...", "nom": "Farim"},
          "localite": {"id": "...", "nom": "Farim Centro"}
        }
      },
      "montant": "15000",
      "methodePaiement": "mobile_money",
      "operateur": "orange_money",
      "statut": "reussi",
      "dateSoumission": "2025-01-15T10:00:00+00:00",
      "dateExecution": "2025-01-15T10:05:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3500,
    "pages": 175
  }
}

---

Validation multi-niveaux

Soumettre pour validation

POST /api/cycles/{id}/soumettre

Corps de la requete

{
  "commentaire": "Cycle pret pour verification"
}

Reponse

{
  "success": true,
  "message": "Cycle soumis pour validation",
  "data": {
    "id": "...",
    "code": "PCH-GB-C001",
    "nom": "Cycle Janvier 2025",
    "statut": "preparation",
    "validation": {
      "soumisPourValidation": true,
      "dateSoumission": "2025-01-04T14:00:00+00:00",
      "statutValidation": "en_attente",
      "niveauActuel": 0,
      "niveauActuelNom": "Soumission",
      "niveauxRequis": 3,
      "prochainNiveau": "Verification",
      "estComplet": false
    }
  }
}

Valider un niveau

POST /api/cycles/{id}/valider

Corps de la requete

{
  "commentaire": "Montants verifies, OK pour continuer"
}

Rejeter

POST /api/cycles/{id}/rejeter

Corps de la requete

{
  "commentaire": "Erreur dans les montants, a corriger"
}

---

Recurrence

Transferts en attente de generation

GET /api/cycles/pending

Generer un transfert pour un programme

POST /api/cycles/generate/{programmeId}

Apercu du prochain cycle

GET /api/cycles/preview/{programmeId}

Generer tous les transferts automatiques

POST /api/cycles/generate-all-automatic

---

Niveaux de validation

Niveau	Nom	Description
0	Soumission	Cycle soumis
1	Verification	Premier niveau
2	Validation	Second niveau
3	Approbation	Troisieme niveau
4	Autorisation	Niveau final