GET /api/beneficiaires

Recupera a lista paginada de beneficiários.

Endpoint

GET /api/beneficiaires

Headers

Header	Valor	Obrigatório
Authorization	Bearer {token}	Sim

Parâmetros de consulta

Paginação

Parâmetro	Tipo	Padrão	Descrição
page	integer	1	Número da página
itemsPerPage	integer	30	Elementos por página (máx: 100)

Filtros

Parâmetro	Tipo	Descrição
programme	IRI	Filtrar por programa (/api/programmes/1)
typeBeneficiaire	string	Tipo: principal ou substitut
statutCycle	string	Estado do ciclo de vida
actif	boolean	Beneficiário ativo (true/false)
documentVerifie	boolean	Documento de identidade verificado
search	string	Pesquisa textual (código, nome, telefone)
region	IRI	Filtrar por região do agregado familiar
commune	IRI	Filtrar por município do agregado familiar

Valores de statutCycle

Valor	Descrição
actif	Beneficiário ativo no programa
suspendu	Temporariamente suspenso
gradue	Concluiu o programa (graduado)
sorti	Saiu do programa
en_recertification	Em processo de recertificação

Ordenação

Parâmetro	Valores	Descrição
order[dateEnrolement]	asc, desc	Ordenar por data de inscrição
order[nomComplet]	asc, desc	Ordenar por nome
order[codeBeneficiaire]	asc, desc	Ordenar por código

Resposta de sucesso

Código: 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"
    }
}

Exemplos

cURL - Lista simples

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

cURL - Com filtros

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

cURL - Pesquisa

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();
};

// Utilização
const data = await getBeneficiaires({
    typeBeneficiaire: 'principal',
    statutCycle: 'actif',
    actif: true
});

console.log(`Total: ${data['hydra:totalItems']} beneficiários`);
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()

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

# Com filtros
beneficiaires = get_beneficiaires(
    token,
    typeBeneficiaire='principal',
    statutCycle='actif',
    actif='true'
)

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

Notas

• Os beneficiários estão vinculados a um agregado familiar (relação obrigatória)
• Um agregado familiar pode ter um beneficiário principal e um substituto
• O campo sexe é copiado do chefe do agregado familiar para facilitar as estatísticas
• A pesquisa textual funciona no código, nome e telefone