API Menages

L'API Menages permet de gerer les menages du registre social.

Vue d'ensemble

Endpoints CRUD

Endpoint	Methode	Description
/api/menages	GET	Liste des menages
/api/menages/{id}	GET	Detail d'un menage
/api/menages	POST	Creer un menage
/api/menages/{id}/update	POST	Modifier un menage
/api/menages/{id}	DELETE	Supprimer un menage
/api/menages/{id}/membres	GET	Membres du menage
/api/menages/{id}/membres/bulk	POST	Ajouter des membres en masse
/api/menages/{id}/validate	POST	Valider et inscrire au programme (registre.menages_validate)
/api/menages/{id}/reject	POST	Rejeter (motif obligatoire, registre.menages_reject)
/api/menages/{id}/validation-history	GET	Historique de validation

Endpoints Workflow Pre-Collecte

Endpoint	Methode	Description
/api/menages/pre-collecte	GET	Liste des menages en pre-collecte
/api/menages/pre-collecte/stats	GET	Statistiques pre-collecte
/api/menages/{id}/valider	POST	Valider la collecte (registre.menages_validate)
/api/menages/{id}/rejeter	POST	Rejeter la collecte (registre.menages_reject)
/api/menages/{id}/integrer	POST	Integrer dans le registre (registre.menages_validate)
/api/menages/valider-masse	POST	Validation en masse
/api/menages/integrer-masse	POST	Integration en masse

Endpoints PMT & Statistiques

Endpoint	Methode	Description
/api/menages/{id}/recalculate-pmt	POST	Recalculer le score PMT
/api/menages/recalculate-all-pmt	POST	Recalculer tous les PMT
/api/menages/bulk-recalculate-pmt	POST	Recalcul PMT en lot
/api/menages/stats/summary	GET	Statistiques globales

Endpoints Operations en Masse

Endpoint	Methode	Description
/api/menages/bulk-enroll	POST	Enrolement en masse comme beneficiaires
/api/menages/bulk-delete	POST	Suppression en masse
/api/menages/{id}/check-dependencies	GET	Verifier les dependances avant suppression

Modele de donnees

Champs principaux

Champ	Type	Description
id	UUID	Identifiant unique
codeMenage	string	Code unique du menage
statut	string	Statut principal (voir ci-dessous)
statutCollecte	string	Statut workflow collecte
milieu	string	Milieu (rural/urbain)
tailleMenage	int	Nombre de membres

Champs demographiques

Champ	Type	Description
nbEnfants04	int	Enfants 0-4 ans
nbEnfants514	int	Enfants 5-14 ans
nbEnfants010	int	Enfants 0-10 ans (alternatif)
nbEnfants1114	int	Enfants 11-14 ans (alternatif)
nbAdultes1564	int	Adultes 15-64 ans
nbPersonnes65Plus	int	Personnes 65+ ans
nbHandicapes	int	Personnes handicapees
nbActifsOccupes	int	Actifs occupes
nbFemmes1564	int	Femmes 15-64 ans
nbFemmes1549	int	Femmes 15-49 ans (age fertile)
nbFemmesEnceintes	int	Femmes enceintes

Champs PMT & Eligibilite

Champ	Type	Description
scorePmt	decimal	Score PMT calcule (0-100)
categoriePauvrete	string	Categorie de pauvrete
eligibleProgramme	boolean	Eligible au programme

Champs Qualite des Donnees

Champ	Type	Description
scoreQualite	decimal	Score qualite des donnees (0-100)
problemesQualite	JSON	Liste des problemes detectes
scoreDoublon	decimal	Score de similarite doublon
resumeDoublons	JSON	Details des doublons potentiels
dateAnalyseQualite	datetime	Date derniere analyse

Champs Geolocalisation

Champ	Type	Description
latitude	string	Latitude GPS
longitude	string	Longitude GPS
altitude	string	Altitude
precisionGps	string	Precision GPS en metres
region	object	Region
secteur	object	Secteur
localite	object	Localite

Champs Source & Synchronisation

