API Cycles de Paiement

L'API Cycles permet de gerer les cycles de paiement du programme de transferts monetaires.

Vue d'ensemble

Endpoint	Methode	Description
`/api/cycles`	GET	Liste des cycles
`/api/cycles/{id}`	GET	Detail d'un cycle
`/api/cycles`	POST	Creer un cycle
`/api/cycles/{id}`	PUT	Modifier un cycle
`/api/cycles/{id}/generate-payments`	POST	Generer les paiements
`/api/cycles/{id}/validate`	POST	Valider un cycle
`/api/cycles/{id}/execute`	POST	Executer les paiements
`/api/cycles/{id}/stats`	GET	Statistiques du cycle
`/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 cycle
`/api/cycles/{id}/validation-status`	GET	Statut de validation

Permissions requises

transferts.cycles_view : Consultation
transferts.cycles_create : Creation
transferts.cycles_edit : Modification
transferts.cycles_validate : Validation
transferts.paiements_execute : Execution des paiements

Liste des cycles

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 cycle

Endpoint

GET /api/cycles/{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 cycle

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 cycle
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 cycle doit etre en statut planifie, valide, ou en_cours
Aucun paiement ne doit exister pour ce cycle
Le programme ne doit pas etre cloture ou termine

Reponse

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

Valider un cycle

Endpoint

POST /api/cycles/{id}/validate

Description

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

Contraintes

Le cycle 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 cycle. En mode dev/test, les paiements sont simules avec 85% de reussite.

Contraintes

Le cycle 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 cycle

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 cycle

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

Cycles en attente de generation

GET /api/cycles/pending

Generer un cycle pour un programme

POST /api/cycles/generate/{programmeId}

Apercu du prochain cycle

GET /api/cycles/preview/{programmeId}

Generer tous les cycles 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

Vue d'ensemble​

Permissions requises​

Liste des cycles​

Endpoint​

Parametres de requete​

Statuts disponibles​

Reponse​

Detail d'un cycle​

Endpoint​

Reponse​

Creer un cycle​

Endpoint​

Corps de la requete​

Champs requis​

Reponse​

Generer les paiements​

Endpoint​

Description​

Contraintes​

Reponse​

Valider un cycle​

Endpoint​

Description​

Contraintes​

Reponse​

Executer les paiements​

Endpoint​

Description​

Contraintes​

Reponse​

Statistiques du cycle​

Endpoint​

Reponse​

Statistiques par operateur​

Endpoint​

Reponse​

Liste des paiements d'un cycle​

Endpoint​

Parametres de requete​

Reponse​

Validation multi-niveaux​

Soumettre pour validation​

Corps de la requete​

Reponse​

Valider un niveau​

Corps de la requete​

Rejeter​

Corps de la requete​

Recurrence​

Cycles en attente de generation​

Generer un cycle pour un programme​

Apercu du prochain cycle​

Generer tous les cycles automatiques​

Niveaux de validation​

Vue d'ensemble

Permissions requises

Liste des cycles

Endpoint

Parametres de requete

Statuts disponibles

Reponse

Detail d'un cycle

Endpoint

Reponse

Creer un cycle

Endpoint

Corps de la requete

Champs requis

Reponse

Generer les paiements

Endpoint

Description

Contraintes

Reponse

Valider un cycle

Endpoint

Description

Contraintes

Reponse

Executer les paiements

Endpoint

Description

Contraintes

Reponse

Statistiques du cycle

Endpoint

Reponse

Statistiques par operateur

Endpoint

Reponse

Liste des paiements d'un cycle

Endpoint

Parametres de requete

Reponse

Validation multi-niveaux

Soumettre pour validation

Corps de la requete

Reponse

Valider un niveau

Corps de la requete

Rejeter

Corps de la requete

Recurrence

Cycles en attente de generation

Generer un cycle pour un programme

Apercu du prochain cycle

Generer tous les cycles automatiques

Niveaux de validation