Documentation API — Modules Transverses & Administration¶

Pilotage, Référentiels, Administration, Audit, Rapports, Synchronisation, Import Excel

Table des matières¶

Module Pilotage — 12 routes
Module Référentiels — 20 routes
Module Administration — 7 routes
Module Audit — 2 routes
Module Audit Référentiel — 8 routes
Module Rapports — 7 routes
Module Synchronisation — 2 routes
Module Import Excel — 1 route

Module Pilotage¶

Préfixe : /api/v1/pilotage | Controller : PilotageModuleController
3 entités : Études diagnostiques, Indicateurs de suivi, Mesures.

Études Diagnostiques¶

GET /api/v1/pilotage/etudes¶

Description : Lister les études diagnostiques
Permission : ETUDE_LIRE
Authentification : Requise

Paramètres query

Champ	Type	Description
`statut`	`EN_COURS` \| `FINALISEE` \| `VALIDEE`	Filtrer par statut
`communeCode`	string	Filtrer par commune
`recherche`	string	Recherche textuelle (titre)
`page`	number	Numéro de page
`limite`	number	Nb par page

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "items": [ { "id": "cuid", "titre": "Étude diagnostique zone nord", "statut": "EN_COURS", "dateDebut": "2024-01-01", "communes": ["COT", "ABE"] } ],
    "total": 3, "page": 1, "limite": 20
  }
}

Use Case associé : ListerEtudesUseCase.ts

POST /api/v1/pilotage/etudes¶

Description : Créer une étude diagnostique
Permission : ETUDE_CREER
Authentification : Requise

Données d'entrée

Champ	Type	Obligatoire	Description
`titre`	string	Oui	Titre de l'étude
`dateDebut`	string (ISO)	Oui	Date de début
`dateFin`	string (ISO)	Non	Date de fin prévue
`statut`	`EN_COURS` \| `FINALISEE` \| `VALIDEE`	Non	Statut (défaut: EN_COURS)
`rapport`	string	Non	URL ou référence du rapport
`communes`	string[]	Oui	Codes des communes couvertes
`observations`	string	Non	Observations

Réponse succès (HTTP 201)

{
  "succes": true,
  "donnees": { "id": "cuid", "titre": "...", "statut": "EN_COURS", "communes": [...] }
}

Codes d'erreur

Code	HTTP	Signification
`DONNEES_INVALIDES`	400	Champs obligatoires manquants
`ERREUR_SERVEUR`	500	Erreur technique

Use Case associé : CreerEtudeUseCase.ts

GET /api/v1/pilotage/etudes/:id¶

Description : Obtenir une étude diagnostique par son ID
Permission : ETUDE_LIRE | Use Case : ObtenirEtudeUseCase.ts

PUT /api/v1/pilotage/etudes/:id¶

Description : Modifier une étude diagnostique
Permission : ETUDE_CREER

Données d'entrée : Mêmes champs que POST, tous optionnels

Use Case associé : ModifierEtudeUseCase.ts

DELETE /api/v1/pilotage/etudes/:id¶

Description : Supprimer une étude diagnostique
Permission : ETUDE_CREER | Use Case : SupprimerEtudeUseCase.ts

Indicateurs de suivi¶

GET /api/v1/pilotage/indicateurs¶

Description : Lister les indicateurs de suivi
Permission : INDICATEUR_LIRE

Paramètres query : recherche, page, limite

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "items": [ { "id": "cuid", "code": "IND-001", "libelle": "Nb enfants identifiés", "resultatRef": "R1", "valeurCible": "500", "unite": "enfants" } ],
    "total": 12
  }
}

Use Case associé : ListerIndicateursUseCase.ts

POST /api/v1/pilotage/indicateurs¶

Description : Créer un indicateur de suivi
Permission : INDICATEUR_SAISIR

Données d'entrée

Champ	Type	Obligatoire	Description
`code`	string	Oui	Code unique de l'indicateur (ex: IND-001)
`libelle`	string	Oui	Libellé de l'indicateur
`resultatRef`	string	Oui	Résultat de référence du cadre logique
`valeurRef`	string	Non	Valeur de référence (baseline)
`valeurCible`	string	Non	Valeur cible
`unite`	string	Non	Unité de mesure