Champ	Type	Description
sourceDonnees	string	Source des donnees
identifiantUnique	string	Identifiant unique externe
koboSubmissionId	string	ID soumission KoBoToolbox
koboFormUid	string	UID formulaire Kobo
koboValidationStatus	string	Statut sync Kobo
idSourceExterne	string	ID systeme externe
campagne	object	Campagne de collecte
enqueteur	object	Enqueteur assigne

Champs Validation

Champ	Type	Description
dateValidationCollecte	datetime	Date validation collecte
valideCollectePar	object	Utilisateur validateur
commentaireValidationCollecte	text	Commentaire validation
donneesValidation	JSON	Donnees validation
historiqueValidation	JSON	Historique validations

---

Statuts

Statut principal (statut)

Statut	Description
collecte	Donnees en cours de collecte
en_attente	En attente de validation
valide	Menage valide
rejete	Menage rejete

Statut collecte (statutCollecte)

Statut	Description
pre_collecte	Pre-collecte (avant validation UCP)
valide	Collecte validee
integre	Integre dans le registre
rejete	Collecte rejetee

---

Liste des menages

Endpoint

GET /api/menages

Parametres de requete

Parametre	Type	Requis	Description
page	int	Non	Numero de page (defaut: 1)
limit	int	Non	Elements par page (max: 100)
statut	string	Non	Filtrer par statut
statutCollecte	string	Non	Filtrer par statut collecte
search	string	Non	Recherche textuelle
region	UUID	Non	Filtrer par region
secteur	UUID	Non	Filtrer par secteur
localite	UUID	Non	Filtrer par localite
milieu	string	Non	Filtrer par milieu (urbain/rural)
eligible	boolean	Non	Filtrer par eligibilite
categoriePauvrete	string	Non	Filtrer par categorie
campagne	UUID	Non	Filtrer par campagne
enqueteur	UUID	Non	Filtrer par enqueteur
scorePmt[gte]	decimal	Non	PMT minimum
scorePmt[lte]	decimal	Non	PMT maximum
tailleMenage[gte]	int	Non	Taille minimum
tailleMenage[lte]	int	Non	Taille maximum

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "codeMenage": "MEN-OIO-001",
      "statut": "valide",
      "statutCollecte": "integre",
      "tailleMenage": 5,
      "scorePmt": 0.42,
      "scoreQualite": 95.5,
      "categoriePauvrete": "pauvre",
      "eligibleProgramme": true,
      "milieu": "rural",
      "region": {"id": "...", "nom": "Oio"},
      "secteur": {"id": "...", "nom": "Farim"},
      "localite": {"id": "...", "nom": "Farim Centro"},
      "chefMenage": {
        "id": "...",
        "nomComplet": "Mamadou Diallo",
        "sexe": "M",
        "age": 45
      },
      "campagne": {"id": "...", "nom": "Campagne 2024"},
      "enqueteur": {"id": "...", "nomComplet": "Fatou Sow"},
      "createdAt": "2024-06-15T10:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15000,
    "pages": 750
  }
}

---

Workflow Pre-Collecte

Le workflow pre-collecte permet de valider les donnees avant leur integration dans le registre officiel.

Liste des menages en pre-collecte

GET /api/menages/pre-collecte

Retourne les menages avec statutCollecte = 'pre_collecte'.

Statistiques pre-collecte

GET /api/menages/pre-collecte/stats

{
  "success": true,
  "data": {
    "total": 500,
    "enAttente": 450,
    "valides": 30,
    "rejetes": 20,
    "parCampagne": [
      {"campagne": "Campagne 2024", "total": 300},
      {"campagne": "Campagne 2023", "total": 200}
    ]
  }
}

Valider la collecte

POST /api/menages/{id}/valider

{
  "commentaire": "Donnees completes et coherentes"
}

Rejeter la collecte

POST /api/menages/{id}/rejeter

{
  "motif": "Donnees GPS manquantes"
}

motif est obligatoire (400 Le motif de rejet est obligatoire).

Integrer dans le registre

POST /api/menages/{id}/integrer

