API Beneficiaires
L'API Beneficiaires permet de gerer les beneficiaires des programmes de transferts monetaires.
Vue d'ensemble
| Endpoint | Methode | Description |
|---|---|---|
/api/beneficiaires | GET | Liste des beneficiaires |
/api/beneficiaires/{id} | GET | Detail d'un beneficiaire |
/api/beneficiaires | POST | Creer un beneficiaire |
/api/beneficiaires/{id} | PUT | Modifier un beneficiaire |
/api/beneficiaires/{id}/activate | POST | Activer |
/api/beneficiaires/{id}/deactivate | POST | Desactiver |
/api/beneficiaires/check-duplicates | POST | Verifier doublons |
/api/beneficiaires/import/from-menages | POST | Import depuis menages |
/api/beneficiaires/bulk-action | POST | Actions en masse |
/api/beneficiaires/stats/summary | GET | Statistiques |
Permissions requises
ROLE_USER: ConsultationROLE_ADMIN: Creation, modificationROLE_TM_SPECIALIST: Import depuis menagestransferts.beneficiaires_edit: Actions en masse
Liste des beneficiaires
Endpoint
GET /api/beneficiaires
Parametres de requete
| Parametre | Type | Requis | Description |
|---|---|---|---|
page | int | Non | Numero de page (defaut: 1) |
limit | int | Non | Elements par page (defaut: 20) |
actif | boolean | Non | Filtrer par statut actif |
search | string | Non | Recherche par nom ou telephone |
region | UUID | Non | Filtrer par region |
secteur | UUID | Non | Filtrer par secteur |
localite | UUID | Non | Filtrer par localite |
projet | UUID | Non | Filtrer par projet |
menage.id | UUID | Non | Filtrer par menage |
Reponse
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"nomComplet": "Mamadou Diallo",
"telephone": "+245955123456",
"modePaiement": "mobile_money",
"compteMobile": "+245955123456",
"compteBancaire": null,
"actif": true,
"menage": {
"id": "...",
"code": "MEN-OIO-001",
"region": "Oio",
"secteur": "Farim"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3500,
"pages": 175
}
}
Detail d'un beneficiaire
Endpoint
GET /api/beneficiaires/{id}
Reponse
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"codeBeneficiaire": "BEN-OIO-2025-000001",
"nomComplet": "Mamadou Diallo",
"telephone": "+245955123456",
"modePaiement": "mobile_money",
"compteMobile": "+245955123456",
"compteBancaire": null,
"actif": true,
"dateEnrolement": "2025-01-01T08:00:00+00:00",
"typeBeneficiaire": "principal",
"isPrincipal": true,
"isSubstitut": false,
"documentVerifie": true,
"dateVerificationDocument": "2025-01-02T10:00:00+00:00",
"numeroMTN": null,
"beneficiairePrincipal": null,
"statutCycle": "actif",
"statutEnrolement": "actif",
"tauxConformiteGlobal": 95.5,
"nombreCyclesCompletes": 12,
"estGradue": false,
"dateGraduation": null,
"dateSortie": null,
"motifSortie": null,
"prochaineRecertification": "2025-07-01T00:00:00+00:00",
"dernierSuivi": "2025-03-10T14:30:00+00:00",
"menage": {
"id": "...",
"code": "MEN-OIO-001",
"region": "Oio",
"secteur": "Farim",
"localite": "Farim Centro",
"tailleMenage": 5,
"scorePmt": 0.42,
"eligibleProgramme": true
},
"statistiques": {
"totalPaiements": 12,
"paiementsReussis": 11,
"paiementsEchoues": 1,
"totalMontantRecu": 165000,
"nbProgrammes": 1,
"nbCycles": 12,
"nbPlaintes": 2,
"nbVerifications": 24,
"nbConformes": 23,
"nbNonConformes": 1,
"nbSuivis": 6
},
"programmes": [
{
"id": "...",
"code": "PCH-GB-001",
"nom": "PCH Guinee-Bissau",
"description": "Programme de transferts monetaires",
"statut": "actif",
"dateDebut": "2024-01-01",
"dateFin": "2026-12-31",
"montantParBeneficiaire": "15000"
}
],
"cycles": [
{
"id": "...",
"code": "PCH-GB-C012",
"nom": "Cycle Decembre 2024",
"statut": "termine",
"dateDebut": "2024-12-01",
"dateFin": "2024-12-31",
"montantParBeneficiaire": "15000",
"programmeId": "...",
"programmeNom": "PCH Guinee-Bissau"
}
],
"paiements": [
{
"id": "...",
"reference": "PAY-PCH-GB-C012-A1B2C3D4",
"montant": "15000",
"statut": "reussi",
"dateExecution": "2024-12-15T10:05:00+00:00",
"dateSoumission": "2024-12-15T10:00:00+00:00",
"cycle": {"id": "...", "code": "PCH-GB-C012", "nom": "Cycle Decembre 2024"},
"programme": {"id": "...", "code": "PCH-GB-001", "nom": "PCH Guinee-Bissau"}
}
],
"plaintes": [
{
"id": "...",
"reference": "PLT-2025-001234",
"categorie": "retard_paiement",
"description": "Paiement non recu",
"statut": "resolue",
"priorite": "moyenne",
"dateCreation": "2024-11-20T08:00:00+00:00",
"dateResolution": "2024-11-25T14:00:00+00:00",
"resolution": "Paiement effectue manuellement"
}
],
"conditionnalites": [
{
"id": "...",
"statut": "conforme",
"tauxConformite": 100,
"dateVerification": "2025-03-01T10:00:00+00:00",
"dateEcheance": "2025-03-31T23:59:59+00:00",
"commentaires": "Enfants scolarises",
"sourceVerification": "visite_terrain",
"conditionnalite": {
"id": "...",
"code": "SCOL-001",
"nom": "Scolarisation des enfants",
"categorie": "education"
},
"cycle": {"id": "...", "code": "PCH-GB-C012"}
}
],
"suivis": [
{
"id": "...",
"typeSuivi": "visite_domicile",
"dateSuivi": "2025-03-10T14:30:00+00:00",
"observations": "Conditions de vie ameliorees",
"latitude": 12.345,
"longitude": -15.678,
"agent": {"id": null, "nom": "Agent Terrain"}
}
],
"documentsIdentite": [
{
"id": "...",
"reference": "DOC-2025-001",
"typeDocument": "carte_identite",
"statut": "verifie",
"nomComplet": "Mamadou Diallo",
"dateNaissance": "1980-05-15",
"lieuNaissance": "Farim",
"sexe": "M",
"nomPere": "Ousmane Diallo",
"nomMere": "Fatou Sane",
"numeroDocument": "GB123456789",
"dateDelivrance": "2020-01-15",
"dateExpiration": "2030-01-14",
"dateDemande": "2020-01-01"
}
]
}
}
Creer un beneficiaire
Endpoint
POST /api/beneficiaires
Corps de la requete
{
"nomComplet": "Fatou Sane",
"menageId": "550e8400-e29b-41d4-a716-446655440001",
"programmeId": "550e8400-e29b-41d4-a716-446655440002",
"telephone": "+245955654321",
"modePaiement": "mobile_money",
"compteMobile": "+245955654321",
"actif": true
}
Champs requis
nomComplet: Nom complet du beneficiairemenageId: ID du menageprogrammeId: ID du programme
Detection de doublons
Si des doublons potentiels sont detectes avec un score >= 90%, l'API retourne une erreur 409 :
{
"success": false,
"error": "Doublons potentiels detectes",
"code": "DUPLICATES_DETECTED",
"data": {
"duplicates": [
{
"id": "...",
"nomComplet": "Fatou Sane",
"telephone": "+245955654321",
"score": 95,
"raisons": ["Meme telephone", "Nom similaire"]
}
],
"highRiskCount": 1,
"message": "Des doublons potentiels ont ete detectes. Utilisez forceCreate=true pour creer malgre tout."
}
}
Forcer la creation
{
"nomComplet": "Fatou Sane",
"menageId": "...",
"programmeId": "...",
"forceCreate": true
}
Verifier les doublons
Endpoint
POST /api/beneficiaires/check-duplicates
Corps de la requete
{
"nomComplet": "Mamadou Diallo",
"telephone": "+245955123456",
"menageId": "...",
"compteMobile": "+245955123456",
"excludeId": "..."
}
Reponse
{
"success": true,
"data": {
"hasDuplicates": true,
"count": 2,
"duplicates": [
{
"id": "...",
"nomComplet": "Mamadou Diallo",
"score": 85,
"raisons": ["Nom identique"]
}
],
"highRiskCount": 0,
"canCreate": true
}
}
Import depuis menages
Endpoint
POST /api/beneficiaires/import/from-menages
Description
Cree automatiquement des beneficiaires a partir des menages eligibles qui n'ont pas encore de beneficiaire.
Reponse
{
"success": true,
"message": "250 beneficiaires crees",
"data": {
"nbCreated": 250
}
}
Actions en masse
Endpoint
POST /api/beneficiaires/bulk-action
Corps de la requete
{
"ids": [
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
],
"action": "activer"
}
Actions disponibles
| Action | Description |
|---|---|
activer | Active les beneficiaires selectionnes |
desactiver | Desactive les beneficiaires selectionnes |
Reponse
{
"success": true,
"message": "5 beneficiaire(s) active(s), 0 erreur(s)",
"data": {
"success": 5,
"errors": 0,
"details": [
{"id": "...", "code": "BEN-OIO-2025-000001", "status": "ok"}
]
}
}
Statistiques
Endpoint
GET /api/beneficiaires/stats/summary
Parametres de requete
| Parametre | Type | Requis | Description |
|---|---|---|---|
projet | UUID | Non | Filtrer par projet |
region | UUID | Non | Filtrer par region |
secteur | UUID | Non | Filtrer par secteur |
localite | UUID | Non | Filtrer par localite |
Reponse
{
"success": true,
"data": {
"total": 3500,
"actifs": 3400,
"inactifs": 100,
"parModePaiement": {
"mobile_money": 3200,
"virement_bancaire": 200,
"especes": 100
}
}
}
Types de beneficiaires
| Type | Description |
|---|---|
principal | Beneficiaire principal du menage |
substitut | Beneficiaire substitut (peut recevoir en l'absence du principal) |
Statuts d'enrolement
| Statut | Description |
|---|---|
actif | Beneficiaire actif dans le programme |
suspendu | Temporairement suspendu |
sorti | Sorti du programme |
gradue | A complete le programme (graduation) |
Modes de paiement
| Mode | Description |
|---|---|
mobile_money | Paiement par mobile money |
virement_bancaire | Virement bancaire |
especes | Paiement en especes |