Codes d'erreur

Code	HTTP	Signification
`INDICATEUR_CODE_EXISTANT`	409	Code déjà utilisé
`DONNEES_INVALIDES`	400	Champs invalides

Use Case associé : CreerIndicateurUseCase.ts

GET /api/v1/pilotage/indicateurs/:id¶

Description : Obtenir un indicateur par son ID
Permission : INDICATEUR_LIRE | Use Case : ObtenirIndicateurUseCase.ts

PUT /api/v1/pilotage/indicateurs/:id¶

Description : Modifier un indicateur
Permission : INDICATEUR_SAISIR

Note : Le code n'est pas modifiable (clé métier).

Use Case associé : ModifierIndicateurUseCase.ts

Mesures des indicateurs¶

GET /api/v1/pilotage/mesures¶

Description : Lister les mesures (filtrer par indicateur et/ou période)
Permission : INDICATEUR_LIRE

Paramètres query

Champ	Type	Description
`indicateurId`	string (CUID)	Filtrer par indicateur
`periode`	string	Filtrer par période (ex: "2024-T1")
`page`	number	Numéro de page
`limite`	number	Nb par page

POST /api/v1/pilotage/mesures¶

Description : Saisir une mesure — upsert par indicateurId + periode
Permission : INDICATEUR_SAISIR

Données d'entrée

Champ	Type	Obligatoire	Description
`indicateurId`	string (CUID)	Oui	ID de l'indicateur
`valeur`	string	Oui	Valeur mesurée
`dateMesure`	string (ISO)	Oui	Date de la mesure
`sourceVerif`	string	Non	Source de vérification
`periode`	string	Non	Période (ex: "2024-T1", "2024-S1")

Codes d'erreur

Code	HTTP	Signification
`INDICATEUR_INTROUVABLE`	404	Indicateur inexistant
`PERIODE_EXISTANTE`	409	Mesure déjà saisie pour cette période

Use Case associé : SaisirMesureUseCase.ts

GET /api/v1/pilotage/mesures/:id¶

Description : Obtenir une mesure par son ID
Permission : INDICATEUR_LIRE | Use Case : ObtenirMesureUseCase.ts

PUT /api/v1/pilotage/mesures/:id¶

Description : Modifier une mesure existante
Permission : INDICATEUR_SAISIR | Use Case : ModifierMesureUseCase.ts

Module Référentiels¶

Préfixe : /api/v1/esm/referentiels + /api/v1/esm/personnes-ressources
Controller : ReferentielsModuleController
Données de référence : communes, types d'accompagnement, profils utilisateur, critères de vulnérabilité, personnes ressources.

Communes¶

GET /api/v1/esm/referentiels/communes¶

Description : Lister toutes les communes
Permission : ENFANT_LIRE

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": [
    { "code": "COT", "nom": "Cotonou", "departement": "Littoral" },
    { "code": "ABE", "nom": "Abomey", "departement": "Zou" }
  ]
}

POST /api/v1/esm/referentiels/communes¶

Description : Créer une nouvelle commune
Permission : REFERENTIEL_MODIFIER

Données d'entrée

Champ	Type	Obligatoire	Description
`code`	string	Oui	Code unique de la commune
`nom`	string	Oui	Nom de la commune
`departement`	string	Oui	Département

GET /api/v1/esm/referentiels/communes/:code¶

Description : Obtenir une commune par son code
Permission : ENFANT_LIRE

PUT /api/v1/esm/referentiels/communes/:code¶

Description : Modifier une commune
Permission : REFERENTIEL_MODIFIER

DELETE /api/v1/esm/referentiels/communes/:code¶

Description : Supprimer une commune
Permission : REFERENTIEL_MODIFIER
Attention : Vérifier les dépendances (enfants, tuteurs, etc.) avant suppression.

Types d'accompagnement¶

GET /api/v1/esm/referentiels/types-accompagnement¶

Description : Lister les types d'accompagnement
Permission : ENFANT_LIRE

Réponse : { items: TypeAccompagnementDTO[], total, page, limit, totalPages }

POST /api/v1/esm/referentiels/types-accompagnement¶

