API Programmes

L'API Programmes permet de gerer les programmes de transferts monetaires.

Vue d'ensemble

Endpoint	Methode	Description
/api/programmes	GET	Liste des programmes
/api/programmes/{id}	GET	Detail d'un programme
/api/programmes	POST	Creer un programme
/api/programmes/{id}	PUT	Modifier un programme
/api/programmes/{id}	DELETE	Supprimer un programme
/api/programmes/{id}/activer	POST	Activer
/api/programmes/{id}/suspendre	POST	Suspendre
/api/programmes/{id}/cloturer	POST	Cloturer
/api/programmes/{id}/reactiver	POST	Reactiver
/api/programmes/{id}/stats	GET	Statistiques
/api/programmes/{id}/eligibles	GET	Menages eligibles
/api/programmes/{id}/enroler	POST	Enroler beneficiaires
/api/programmes/{id}/beneficiaires	GET	Beneficiaires
/api/programmes/{id}/cycles	GET	Cycles
/api/programmes/{id}/recurrence	GET/PUT	Recurrence
/api/programmes/stats/summary	GET	Stats globales
/api/programmes/regions	GET	Regions eligibles

Permissions requises

• programmes.view : Consultation
• programmes.create : Creation
• programmes.edit : Modification
• programmes.delete : Suppression
• programmes.enroll : Enrolement
• transferts.recurrence : Recurrence

---

Liste des programmes

Endpoint

GET /api/programmes

Parametres de requete

Parametre	Type	Requis	Description
page	int	Non	Numero de page (defaut: 1)
limit	int	Non	Elements par page (max: 100)
statut	string	Non	Filtrer par statut
type	string	Non	Filtrer par type
search	string	Non	Recherche textuelle

Statuts disponibles

Statut	Description
en_preparation	En cours de preparation
actif	Programme actif
suspendu	Temporairement suspendu
termine	Programme termine
cloture	Programme cloture

Types de programmes

Type	Description
transfert_monetaire	Transfert monetaire direct
travaux_publics	Travaux publics a haute intensite de main d'oeuvre
formation	Formation professionnelle
mixte	Programme mixte

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "PCH-GB-001",
      "nom": "PCH Guinee-Bissau",
      "description": "Programme de transferts monetaires conditionnels",
      "type": "transfert_monetaire",
      "dateDebut": "2024-01-01",
      "dateFin": "2026-12-31",
      "budgetTotal": "5000000000",
      "budgetAlloue": "3500000000",
      "montantDecaisse": "1800000000",
      "montantEngage": "2500000000",
      "devise": "XOF",
      "objectifBeneficiaires": 5000,
      "nbBeneficiairesActifs": 3500,
      "nbBeneficiairesTotal": 3600,
      "nbCyclesExecutes": 12,
      "tauxExecution": 36.0,
      "tauxCouverture": 70.0,
      "joursRestants": 730,
      "statut": "actif",
      "frequencePaiement": "mensuel",
      "montantParBeneficiaire": "15000",
      "avecConditionnalites": true,
      "projet": {
        "id": "...",
        "code": "PCH-2025",
        "nom": "Projet PCH",
        "lectureSeule": false
      },
      "createdAt": "2024-01-01T08:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "pages": 1
  }
}

---

Detail d'un programme

Endpoint

GET /api/programmes/{id}

Reponse

Inclut tous les champs de la liste plus :

