Secteurs

Les secteurs sont le deuxième niveau de la hiérarchie géographique, rattachés à une région.

Hiérarchie géographique

Région → Secteur → Localité
         ^^^^^^^^

GET /api/geo/secteurs

Récupère la liste des secteurs avec pagination.

Endpoint

GET /api/geo/secteurs

Headers

Header	Valeur	Requis
Authorization	Bearer {token}	Oui

Paramètres de requête

Paramètre	Type	Défaut	Description
page	integer	1	Numéro de la page
limit	integer	50	Nombre d'éléments par page (max: 100)
search	string	-	Recherche par nom ou code
regionId	UUID	-	Filtrer par région
region	UUID	-	Alias pour regionId

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": [
        {
            "id": "aa0e8400-e29b-41d4-a716-446655440001",
            "nom": "Contuboel",
            "code": "CTB",
            "latitude": 12.3833,
            "longitude": -14.5333,
            "regionId": "990e8400-e29b-41d4-a716-446655440001",
            "regionNom": "Bafatá",
            "nbMenages": 450
        },
        {
            "id": "aa0e8400-e29b-41d4-a716-446655440002",
            "nom": "Mansabá",
            "code": "MSB",
            "latitude": 12.1167,
            "longitude": -15.2833,
            "regionId": "990e8400-e29b-41d4-a716-446655440002",
            "regionNom": "Oio",
            "nbMenages": 320
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 25,
        "pages": 1
    }
}

Champs de réponse

Champ	Type	Description
id	UUID	Identifiant unique
nom	string	Nom du secteur
code	string|null	Code du secteur
latitude	float|null	Latitude du centroïde
longitude	float|null	Longitude du centroïde
regionId	UUID|null	Identifiant de la région parente
regionNom	string|null	Nom de la région parente
nbMenages	integer	Nombre de ménages dans le secteur

Pagination

Champ	Type	Description
page	integer	Page courante
limit	integer	Éléments par page
total	integer	Nombre total d'éléments
pages	integer	Nombre total de pages

---

GET /api/geo/secteurs/{id}

Récupère un secteur par son identifiant.

Endpoint

GET /api/geo/secteurs/{id}

Réponse succès

Code: 200 OK

{
    "success": true,
    "data": {
        "id": "aa0e8400-e29b-41d4-a716-446655440001",
        "nom": "Contuboel",
        "code": "CTB",
        "latitude": 12.3833,
        "longitude": -14.5333,
        "regionId": "990e8400-e29b-41d4-a716-446655440001",
        "regionNom": "Bafatá"
    }
}

Réponse erreur

Code: 404 Not Found

{
    "success": false,
    "error": "Not found"
}

---

POST /api/geo/secteurs

Crée un nouveau secteur (ADMIN ou permission secteurs.create).

Endpoint

POST /api/geo/secteurs

Corps de la requête

{
    "nom": "Nouveau Secteur",
    "code": "NS01",
    "latitude": 12.5,
    "longitude": -14.8,
    "regionId": "990e8400-e29b-41d4-a716-446655440001"
}

Champs

Champ	Type	Requis	Description
nom	string	Oui	Nom du secteur
code	string	Non	Code du secteur
latitude	number	Non	Latitude du centroïde
longitude	number	Non	Longitude du centroïde
regionId	UUID	Non	Identifiant de la région parente

Réponse succès

Code: 201 Created

{
    "success": true,
    "data": {
        "id": "aa0e8400-e29b-41d4-a716-446655440003"
    }
}

---

PUT /api/geo/secteurs/{id}

Modifie un secteur (ADMIN ou permission secteurs.edit).

Endpoint

PUT /api/geo/secteurs/{id}
PATCH /api/geo/secteurs/{id}

Corps de la requête

{
    "nom": "Secteur Modifié",
    "regionId": "990e8400-e29b-41d4-a716-446655440002"
}

Réponse succès

Code: 200 OK

{
    "success": true
}

---

DELETE /api/geo/secteurs/{id}

Supprime un secteur (ADMIN ou permission secteurs.delete).

Endpoint

DELETE /api/geo/secteurs/{id}

Réponse succès

Code: 200 OK

{
    "success": true
}

---

Exemples

cURL - Liste avec pagination

# Première page de 10 éléments
curl "https://mariacare.ucp-pch.org/api/geo/secteurs?page=1&limit=10" \
  -H "Authorization: Bearer TOKEN"

# Secteurs d'une région spécifique
curl "https://mariacare.ucp-pch.org/api/geo/secteurs?regionId=990e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

# Recherche par nom
curl "https://mariacare.ucp-pch.org/api/geo/secteurs?search=contuboel" \
  -H "Authorization: Bearer TOKEN"

cURL - Secteur par ID

curl "https://mariacare.ucp-pch.org/api/geo/secteurs/aa0e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer TOKEN"

JavaScript

const getSecteurs = async (options = {}) => {
    const { page = 1, limit = 50, search = '', regionId = null } = options;

    const params = new URLSearchParams({
        page: page.toString(),
        limit: limit.toString()
    });

    if (search) params.append('search', search);
    if (regionId) params.append('regionId', regionId);

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

// Tous les secteurs avec pagination
const allSecteurs = await getSecteurs({ page: 1, limit: 10 });
console.log(`Total secteurs: ${allSecteurs.pagination.total}`);

// Secteurs d'une région
const secteursBafata = await getSecteurs({
    regionId: '990e8400-e29b-41d4-a716-446655440001'
});

secteursBafata.data.forEach(secteur => {
    console.log(`${secteur.nom} (${secteur.regionNom}) - ${secteur.nbMenages} ménages`);
});

Python

import requests

def get_secteurs(token, page=1, limit=50, search=None, region_id=None):
    params = {'page': page, 'limit': limit}
    if search:
        params['search'] = search
    if region_id:
        params['regionId'] = region_id

    response = requests.get(
        'https://mariacare.ucp-pch.org/api/geo/secteurs',
        headers={'Authorization': f'Bearer {token}'},
        params=params
    )
    return response.json()

# Tous les secteurs
result = get_secteurs(token, page=1, limit=10)
print(f"Total: {result['pagination']['total']}")

# Secteurs d'une région
secteurs_bafata = get_secteurs(
    token,
    region_id='990e8400-e29b-41d4-a716-446655440001'
)

for s in secteurs_bafata['data']:
    print(f"- {s['nom']} ({s['regionNom']}) - {s['nbMenages']} ménages")

Permissions

Action	Permission requise
Lecture	ROLE_USER + (ROLE_ADMIN ou secteurs.view)
Création	ROLE_ADMIN ou secteurs.create
Modification	ROLE_ADMIN ou secteurs.edit
Suppression	ROLE_ADMIN ou secteurs.delete

Notes

• Les secteurs sont le niveau intermédiaire entre les régions et les localités
• Un secteur peut être rattaché à une région (champ regionId)
• Le champ nbMenages compte les ménages directement associés à ce secteur
• La recherche est insensible à la casse et filtre par nom ou code
• Les résultats sont triés par nom de région puis par nom de secteur