Description : Créer un type d'accompagnement
Permission : REFERENTIEL_MODIFIER

Données d'entrée

Champ	Type	Obligatoire	Description
`code`	string	Oui	Code unique
`libelle`	string	Oui	Libellé
`description`	string	Non	Description
`actif`	boolean	Non	Actif (défaut: true)

GET /api/v1/esm/referentiels/types-accompagnement/:id¶

Description : Obtenir un type par son ID | Permission : ENFANT_LIRE

PUT /api/v1/esm/referentiels/types-accompagnement/:id¶

Description : Modifier un type d'accompagnement | Permission : REFERENTIEL_MODIFIER

DELETE /api/v1/esm/referentiels/types-accompagnement/:id¶

Description : Supprimer un type d'accompagnement | Permission : REFERENTIEL_MODIFIER

Profils utilisateur¶

GET /api/v1/esm/referentiels/profils-utilisateur¶

Description : Lister les profils utilisateur
Permission : ENFANT_LIRE

Réponse : { profils: ProfilUtilisateurDTO[], total, page, limit, totalPages }

POST /api/v1/esm/referentiels/profils-utilisateur¶

Description : Créer un profil utilisateur
Permission : REFERENTIEL_MODIFIER

Données d'entrée

Champ	Type	Obligatoire	Description
`code`	string	Oui	Code unique du profil (ex: AGENT, SUPERVISEUR)
`libelle`	string	Oui	Libellé
`description`	string	Non	Description
`actif`	boolean	Non	Actif (défaut: true)

GET /api/v1/esm/referentiels/profils-utilisateur/:id¶

Description : Obtenir un profil par son ID | Permission : ENFANT_LIRE

PUT /api/v1/esm/referentiels/profils-utilisateur/:id¶

Description : Modifier un profil | Permission : REFERENTIEL_MODIFIER

DELETE /api/v1/esm/referentiels/profils-utilisateur/:id¶

Description : Supprimer un profil | Permission : REFERENTIEL_MODIFIER

Configuration des critères de vulnérabilité¶

GET /api/v1/esm/referentiels/config-criteres¶

Description : Lister la configuration des 6 critères de vulnérabilité
Permission : ENFANT_LIRE

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": [
    { "id": "cuid", "code": "C1", "libelle": "Malnutrition", "description": "...", "ordre": 1, "actif": true },
    { "id": "cuid", "code": "C2", "libelle": "Non scolarisé", "ordre": 2, "actif": true }
  ]
}

PUT /api/v1/esm/referentiels/config-criteres/:id¶

Description : Modifier un critère de vulnérabilité (libellé, description, actif)
Permission : REFERENTIEL_MODIFIER

Note : Les codes des critères (C1-C6) ne sont pas modifiables.

Personnes ressources¶

Préfixe : /api/v1/esm/personnes-ressources

GET /api/v1/esm/personnes-ressources¶

Description : Lister les personnes ressources
Permission : REFERENTIEL_LIRE

Paramètres query : type (INTERVENANT|ANIMATEUR|FORMATEUR|AUTRE), communeCode, nom, page, limite

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "personnesRessources": [
      { "id": "cuid", "nom": "Bello", "prenom": "Aminata", "type": "FORMATEUR", "structure": "ONG Santé Plus", "profession": "Infirmière" }
    ],
    "total": 5
  }
}

POST /api/v1/esm/personnes-ressources¶

Description : Créer une personne ressource
Permission : REFERENTIEL_CREER

Données d'entrée

Champ	Type	Obligatoire	Description
`nom`	string	Oui	Nom de famille
`prenom`	string	Oui	Prénom
`type`	`INTERVENANT` \| `ANIMATEUR` \| `FORMATEUR` \| `AUTRE`	Oui	Type de personne ressource
`telephone`	string	Non	Téléphone
`email`	string	Non	Email
`communeCode`	string	Non	Code commune
`profession`	string	Non	Profession
`structure`	string	Non	Structure/organisation

GET /api/v1/esm/personnes-ressources/:id¶

Description : Obtenir une personne ressource par son ID | Permission : REFERENTIEL_LIRE

PUT /api/v1/esm/personnes-ressources/:id¶

