GET /api/menages

Obtem a lista paginada de agregados familiares.

Endpoint

GET /api/menages

Headers

Header	Valor	Obrigatorio
Authorization	Bearer {token}	Sim

Parametros de consulta

Paginacao

Parametro	Tipo	Padrao	Descricao
page	integer	1	Numero da pagina
itemsPerPage	integer	30	Elementos por pagina (max: 100)

Filtros

Parametro	Tipo	Descricao
region	IRI	Filtrar por regiao (/api/regions/1)
secteur	IRI	Filtrar por setor
commune	IRI	Filtrar por municipio
localite	IRI	Filtrar por localidade
statut	string	Filtrar por estado (actif, inactif, en_attente)
search	string	Pesquisa textual (codigo, nome do chefe)

Ordenacao

Parametro	Valores	Descricao
order[createdAt]	asc, desc	Ordenar por data de criacao
order[codeMenage]	asc, desc	Ordenar por codigo do agregado
order[scorePmt]	asc, desc	Ordenar por pontuacao PMT

Resposta de sucesso

Codigo: 200 OK

{
    "@context": "/api/contexts/Menage",
    "@id": "/api/menages",
    "@type": "hydra:Collection",
    "hydra:totalItems": 1234,
    "hydra:member": [
        {
            "@id": "/api/menages/1",
            "@type": "Menage",
            "id": 1,
            "codeMenage": "MEN-2024-00001",
            "tailleMenage": 5,
            "scorePmt": "45.67",
            "statut": "actif",
            "chefMenage": {
                "@id": "/api/chef_menages/1",
                "nomComplet": "Mamadou Diallo",
                "sexe": "M",
                "telephone": "771234567"
            },
            "region": {
                "@id": "/api/regions/1",
                "nom": "Dakar"
            },
            "secteur": {
                "@id": "/api/secteurs/1",
                "nom": "Secteur 1"
            },
            "commune": {
                "@id": "/api/communes/1",
                "nom": "Commune 1"
            },
            "createdAt": "2024-01-15T10:30:00+00:00"
        }
    ],
    "hydra:view": {
        "@id": "/api/menages?page=1",
        "@type": "hydra:PartialCollectionView",
        "hydra:first": "/api/menages?page=1",
        "hydra:last": "/api/menages?page=42",
        "hydra:next": "/api/menages?page=2"
    },
    "hydra:search": {
        "@type": "hydra:IriTemplate",
        "hydra:template": "/api/menages{?search,region,secteur,commune,localite,statut}",
        "hydra:variableRepresentation": "BasicRepresentation",
        "hydra:mapping": [
            {"@type": "IriTemplateMapping", "variable": "search", "property": "search"}
        ]
    }
}

Exemplos

cURL - Lista simples

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

cURL - Com filtros

curl "https://sig.ucp-pch.org/api/menages?region=/api/regions/1&statut=actif&page=2" \
  -H "Authorization: Bearer TOKEN"

cURL - Com pesquisa

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

JavaScript

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

    if (filters.region) params.append('region', filters.region);
    if (filters.statut) params.append('statut', filters.statut);
    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/menages?${params}`,
        {
            headers: {
                'Authorization': `Bearer ${localStorage.getItem('token')}`
            }
        }
    );

    return response.json();
};

// Utilizacao
const data = await getMenages({
    region: '/api/regions/1',
    statut: 'actif',
    page: 1
});

console.log(`Total: ${data['hydra:totalItems']} agregados familiares`);
data['hydra:member'].forEach(menage => {
    console.log(menage.codeMenage, menage.chefMenage.nomComplet);
});

Python

import requests

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

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

# Com filtros
menages = get_menages(
    token,
    region='/api/regions/1',
    statut='actif',
    page=2
)

Notas

• Os resultados sao paginados por padrao (30 elementos)
• A pesquisa textual (search) pesquisa no codigo do agregado e no nome do chefe
• Os filtros geograficos utilizam IRIs (ex: /api/regions/1)
• As relacoes (chefMenage, region) sao incluidas na resposta