{
  "success": true,
  "data": {
    "sourcesFinancement": ["Banque Mondiale", "Gouvernement GB"],
    "seuilPmtMax": 50,
    "seuilPmtMin": null,
    "categoriesPauvreteEligibles": ["extreme_pauvre", "pauvre"],
    "regionsEligibles": ["uuid-oio", "uuid-bafata"],
    "regionsEligiblesNoms": {
      "uuid-oio": "Oio",
      "uuid-bafata": "Bafata"
    },
    "milieuEligible": "tous",
    "criteresChefMenage": {
      "sexe": null,
      "ageMin": 18,
      "ageMax": null
    },
    "criteresMenage": {
      "tailleMin": 3
    },
    "criteresVulnerabilite": [
      "femme_chef_menage",
      "menage_avec_handicapes",
      "menage_personnes_agees"
    ],
    "criteresPersonnalises": null,
    "nombreCyclesPrevus": 36,
    "dureeMois": 36,
    "conditionnalites": {
      "education": ["scolarisation_enfants"],
      "sante": ["vaccination", "visite_prenatale"]
    },
    "responsable": "Mamadou Diallo",
    "emailResponsable": "m.diallo@pch.gw",
    "telephoneResponsable": "+245955000001",
    "partenaires": ["UNICEF", "PAM"],
    "budgetDisponible": "1000000000",
    "tauxEngagement": 50.0,
    "progressionCycles": 33.3,
    "nbMenagesEligibles": 15000
  }
}

---

Creer un programme

Endpoint

POST /api/programmes

Corps de la requete

{
  "nom": "Programme Pilote Region Est",
  "description": "Programme pilote de transferts monetaires",
  "type": "transfert_monetaire",
  "dateDebut": "2025-01-01",
  "dateFin": "2026-12-31",
  "budgetTotal": "500000000",
  "devise": "XOF",
  "montantParBeneficiaire": "15000",
  "frequencePaiement": "mensuel",
  "objectifBeneficiaires": 1000,
  "seuilPmtMax": 50,
  "categoriesPauvreteEligibles": ["extreme_pauvre", "pauvre"],
  "regionsEligibles": ["uuid-gabou"],
  "avecConditionnalites": true,
  "projetId": "uuid-projet"
}

---

Statistiques globales

Endpoint

GET /api/programmes/stats/summary

Reponse

{
  "success": true,
  "data": {
    "total": 5,
    "parStatut": {
      "en_preparation": 1,
      "actif": 3,
      "suspendu": 0,
      "termine": 1,
      "cloture": 0
    },
    "parType": {
      "transfert_monetaire": 4,
      "travaux_publics": 0,
      "formation": 1,
      "mixte": 0
    },
    "budgetTotal": 10000000000,
    "budgetAlloue": 7500000000,
    "montantDecaisse": 3500000000,
    "montantEngage": 5000000000,
    "nbBeneficiairesActifs": 8500,
    "nbBeneficiairesTotal": 9000,
    "objectifBeneficiaires": 12000,
    "nbCyclesExecutes": 45,
    "tauxExecution": 35.0,
    "tauxEngagement": 50.0,
    "tauxCouverture": 70.8
  }
}

---

Statistiques d'un programme

Endpoint

GET /api/programmes/{id}/stats

Reponse

{
  "success": true,
  "data": {
    "programme": {...},
    "cycles": [
      {"statut": "termine", "count": 10, "montant": "1500000000"},
      {"statut": "en_cours", "count": 1, "montant": "150000000"},
      {"statut": "planifie", "count": 2, "montant": "300000000"}
    ],
    "beneficiaires": [
      {"actif": true, "modePaiement": "mobile_money", "count": 3200},
      {"actif": true, "modePaiement": "virement_bancaire", "count": 300},
      {"actif": false, "modePaiement": "mobile_money", "count": 100}
    ],
    "parRegion": [
      {"region": "Oio", "count": 1500},
      {"region": "Bafata", "count": 1200}
    ],
    "indicateurs": {
      "tauxExecution": 36.0,
      "tauxEngagement": 50.0,
      "tauxCouverture": 70.0,
      "progressionCycles": 33.3,
      "budgetDisponible": "1000000000",
      "joursRestants": 730
    }
  }
}

---

Menages eligibles

Endpoint

GET /api/programmes/{id}/eligibles

Parametres de requete

Parametre	Type	Requis	Description
page	int	Non	Numero de page
limit	int	Non	Elements par page
search	string	Non	Recherche par code/nom
statut	string	Non	enrole, non_enrole, ou vide

Reponse