Description : Modifier une personne ressource | Permission : REFERENTIEL_CREER

DELETE /api/v1/esm/personnes-ressources/:id¶

Description : Supprimer une personne ressource | Permission : REFERENTIEL_CREER

Module Administration¶

Préfixe : /api/v1/esm/administration | Controller : AdministrationModuleController
Toutes les routes nécessitent la permission UTILISATEUR_GERER (niveau administrateur).

GET /api/v1/esm/administration/utilisateurs¶

Description : Lister tous les utilisateurs du système
Permission : UTILISATEUR_GERER
Authentification : Requise

Paramètres query

Champ	Type	Description
`profilId`	string (CUID)	Filtrer par profil
`communeCode`	string	Filtrer par commune
`actif`	boolean	Filtrer par statut actif/inactif
`recherche`	string	Recherche sur nom, prénom, email
`page`	number	Numéro de page
`limit`	number	Nb par page

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "utilisateurs": [
      { "id": "cuid", "email": "agent@caritas.bj", "nom": "Akpoue", "prenom": "Fiacre", "profil": {"code": "AGENT"}, "actif": true, "loginAttempts": 0, "deuxFacteursActive": false }
    ],
    "total": 24, "page": 1, "limit": 20, "totalPages": 2
  }
}

POST /api/v1/esm/administration/utilisateurs¶

Description : Créer un nouvel utilisateur (création admin, sans flow d'inscription)
Permission : UTILISATEUR_GERER

Données d'entrée

Champ	Type	Obligatoire	Description
`email`	string	Oui	Email unique
`nom`	string	Oui	Nom de famille
`prenom`	string	Oui	Prénom
`profilId`	string (CUID)	Oui	ID du profil
`communeCode`	string	Non	Code commune
`motDePasse`	string	Oui	Mot de passe initial
`emailNotifications`	boolean	Non	Activer les notifications

GET /api/v1/esm/administration/utilisateurs/:id¶

Description : Obtenir un utilisateur par son ID
Permission : UTILISATEUR_GERER

PUT /api/v1/esm/administration/utilisateurs/:id¶

Description : Modifier un utilisateur (profil, commune, statut actif)
Permission : UTILISATEUR_GERER

Données d'entrée

Champ	Type	Description
`nom`	string	Nouveau nom
`prenom`	string	Nouveau prénom
`profilId`	string (CUID)	Changer de profil
`communeCode`	string	Changer de commune
`actif`	boolean	Activer/désactiver le compte
`emailNotifications`	boolean	Notifications email

DELETE /api/v1/esm/administration/utilisateurs/:id¶

Description : Supprimer un utilisateur
Permission : UTILISATEUR_GERER
Attention : Action irréversible.

POST /api/v1/esm/administration/utilisateurs/:id/reinitialiser-mot-de-passe¶

Description : Réinitialiser le mot de passe d'un utilisateur (par un administrateur)
Permission : UTILISATEUR_GERER

Données d'entrée

Champ	Type	Obligatoire	Description
`nouveauMotDePasse`	string	Oui	Nouveau mot de passe imposé

Cas d'usage : Un administrateur réinitialise le mot de passe d'un agent qui a oublié le sien.

POST /api/v1/esm/administration/utilisateurs/:id/debloquer¶

Description : Débloquer un compte utilisateur (après trop de tentatives échouées)
Permission : UTILISATEUR_GERER

Note : Remet loginAttempts = 0 et lockedUntil = null.

Module Audit¶

Préfixe : /api/v1/esm/audit | Controller : AuditModuleController
Lecture seule des logs d'audit générés automatiquement par toutes les opérations.

GET /api/v1/esm/audit/logs¶

Description : Lister les logs d'audit avec filtres
Permission : AUDIT_LIRE
Authentification : Requise

Paramètres query

Champ	Type	Description
`idUtilisateur`	string (CUID)	Filtrer par utilisateur
`action`	string	Filtrer par action (slug)
`ressource`	string	Filtrer par ressource (slug)
`ipAddress`	string	Filtrer par adresse IP
`cibleId`	string (CUID)	Filtrer par ID de la cible
`dateDebut`	string (ISO)	Date de début
`dateFin`	string (ISO)	Date de fin
`page`	number	Numéro de page
`limite`	number	Nb par page

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "logs": [
      {
        "idAuditLog": "cuid",
        "action": "CONNEXION",
        "ressource": "AUTH",
        "details": { "email": "user@example.com" },
        "ipAddress": "192.168.1.1",
        "createdAt": "2026-06-17T10:00:00Z",
        "idUtilisateur": "cuid",
        "cibleId": null
      }
    ],
    "total": 250, "page": 1, "limite": 20
  }
}

