GET /api/beneficiaires

Récupère la liste paginée des bénéficiaires.

Endpoint

GET /api/beneficiaires

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Paramètres de requête

Pagination

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de page
itemsPerPage	integer	30	Éléments par page (max: 100)

Filtres

Paramètre	Type	Description
programme	IRI	Filtrer par programme (/api/programmes/1)
typeBeneficiaire	string	Type: principal ou substitut
statutCycle	string	Statut du cycle de vie
actif	boolean	Bénéficiaire actif (true/false)
documentVerifie	boolean	Document d'identité vérifié
search	string	Recherche textuelle (code, nom, téléphone)
region	IRI	Filtrer par région du ménage
commune	IRI	Filtrer par commune du ménage

Valeurs de statutCycle

Valeur	Description
actif	Bénéficiaire actif dans le programme
suspendu	Temporairement suspendu
gradue	A terminé le programme (gradué)
sorti	Sorti du programme
en_recertification	En cours de recertification

Tri

Paramètre	Valeurs	Description
order[dateEnrolement]	asc, desc	Trier par date d'enrôlement
order[nomComplet]	asc, desc	Trier par nom
order[codeBeneficiaire]	asc, desc	Trier par code

Réponse succès

Code: 200 OK

{
    "@context": "/api/contexts/Beneficiaire",
    "@id": "/api/beneficiaires",
    "@type": "hydra:Collection",
    "hydra:totalItems": 856,
    "hydra:member": [
        {
            "@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",
            "typeBeneficiaire": "principal",
            "statutCycle": "actif",
            "actif": true,
            "documentVerifie": true,
            "sexe": "F",
            "nombreCyclesCompletes": 3,
            "menage": {
                "@id": "/api/menages/1",
                "codeMenage": "MEN-2024-00001"
            },
            "programme": {
                "@id": "/api/programmes/1",
                "nom": "Transferts Monétaires 2024"
            },
            "dateEnrolement": "2024-01-15T10:30:00+00:00"
        }
    ],
    "hydra:view": {
        "@id": "/api/beneficiaires?page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/beneficiaires?page=1",
        "hydra:last": "/api/beneficiaires?page=29",
        "hydra:next": "/api/beneficiaires?page=2"
    }
}

Exemples

cURL - Liste simple

curl https://sig.ucp-pch.org/api/beneficiaires \
  -H "Authorization: Bearer TOKEN"

cURL - Avec filtres

curl "https://sig.ucp-pch.org/api/beneficiaires?typeBeneficiaire=principal&statutCycle=actif&actif=true" \
  -H "Authorization: Bearer TOKEN"

cURL - Recherche

curl "https://sig.ucp-pch.org/api/beneficiaires?search=Diallo" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getBeneficiaires = async (filters = {}) => {
    const params = new URLSearchParams();

    if (filters.programme) params.append('programme', filters.programme);
    if (filters.typeBeneficiaire) params.append('typeBeneficiaire', filters.typeBeneficiaire);
    if (filters.statutCycle) params.append('statutCycle', filters.statutCycle);
    if (filters.actif !== undefined) params.append('actif', filters.actif);
    if (filters.search) params.append('search', filters.search);
    if (filters.page) params.append('page', filters.page);

    const response = await fetch(
        `https://sig.ucp-pch.org/api/beneficiaires?${params}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    return response.json();
};

// Utilisation
const data = await getBeneficiaires({
    typeBeneficiaire: 'principal',
    statutCycle: 'actif',
    actif: true
});

console.log(`Total: ${data['hydra:totalItems']} bénéficiaires`);
data['hydra:member'].forEach(ben => {
    console.log(`${ben.codeBeneficiaire} - ${ben.nomComplet}`);
});

Python

import requests

def get_beneficiaires(token, **filters):
    response = requests.get(
        'https://sig.ucp-pch.org/api/beneficiaires',
        headers={'Authorization': f'Bearer {token}'},
        params=filters
    )
    return response.json()

# Liste simple
beneficiaires = get_beneficiaires(token)
print(f"Total: {beneficiaires['hydra:totalItems']}")

# Avec filtres
beneficiaires = get_beneficiaires(
    token,
    typeBeneficiaire='principal',
    statutCycle='actif',
    actif='true'
)

for ben in beneficiaires['hydra:member']:
    print(f"- {ben['codeBeneficiaire']}: {ben['nomComplet']}")

Notes

• Les bénéficiaires sont liés à un ménage (relation obligatoire)
• Un ménage peut avoir un bénéficiaire principal et un substitut
• Le champ sexe est copié depuis le chef de ménage pour faciliter les statistiques
• La recherche textuelle fonctionne sur le code, le nom et le téléphone