{
  "success": true,
  "data": {
    "stats": {
      "totalEligibles": 15000,
      "totalEnrolled": 3500,
      "totalNonEnrolled": 11500
    },
    "totalEligibles": 11500,
    "criteres": {
      "seuilPmtMax": 50,
      "seuilPmtMin": null,
      "categoriesPauvrete": ["extreme_pauvre", "pauvre"],
      "regions": ["uuid-oio", "uuid-bafata"],
      "milieu": "tous",
      "criteresChef": {"ageMin": 18},
      "criteresMenage": {"tailleMin": 3},
      "criteresVulnerabilite": ["femme_chef_menage"]
    },
    "preview": [
      {
        "id": "...",
        "codeMenage": "MEN-OIO-001",
        "chefNom": "Mamadou Diallo",
        "region": "Oio",
        "scorePmt": 35.5,
        "categoriePauvrete": "pauvre",
        "statutEnrolement": "non_enrole",
        "dateEnrolement": null,
        "codeBeneficiaire": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 11500,
      "pages": 1150
    }
  }
}

---

Enroler des beneficiaires

Endpoint

POST /api/programmes/{id}/enroler

Corps de la requete

{
  "menageIds": ["uuid-1", "uuid-2"],
  "limit": null
}

Si menageIds est vide, tous les menages eligibles non enroles seront enroles (jusqu'a limit).

Reponse

{
  "success": true,
  "message": "500 beneficiaires enroles",
  "data": {
    "enrolled": 500,
    "skipped": 10,
    "totalBeneficiaires": 4000
  }
}

---

Configuration de la recurrence

Lire la configuration

GET /api/programmes/{id}/recurrence

Reponse

{
  "success": true,
  "data": {
    "programmeId": "...",
    "programmeCode": "PCH-GB-001",
    "programmeNom": "PCH Guinee-Bissau",
    "recurrenceActive": true,
    "modeGeneration": "semi_automatique",
    "frequencePaiement": "mensuel",
    "jourGeneration": 1,
    "delaiCreationJours": 7,
    "parametresHeritables": ["montantParBeneficiaire", "description"],
    "prochainCycleDate": "2025-02-01",
    "dernierCycleGenereId": "uuid-dernier-cycle"
  }
}

Modifier la configuration

PUT /api/programmes/{id}/recurrence

Corps de la requete

{
  "recurrenceActive": true,
  "modeGeneration": "automatique",
  "frequencePaiement": "mensuel",
  "jourGeneration": 1,
  "delaiCreationJours": 7,
  "parametresHeritables": ["montantParBeneficiaire"]
}

Modes de generation

Mode	Description
automatique	Cycles generes automatiquement
semi_automatique	Notification envoyee, validation requise

Frequences

Frequence	Description
mensuel	Tous les mois
bimestriel	Tous les 2 mois
trimestriel	Tous les 3 mois
semestriel	Tous les 6 mois
annuel	Une fois par an

---

Apercu du prochain cycle

Endpoint

GET /api/programmes/{id}/recurrence/preview

Reponse

{
  "success": true,
  "data": {
    "dateDebut": "2025-02-01",
    "dateFin": "2025-02-28",
    "code": "PCH-GB-C013",
    "nom": "Cycle Fevrier 2025",
    "montantParBeneficiaire": "15000",
    "nbBeneficiairesEstimes": 3500,
    "montantTotalEstime": 52500000
  }
}

---

Generer le prochain cycle

Endpoint

POST /api/programmes/{id}/recurrence/generate

Corps de la requete

{
  "force": false
}

Reponse

{
  "success": true,
  "message": "Cycle genere avec succes",
  "data": {
    "id": "...",
    "code": "PCH-GB-C013",
    "nom": "Cycle Fevrier 2025",
    "dateDebut": "2025-02-01",
    "dateFin": "2025-02-28",
    "montantParBeneficiaire": "15000",
    "numeroSequence": 13
  }
}

---

Criteres de vulnerabilite

Code	Description
femme_chef_menage	Chef de menage femme
femme_rurale	Femme en milieu rural
personne_handicapee	Menage avec personne handicapee
menage_avec_handicapes	Menage avec handicapes
femme_agee_demunie	Femme agee (65+) demunie
menage_personnes_agees	Menage avec personnes 65+
femme_sans_assistance	Femme veuve/celibataire/divorcee