Passe le menage de pre_collecte a integre et met statut a valide.

Validation en masse

POST /api/menages/valider-masse

{
  "ids": ["uuid1", "uuid2", "uuid3"],
  "commentaire": "Validation lot 15 juin"
}

Integration en masse

POST /api/menages/integrer-masse

{
  "ids": ["uuid1", "uuid2", "uuid3"]
}

---

Detail d'un menage

Endpoint

GET /api/menages/{id}

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "codeMenage": "MEN-OIO-001",
    "statut": "valide",
    "statutCollecte": "integre",
    "milieu": "rural",
    "tailleMenage": 5,
    "nbEnfants04": 1,
    "nbEnfants514": 2,
    "nbEnfants010": 2,
    "nbEnfants1114": 1,
    "nbAdultes1564": 2,
    "nbPersonnes65Plus": 0,
    "nbHandicapes": 0,
    "nbActifsOccupes": 2,
    "nbFemmes1564": 1,
    "nbFemmes1549": 1,
    "nbFemmesEnceintes": 0,
    "scorePmt": 0.42,
    "categoriePauvrete": "pauvre",
    "eligibleProgramme": true,
    "scoreQualite": 95.5,
    "problemesQualite": [],
    "scoreDoublon": 0,
    "resumeDoublons": [],
    "dateAnalyseQualite": "2024-06-20T10:00:00+00:00",
    "latitude": "12.345678",
    "longitude": "-15.678901",
    "altitude": "25.5",
    "precisionGps": "5.0",
    "sourceDonnees": "kobo",
    "identifiantUnique": "MEN-2024-001",
    "koboSubmissionId": "abc123",
    "koboFormUid": "xyz789",
    "dateCollecte": "2024-06-15T10:00:00+00:00",
    "dateValidationCollecte": "2024-06-18T14:30:00+00:00",
    "region": {
      "id": "...",
      "nom": "Oio",
      "code": "OIO"
    },
    "secteur": {
      "id": "...",
      "nom": "Farim"
    },
    "localite": {
      "id": "...",
      "nom": "Farim Centro"
    },
    "campagne": {
      "id": "...",
      "nom": "Campagne Oio 2024"
    },
    "enqueteur": {
      "id": "...",
      "nomComplet": "Fatou Sow"
    },
    "chefMenage": {
      "id": "...",
      "nomComplet": "Mamadou Diallo",
      "sexe": "M",
      "age": 45,
      "niveauEducation": "primaire",
      "occupationPrincipale": "agriculture",
      "statutMatrimonial": "marie",
      "telephone": "+245955123456",
      "numeroMobileMoney": "+245955123456",
      "compteBancaire": null
    },
    "logement": {
      "id": "...",
      "typeLogement": "maison_individuelle",
      "statutOccupation": "proprietaire",
      "nbPieces": 3,
      "materiauMur": "brique_ciment",
      "materiauToit": "tole",
      "materiauSol": "ciment",
      "sourceEau": "puits_ameliore",
      "typeToilette": "latrine_amelioree",
      "sourceEclairage": "solaire",
      "combustibleCuisine": "bois",
      "traitementEau": "filtration",
      "evacuationDechets": "fosse",
      "aUneCuisine": true
    },
    "createdAt": "2024-06-15T10:00:00+00:00",
    "updatedAt": "2025-01-10T14:30:00+00:00"
  }
}

---

Operations en masse

Suppression en masse

POST /api/menages/bulk-delete

{
  "ids": ["uuid1", "uuid2", "uuid3"]
}

Note: Verifie les dependances avant suppression (beneficiaires, plaintes, visites sante, etc.)

Verifier les dependances

GET /api/menages/{id}/check-dependencies

{
  "success": true,
  "data": {
    "canDelete": false,
    "dependencies": {
      "beneficiaires": 2,
      "plaintes": 1,
      "visitesSante": 3,
      "mesuresAccompagnement": 5
    },
    "message": "Ce menage a des dependances et ne peut pas etre supprime"
  }
}

Enrolement en masse