Use Case associé : ListerLogsUseCase.ts

GET /api/v1/esm/audit/logs/:id¶

Description : Obtenir le détail d'un log d'audit
Permission : AUDIT_LIRE

Use Case associé : ObtenirLogUseCase.ts

Module Audit Référentiel¶

Préfixe : /api/admin/audit (montage distinct via createAuditReferentielRoutes)
Gestion des actions et ressources utilisées dans les logs d'audit.
Accès lecture : tout utilisateur authentifié
Accès écriture : utilisateurs avec niveau de rôle ≤ 2 (super-admin + admin)

GET /api/admin/audit/actions¶

Description : Lister toutes les actions d'audit enregistrées
Authentification : Requise (tout niveau)

Réponse succès (HTTP 200)

{
  "success": true,
  "data": [
    { "id": "cuid", "slug": "CONNEXION", "description": "Connexion utilisateur", "isActive": true },
    { "id": "cuid", "slug": "CREER_ENFANT", "description": "Création d'un enfant", "isActive": true }
  ]
}

POST /api/admin/audit/actions¶

Description : Créer une nouvelle action d'audit
Authentification : Requise + niveau ≤ 2

Données d'entrée

Champ	Type	Obligatoire	Description
`slug`	string	Oui	Identifiant unique de l'action (ex: CREER_ENFANT)
`description`	string	Non	Description lisible
`isActive`	boolean	Non	Active (défaut: true)

Réponse (HTTP 201) : { "success": true, "data": { action créée } }

PUT /api/admin/audit/actions/:id¶

Description : Modifier une action d'audit
Authentification : Requise + niveau ≤ 2

DELETE /api/admin/audit/actions/:id¶

Description : Supprimer une action d'audit
Authentification : Requise + niveau ≤ 2

GET /api/admin/audit/ressources¶

Description : Lister toutes les ressources d'audit
Authentification : Requise (tout niveau)

Réponse : { "success": true, "data": [{ "id": "cuid", "slug": "AUTH", "description": "...", "isActive": true }] }

POST /api/admin/audit/ressources¶

Description : Créer une ressource d'audit
Authentification : Requise + niveau ≤ 2

Données d'entrée

Champ	Type	Obligatoire	Description
`slug`	string	Oui	Identifiant unique (ex: ENFANT, AUTH)
`description`	string	Non	Description
`isActive`	boolean	Non	Active (défaut: true)

PUT /api/admin/audit/ressources/:id¶

Description : Modifier une ressource d'audit
Authentification : Requise + niveau ≤ 2

DELETE /api/admin/audit/ressources/:id¶

Description : Supprimer une ressource d'audit
Authentification : Requise + niveau ≤ 2

Module Rapports¶

Préfixe : /api/v1/esm/rapports | Controller : RapportsModuleController
Données agrégées et fiches — lecture seule.

GET /api/v1/esm/rapports/tableau-de-bord¶

Description : Obtenir le tableau de bord global (KPIs agrégés)
Permission : INDICATEUR_LIRE
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "statutsEnfants": { "ACTIF": 312, "SORTI": 45, "PERDU_DE_VUE": 12, "DECEDE": 3, "total": 372 },
    "repartitionCommune": [ { "communeCode": "COT", "communeNom": "Cotonou", "nbEnfants": 150 } ],
    "repartitionVulnerabilite": { "N1": 80, "N2": 120, "N3": 90, "N4": 22, "sansEvaluation": 60 },
    "accompagnements": { "enCours": 98, "termines": 45, "total": 143 },
    "formationsRecentes": 8,
    "nbMaitresCoraniques": 24,
    "nbTuteurs": 187
  }
}

