Pular para o conteúdo principal

API Menages

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

Vue d'ensemble​

Endpoints CRUD​

EndpointMethodeDescription
/api/menagesGETListe des menages
/api/menages/{id}GETDetail d'un menage
/api/menagesPOSTCreer un menage
/api/menages/{id}/updatePOSTModifier un menage
/api/menages/{id}DELETESupprimer un menage
/api/menages/{id}/membresGETMembres du menage
/api/menages/{id}/bulk-add-membresPOSTAjouter des membres en masse

Endpoints Workflow Pre-Collecte​

EndpointMethodeDescription
/api/menages/pre-collecteGETListe des menages en pre-collecte
/api/menages/pre-collecte/statsGETStatistiques pre-collecte
/api/menages/{id}/validate-collectePOSTValider la collecte
/api/menages/{id}/reject-collectePOSTRejeter la collecte
/api/menages/{id}/integrate-collectePOSTIntegrer dans le registre
/api/menages/valider-massePOSTValidation en masse
/api/menages/integrer-massePOSTIntegration en masse

Endpoints PMT & Statistiques​

EndpointMethodeDescription
/api/menages/{id}/recalculate-pmtPOSTRecalculer le score PMT
/api/menages/recalculate-all-pmtPOSTRecalculer tous les PMT
/api/menages/bulk-recalculate-pmtPOSTRecalcul PMT en lot
/api/menages/stats/summaryGETStatistiques globales

Endpoints Operations en Masse​

EndpointMethodeDescription
/api/menages/bulk-enrollPOSTEnrolement en masse comme beneficiaires
/api/menages/bulk-deletePOSTSuppression en masse
/api/menages/{id}/check-dependenciesGETVerifier les dependances avant suppression

Modele de donnees​

Champs principaux​

ChampTypeDescription
idUUIDIdentifiant unique
codeMenagestringCode unique du menage
statutstringStatut principal (voir ci-dessous)
statutCollectestringStatut workflow collecte
milieustringMilieu (rural/urbain)
tailleMenageintNombre de membres

Champs demographiques​

ChampTypeDescription
nbEnfants04intEnfants 0-4 ans
nbEnfants514intEnfants 5-14 ans
nbEnfants010intEnfants 0-10 ans (alternatif)
nbEnfants1114intEnfants 11-14 ans (alternatif)
nbAdultes1564intAdultes 15-64 ans
nbPersonnes65PlusintPersonnes 65+ ans
nbHandicapesintPersonnes handicapees
nbActifsOccupesintActifs occupes
nbFemmes1564intFemmes 15-64 ans
nbFemmes1549intFemmes 15-49 ans (age fertile)
nbFemmesEnceintesintFemmes enceintes

Champs PMT & Eligibilite​

ChampTypeDescription
scorePmtdecimalScore PMT calcule (0-100)
categoriePauvretestringCategorie de pauvrete
eligibleProgrammebooleanEligible au programme

Champs Qualite des Donnees​

ChampTypeDescription
scoreQualitedecimalScore qualite des donnees (0-100)
problemesQualiteJSONListe des problemes detectes
scoreDoublondecimalScore de similarite doublon
resumeDoublonsJSONDetails des doublons potentiels
dateAnalyseQualitedatetimeDate derniere analyse

Champs Geolocalisation​

ChampTypeDescription
latitudestringLatitude GPS
longitudestringLongitude GPS
altitudestringAltitude
precisionGpsstringPrecision GPS en metres
regionobjectRegion
secteurobjectSecteur
localiteobjectLocalite

Champs Source & Synchronisation​

ChampTypeDescription
sourceDonneesstringSource des donnees
identifiantUniquestringIdentifiant unique externe
koboSubmissionIdstringID soumission KoBoToolbox
koboFormUidstringUID formulaire Kobo
koboValidationStatusstringStatut sync Kobo
idSourceExternestringID systeme externe
campagneobjectCampagne de collecte
enqueteurobjectEnqueteur assigne

Champs Validation​

ChampTypeDescription
dateValidationCollectedatetimeDate validation collecte
valideCollecteParobjectUtilisateur validateur
commentaireValidationCollectetextCommentaire validation
donneesValidationJSONDonnees validation
historiqueValidationJSONHistorique validations

Statuts​

Statut principal (statut)​

StatutDescription
collecteDonnees en cours de collecte
en_attenteEn attente de validation
valideMenage valide
rejeteMenage rejete

Statut collecte (statutCollecte)​

StatutDescription
pre_collectePre-collecte (avant validation UCP)
valideCollecte validee
integreIntegre dans le registre
rejeteCollecte rejetee

Liste des menages​

Endpoint​

GET /api/menages

Parametres de requete​

ParametreTypeRequisDescription
pageintNonNumero de page (defaut: 1)
limitintNonElements par page (max: 100)
statutstringNonFiltrer par statut
statutCollectestringNonFiltrer par statut collecte
searchstringNonRecherche textuelle
regionUUIDNonFiltrer par region
secteurUUIDNonFiltrer par secteur
localiteUUIDNonFiltrer par localite
milieustringNonFiltrer par milieu (urbain/rural)
eligiblebooleanNonFiltrer par eligibilite
categoriePauvretestringNonFiltrer par categorie
campagneUUIDNonFiltrer par campagne
enqueteurUUIDNonFiltrer par enqueteur
scorePmt[gte]decimalNonPMT minimum
scorePmt[lte]decimalNonPMT maximum
tailleMenage[gte]intNonTaille minimum
tailleMenage[lte]intNonTaille 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}/validate-collecte
{
  "commentaire": "Donnees completes et coherentes"
}

Rejeter la collecte​

POST /api/menages/{id}/reject-collecte
{
  "commentaire": "Donnees GPS manquantes",
  "motif": "donnees_incompletes"
}

Integrer dans le registre​

POST /api/menages/{id}/integrate-collecte

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}/bulk-add-membres
{
  "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​

ParametreTypeRequisDescription
regionstringNonFiltrer par nom de region
campagneUUIDNonFiltrer 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​

CategorieSeuil PMTDescription
extreme_pauvre< 20Pauvrete extreme
pauvre20-50Pauvre
vulnerable50-70Vulnerable
non_pauvre> 70Non pauvre

Sources de donnees​

SourceDescription
koboCollecte via KoBoToolbox
survey_solutionsCollecte via Survey Solutions
manuelSaisie manuelle
importImport depuis fichier
migrationMigration depuis autre systeme

Codes d'erreur​

CodeStatut HTTPDescription
NOT_FOUND404Menage non trouve
VALIDATION_ERROR400Donnees invalides
DUPLICATE_CODE400Code menage deja existant
HAS_DEPENDENCIES400Menage a des dependances
FORBIDDEN403Permission insuffisante
INVALID_STATUS400Transition de statut invalide