POST /api/menages/bulk-enroll

{
  "ids": ["uuid1", "uuid2", "uuid3"],
  "programmeId": "uuid-programme"
}

Ajout de membres en masse

POST /api/menages/{id}/membres/bulk

{
  "membres": [
    {
      "nom": "Diallo",
      "prenom": "Aminata",
      "sexe": "F",
      "dateNaissance": "2010-05-15",
      "lienParente": "fille"
    },
    {
      "nom": "Diallo",
      "prenom": "Moussa",
      "sexe": "M",
      "dateNaissance": "2015-08-20",
      "lienParente": "fils"
    }
  ]
}

---

Recalculer le score PMT

Endpoint

POST /api/menages/{id}/recalculate-pmt

Description

Recalcule le score PMT (Proxy Means Test) pour un menage specifique en fonction de ses caracteristiques.

Reponse

{
  "success": true,
  "data": {
    "menageId": "550e8400-e29b-41d4-a716-446655440000",
    "codeMenage": "MEN-OIO-001",
    "oldScore": 0.45,
    "newScore": 0.42,
    "categoriePauvrete": "pauvre",
    "eligibleProgramme": true
  }
}

---

Statistiques des menages

Endpoint

GET /api/menages/stats/summary

Parametres de requete

Parametre	Type	Requis	Description
region	string	Non	Filtrer par nom de region
campagne	UUID	Non	Filtrer par campagne

Reponse

{
  "success": true,
  "data": {
    "general": {
      "total": 15000,
      "valides": 14500,
      "enAttente": 400,
      "rejetes": 100,
      "preCollecte": 200,
      "eligibles": 12000,
      "avecPmt": 14800,
      "pmtMoyen": 42.5,
      "totalPopulation": 75000,
      "tailleMoyenne": 5.0,
      "qualiteMoyenne": 92.3
    },
    "composition": {
      "totalEnfants04": 8000,
      "totalEnfants514": 12000,
      "totalEnfants010": 15000,
      "totalEnfants1114": 12000,
      "totalAdultes1564": 35000,
      "totalPersonnes65Plus": 3000,
      "totalHandicapes": 500,
      "totalActifs": 28000,
      "totalFemmes1564": 18000,
      "totalFemmes1549": 15000,
      "totalFemmesEnceintes": 800
    },
    "parStatut": {
      "valide": 14500,
      "en_attente": 400,
      "collecte": 0,
      "rejete": 100
    },
    "parStatutCollecte": {
      "pre_collecte": 200,
      "valide": 500,
      "integre": 14200,
      "rejete": 100
    },
    "parCategorie": {
      "extreme_pauvre": 3000,
      "pauvre": 9000,
      "vulnerable": 2000,
      "non_pauvre": 1000
    },
    "parMilieu": {
      "rural": 12000,
      "urbain": 3000
    },
    "parRegion": [
      {
        "id": "...",
        "nom": "Oio",
        "total": 5000,
        "valides": 4800,
        "enAttente": 150,
        "preCollecte": 50
      }
    ],
    "parCampagne": [
      {
        "id": "...",
        "nom": "Campagne 2024",
        "total": 3000,
        "valides": 2800
      }
    ]
  }
}

---

Categories de pauvrete

Categorie	Seuil PMT	Description
extreme_pauvre	< 20	Pauvrete extreme
pauvre	20-50	Pauvre
vulnerable	50-70	Vulnerable
non_pauvre	> 70	Non pauvre

Sources de donnees

Source	Description
kobo	Collecte via KoBoToolbox
survey_solutions	Collecte via Survey Solutions
manuel	Saisie manuelle
import	Import depuis fichier
migration	Migration depuis autre systeme

Codes d'erreur

Code	Statut HTTP	Description
NOT_FOUND	404	Menage non trouve
VALIDATION_ERROR	400	Donnees invalides
DUPLICATE_CODE	400	Code menage deja existant
HAS_DEPENDENCIES	400	Menage a des dependances
FORBIDDEN	403	Permission insuffisante
INVALID_STATUS	400	Transition de statut invalide