Use Case associé : Non documenté — use case à créer
Cas d'usage : Page d'accueil de l'application — vue synthétique pour les superviseurs.

GET /api/v1/esm/rapports/repartition-commune¶

Description : Obtenir la répartition des enfants par commune
Permission : INDICATEUR_LIRE

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": [
    { "communeCode": "COT", "communeNom": "Cotonou", "nbEnfants": 150, "nbActifs": 130, "nbSortis": 20 }
  ]
}

GET /api/v1/esm/rapports/repartition-vulnerabilite¶

Description : Obtenir la répartition des enfants par niveau de vulnérabilité (N1/N2/N3/N4)
Permission : INDICATEUR_LIRE

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": { "N1": 80, "N2": 120, "N3": 90, "N4": 22, "sansEvaluation": 60, "total": 372 }
}

GET /api/v1/esm/rapports/repartition-accompagnement¶

Description : Obtenir la répartition des enfants par type d'accompagnement
Permission : INDICATEUR_LIRE

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": [
    { "typeId": "cuid", "typeLibelle": "Psychosocial", "nbEnfants": 45, "nbEnCours": 30, "nbTermines": 15 }
  ]
}

GET /api/v1/esm/rapports/kpis¶

Description : Obtenir les KPIs pour une période donnée
Permission : INDICATEUR_LIRE

Paramètres query

Champ	Type	Obligatoire	Description
`dateDebut`	string (ISO)	Oui	Début de la période
`dateFin`	string (ISO)	Oui	Fin de la période

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "nouvellesInscriptions": 25,
    "evaluationsEffectuees": 40,
    "accompagnementsDebutes": 18,
    "suivisEffectues": 60,
    "formationsOrganisees": 3,
    "periode": { "dateDebut": "2026-01-01", "dateFin": "2026-03-31" }
  }
}

GET /api/v1/esm/rapports/enfants/:id/fiche¶

Description : Obtenir la fiche complète d'un enfant (profil + historique complet)
Permission : RAPPORT_EXPORTER
Authentification : Requise

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "enfant": { "id": "cuid", "nom": "...", "prenom": "...", "dateNaissance": "...", "statutEnregistrement": "ACTIF" },
    "commune": { "code": "COT", "nom": "Cotonou" },
    "tuteur": { "nom": "...", "typeLien": "PERE" },
    "maitre": { "nom": "...", "nomEcole": "Daara Al-Nour" },
    "evaluations": [ { "dateEvaluation": "...", "niveauVulnerabilite": "N2", "scoreTotal": 3 } ],
    "accompagnements": [ { "typeLibelle": "Psychosocial", "statut": "EN_COURS", "nbSuivis": 4 } ],
    "formationsParticipees": [ { "titre": "Formation tuteurs", "presence": true } ]
  }
}

Cas d'usage : Génération du rapport PDF individuel pour un enfant.

GET /api/v1/esm/rapports/formations/:id/bilan¶

Description : Obtenir le bilan d'une formation (statistiques de présence)
Permission : RAPPORT_EXPORTER

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "formation": { "id": "cuid", "titre": "Formation tuteurs", "date": "...", "animateur": "..." },
    "participants": [ { "participantId": "cuid", "typeParticipant": "TUTEUR", "presence": true } ],
    "statistiques": { "totalParticipants": 25, "nbPresents": 22, "nbAbsents": 3, "tauxPresence": 88 }
  }
}

Module Synchronisation¶

Préfixe : /api/v1/esm/synchronisation | Controller : SynchronisationModuleController
Support de la synchronisation offline-first pour l'application mobile.

GET /api/v1/esm/synchronisation/delta¶

Description : Obtenir le delta de synchronisation (toutes les entités modifiées depuis une date)
Permission : REFERENTIEL_MODIFIER
Authentification : Requise

Paramètres query

Champ	Type	Obligatoire	Description
`depuis`	string (ISO)	Oui	Date de la dernière synchronisation

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "depuis": "2026-06-10T00:00:00Z",
    "tuteurs": [ { "id": "cuid", "nom": "...", "updatedAt": "..." } ],
    "maitresCoraniques": [],
    "enfants": [ { "id": "cuid", "nom": "...", "statutEnregistrement": "ACTIF" } ],
    "evaluations": [],
    "accompagnements": [],
    "suivis": [],
    "formations": [],
    "participations": []
  }
}

