GET /api/beneficiaires/{id}

Récupère les informations détaillées d'un bénéficiaire.

Endpoint

GET /api/beneficiaires/{id}

Paramètres d'URL

Paramètre	Type	Description
id	UUID	Identifiant unique du bénéficiaire

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Réponse succès

Code: 200 OK

{
    "@context": "/api/contexts/Beneficiaire",
    "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
    "@type": "Beneficiaire",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "codeBeneficiaire": "BEN-2024-00001",
    "nomComplet": "Fatou Diallo",
    "telephone": "771234567",
    "modePaiement": "orange_money",
    "compteMobile": "771234567",
    "compteBancaire": null,
    "numeroMTN": null,
    "typeBeneficiaire": "principal",
    "actif": true,
    "sexe": "F",
    "statutEnrolement": "actif",
    "dateEnrolement": "2024-01-15T10:30:00+00:00",
    "dateSortie": null,
    "motifSortie": null,
    "documentVerifie": true,
    "dateVerificationDocument": "2024-01-20",
    "statutCycle": "actif",
    "prochaineRecertification": "2025-01-15",
    "estGradue": false,
    "dateGraduation": null,
    "tauxConformiteGlobal": "92.50",
    "nombreCyclesCompletes": 3,
    "dernierSuivi": "2024-06-15",
    "menage": {
        "@id": "/api/menages/1",
        "@type": "Menage",
        "id": 1,
        "codeMenage": "MEN-2024-00001",
        "tailleMenage": 5,
        "chefMenage": {
            "@id": "/api/chef_menages/1",
            "nomComplet": "Mamadou Diallo"
        },
        "region": {
            "@id": "/api/regions/1",
            "nom": "Oio"
        },
        "secteur": {
            "@id": "/api/secteurs/1",
            "nom": "Farim"
        }
    },
    "programme": {
        "@id": "/api/programmes/1",
        "@type": "Programme",
        "id": 1,
        "nom": "Transferts Monétaires 2024",
        "code": "TM-2024"
    },
    "beneficiairePrincipal": null
}

Réponses erreur

404 Not Found

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Item not found for \"/api/beneficiaires/invalid-uuid\""
}

403 Forbidden

{
    "@context": "/api/contexts/Error",
    "@type": "hydra:Error",
    "hydra:title": "An error occurred",
    "hydra:description": "Access Denied."
}

Exemples

cURL

curl https://sig.example.com/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getBeneficiaire = async (id) => {
    const response = await fetch(
        `https://sig.example.com/api/beneficiaires/${id}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    if (response.status === 404) {
        throw new Error('Bénéficiaire non trouvé');
    }

    return response.json();
};

// Utilisation
try {
    const beneficiaire = await getBeneficiaire('550e8400-e29b-41d4-a716-446655440000');
    console.log(`Nom: ${beneficiaire.nomComplet}`);
    console.log(`Type: ${beneficiaire.typeBeneficiaire}`);
    console.log(`Statut: ${beneficiaire.statutCycle}`);
    console.log(`Cycles complétés: ${beneficiaire.nombreCyclesCompletes}`);
    console.log(`Ménage: ${beneficiaire.menage.codeMenage}`);
} catch (error) {
    console.error(error.message);
}

Python

import requests

def get_beneficiaire(token, beneficiaire_id):
    response = requests.get(
        f'https://sig.example.com/api/beneficiaires/{beneficiaire_id}',
        headers={'Authorization': f'Bearer {token}'}
    )

    if response.status_code == 404:
        raise Exception('Bénéficiaire non trouvé')

    return response.json()

# Utilisation
beneficiaire = get_beneficiaire(token, '550e8400-e29b-41d4-a716-446655440000')
print(f"Code: {beneficiaire['codeBeneficiaire']}")
print(f"Nom: {beneficiaire['nomComplet']}")
print(f"Mode paiement: {beneficiaire['modePaiement']}")
print(f"Conformité: {beneficiaire['tauxConformiteGlobal']}%")

Champs de la réponse

Identité

Champ	Type	Description
id	UUID	Identifiant unique
codeBeneficiaire	string	Code unique (BEN-YYYY-NNNNN)
nomComplet	string	Nom complet du bénéficiaire
telephone	string	Numéro de téléphone
sexe	string	"M" ou "F"

Paiement

Champ	Type	Description
modePaiement	string	Mode de paiement (orange_money, wave, etc.)
compteMobile	string	Numéro de compte Mobile Money
compteBancaire	string	Numéro de compte bancaire
numeroMTN	string	Numéro MTN Mobile Money

Type et statut

Champ	Type	Description
typeBeneficiaire	string	"principal" ou "substitut"
actif	boolean	Bénéficiaire actif
statutEnrolement	string	Statut d'enrôlement
statutCycle	string	Statut dans le cycle de vie
documentVerifie	boolean	Document d'identité vérifié

Cycle de vie

Champ	Type	Description
dateEnrolement	datetime	Date d'enrôlement
prochaineRecertification	date	Date de prochaine recertification
estGradue	boolean	A terminé le programme
dateGraduation	date	Date de graduation
nombreCyclesCompletes	integer	Nombre de cycles de paiement complétés
tauxConformiteGlobal	decimal	Taux de conformité aux conditionnalités (0-100)
dernierSuivi	date	Date du dernier suivi terrain

Notes

• Les identifiants de bénéficiaires sont des UUID
• Le bénéficiaire substitut référence son bénéficiaire principal via beneficiairePrincipal
• Le taux de conformité est calculé sur toutes les conditionnalités du programme
• La recertification est obligatoire périodiquement pour maintenir l'éligibilité

---

Retrait, désactivation et réactivation

Trois actions, toutes avec la permission registre.beneficiaires_edit et la vérification du périmètre de l'utilisateur (403 si le bénéficiaire en sort, 404 s'il n'existe pas).

Méthode	Endpoint	Effet
POST	/api/beneficiaires/{id}/unenroll	Retire le bénéficiaire de son programme sans le supprimer
POST	/api/beneficiaires/{id}/deactivate	Passe actif à false
POST	/api/beneficiaires/{id}/activate	Repasse actif à true

POST /api/beneficiaires/{id}/unenroll

Corps optionnel :

{ "motif": "demenagement" }

Le bénéficiaire perd son programme et sa date d'enrôlement. Si un motif est fourni, il est enregistré comme motif de sortie avec la date du jour. L'opération est tracée dans le journal d'audit.

{ "success": true, "message": "Bénéficiaire retiré du programme \"Programme exemple\"" }

Erreur 400 si le bénéficiaire n'est enrôlé dans aucun programme : Ce bénéficiaire n'est enrôlé dans aucun programme.

Un bénéficiaire retiré n'entre plus dans les transferts suivants ; il peut être réenrôlé plus tard, et son historique de paiements est conservé.

curl -X POST "https://sig.example.com/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000/unenroll" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"motif": "demenagement"}'