Cas d'usage : L'app mobile télécharge les changements depuis sa dernière sync.

POST /api/v1/esm/synchronisation/sync¶

Description : Synchroniser un lot de données depuis l'application mobile
Permission : REFERENTIEL_MODIFIER
Authentification : Requise

Données d'entrée (body)

{
  "items": [
    {
      "entite": "ENFANT",
      "id": "local-id-ou-cuid",
      "operation": "CREATE",
      "donnees": { "nom": "...", "prenom": "...", "dateNaissance": "..." },
      "updatedAt": "2026-06-17T08:00:00Z"
    },
    {
      "entite": "EVALUATION",
      "id": "cuid-existant",
      "operation": "UPDATE",
      "donnees": { "critere1": true, "critere2": false },
      "updatedAt": "2026-06-17T09:00:00Z"
    }
  ]
}

Entités acceptées : TUTEUR, MAITRE_CORANIQUE, ENFANT, EVALUATION, ACCOMPAGNEMENT, SUIVI, FORMATION, PARTICIPATION

Réponse succès (HTTP 200)

{
  "succes": true,
  "donnees": {
    "total": 2,
    "crees": 1,
    "misAJour": 1,
    "ignores": 0,
    "erreurs": 0,
    "details": [
      { "id": "local-id", "entite": "ENFANT", "statut": "CREE" },
      { "id": "cuid-existant", "entite": "EVALUATION", "statut": "MIS_A_JOUR" }
    ]
  }
}

Codes d'erreur par item : CREE, MIS_A_JOUR, IGNORE, ERREUR

Cas d'usage : L'agent terrain collecte des données sans connexion — à son retour, l'app mobile envoie le lot au serveur.

Module Import Excel¶

Préfixe : /api/v1/esm/import | Controller : ImportExcelModuleController
Import initial de données depuis un fichier Excel multi-feuilles.

POST /api/v1/esm/import/excel¶

Description : Importer un fichier Excel contenant des données sur plusieurs feuilles
Permission : REFERENTIEL_MODIFIER
Authentification : Requise
Content-Type : multipart/form-data

Données d'entrée (form-data)

Champ	Type	Obligatoire	Description
`fichier`	file	Oui	Fichier Excel (.xlsx)

Feuilles attendues dans le fichier : - Tuteurs — colonnes: nom, prenom, telephone, communeCode, typeLien, ... - MaitresCoraniques — colonnes: nom, prenom, nomEcole, communeCode, ... - Enfants — colonnes: nom, prenom, dateNaissance, genre, communeCode, ... - Evaluations — colonnes: ref_enfant, critere1...critere6, dateEvaluation, ... - Formations — colonnes: titre, date, lieu, typeActeurCible, ... - Participations — colonnes: ref_formation, ref_participant, typeParticipant, presence, ...

Réponse succès (HTTP 200)

{
  "succes": true,
  "message": "Import terminé",
  "donnees": {
    "tuteurs":           { "crees": 15, "ignores": 2, "erreurs": [] },
    "maitresCoraniques": { "crees": 8,  "ignores": 0, "erreurs": [] },
    "enfants":           { "crees": 120, "ignores": 5, "erreurs": [ { "feuille": "Enfants", "ligne": 45, "message": "communeCode 'XYZ' introuvable" } ] },
    "evaluations":       { "crees": 98,  "ignores": 3, "erreurs": [] },
    "formations":        { "crees": 6,   "ignores": 0, "erreurs": [] },
    "participations":    { "crees": 45,  "ignores": 2, "erreurs": [] },
    "totalCrees": 292, "totalIgnores": 12, "totalErreurs": 1
  }
}

Codes d'erreur

Code	HTTP	Signification
`FICHIER_INVALIDE`	400	Fichier non Excel ou corrompu
`FEUILLE_MANQUANTE`	400	Une feuille obligatoire manque
`ERREUR_SERVEUR`	500	Erreur technique

Use Case associé : ImporterFichierExcelUseCase.ts
Cas d'usage : Migration initiale depuis des registres papier ou Excel historiques.