API Plaintes

L'API Plaintes permet de gerer les plaintes du mecanisme de gestion des griefs (GRM).

Vue d'ensemble

Le systeme de plaintes est divise en plusieurs controleurs specialises:

Controleur	Description
PlainteController	CRUD principal (cette page)
PlainteWorkflowController	Workflow et phases
PlainteAssignmentController	Assignations
PlainteSensibleController	Plaintes sensibles
PlainteStatsController	Statistiques
PlainteAlertController	Alertes
PlainteSearchController	Recherche, doublons
PlainteActionController	Actions de statut

Endpoints CRUD principal

Endpoint	Methode	Description
`/api/plaintes`	GET	Liste des plaintes
`/api/plaintes/{id}`	GET	Detail d'une plainte
`/api/plaintes`	POST	Creer une plainte
`/api/plaintes/{id}`	PUT/PATCH	Modifier une plainte
`/api/plaintes/{id}`	DELETE	Supprimer une plainte

Liste des plaintes

Endpoint

GET /api/plaintes

Parametres de requete

Parametre	Type	Requis	Description
`page`	int	Non	Numero de page (defaut: 1)
`limit`	int	Non	Elements par page (defaut: 20)
`statut`	string	Non	Filtrer par statut
`module`	string	Non	Filtrer par module
`priorite`	string	Non	Filtrer par priorite
`type`	string	Non	Filtrer par type de plainte
`search`	string	Non	Recherche (reference, plaignant, objet)
`region`	UUID	Non	Filtrer par region
`secteur`	UUID	Non	Filtrer par secteur
`localite`	UUID	Non	Filtrer par localite
`cluster`	UUID/string	Non	Filtrer par cluster (`unclustered` pour sans cluster)
`projet`	UUID	Non	Filtrer par projet
`sort`	string	Non	Champ de tri (defaut: dateCreation)
`order`	string	Non	Ordre de tri: ASC ou DESC (defaut: DESC)

Champs de tri disponibles

dateCreation
reference
plaignant
statut
priorite
module
updatedAt

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "PLT-2025-001234",
      "plaignant": "Mamadou Diallo",
      "sexePlaignant": "M",
      "telephone": "+245955123456",
      "module": "protection_sociale",
      "categorie": "retard_paiement",
      "objet": "Paiement non recu",
      "priorite": "moyenne",
      "statut": "en_cours",
      "localisation": "Farim Centro",
      "secteur": {"id": "...", "nom": "Farim"},
      "localite": {"id": "...", "nom": "Farim Centro"},
      "canalReception": "telephone",
      "typePlainteNonSensible": "retard_paiement",
      "estSensible": false,
      "estAnonyme": false,
      "dateCreation": "2025-01-15T10:00:00+00:00",
      "updatedAt": "2025-01-16T14:30:00+00:00",
      "datePriseEnCharge": "2025-01-15T11:00:00+00:00",
      "dateResolution": null,
      "resolution": null,
      "sourceCreation": "web",
      "enRetard": false,
      "joursRestantsSla": 12,
      "beneficiaire": {
        "id": "...",
        "nomComplet": "Mamadou Diallo"
      },
      "traitePar": {
        "id": "...",
        "email": "agent@pch.gw"
      },
      "assigneA": {
        "id": "...",
        "email": "superviseur@pch.gw"
      },
      "phase": "investigation",
      "phaseLabel": "Investigation",
      "phaseEnRetard": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 500,
    "pages": 25
  }
}

Detail d'une plainte

Endpoint

GET /api/plaintes/{id}

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "PLT-2025-001234",
    "plaignant": "Mamadou Diallo",
    "sexePlaignant": "M",
    "telephone": "+245955123456",
    "emailPlaignant": "mamadou@email.gw",
    "adresse": "Quartier Central, Farim",
    "latitudePlaignant": "12.345678",
    "longitudePlaignant": "-15.678901",
    "module": "protection_sociale",
    "categorie": "retard_paiement",
    "objet": "Paiement non recu",
    "description": "Je n'ai pas recu mon paiement du mois de decembre...",
    "priorite": "moyenne",
    "statut": "en_cours",
    "localisation": "Farim Centro",
    "secteur": {"id": "...", "nom": "Farim"},
    "localite": {"id": "...", "nom": "Farim Centro"},
    "canalReception": "telephone",
    "typePlainteNonSensible": "retard_paiement",
    "estSensible": false,
    "estAnonyme": false,
    "accuseReceptionEnvoye": true,
    "dateAccuseReception": "2025-01-15T10:05:00+00:00",
    "piecesJustificatives": ["doc1.pdf", "photo1.jpg"],
    "commentairesInternes": "Verifier avec Orange Money",
    "dateCreation": "2025-01-15T10:00:00+00:00",
    "updatedAt": "2025-01-16T14:30:00+00:00",
    "datePriseEnCharge": "2025-01-15T11:00:00+00:00",
    "dateResolution": null,
    "sourceCreation": "web",
    "resolution": null,
    "motifRejet": null,
    "propositionSolution": "Relancer le paiement",
    "reponsePlaignant": null,
    "solutionsAccordees": null,
    "historique": [
      {
        "date": "2025-01-15T10:00:00+00:00",
        "action": "Creation de la plainte",
        "utilisateur": "agent@pch.gw"
      },
      {
        "date": "2025-01-15T11:00:00+00:00",
        "action": "Prise en charge",
        "utilisateur": "superviseur@pch.gw"
      }
    ],
    "enRetard": false,
    "joursRestantsSla": 12,
    "slaDeadline": "2025-01-29T10:00:00+00:00",
    "beneficiaire": {
      "id": "...",
      "nomComplet": "Mamadou Diallo",
      "telephone": "+245955123456"
    },
    "traitePar": {"id": "...", "email": "agent@pch.gw"},
    "assigneA": {"id": "...", "email": "superviseur@pch.gw"},
    "dateAssignation": "2025-01-15T11:00:00+00:00",
    "phase": "investigation",
    "phaseLabel": "Investigation",
    "phaseEnRetard": false,
    "joursRestantsPhase": 5,
    "dateEcheancePhase": "2025-01-21T10:00:00+00:00"
  }
}

Creer une plainte

Endpoint

POST /api/plaintes

Corps de la requete

{
  "estAnonyme": false,
  "plaignant": "Mamadou Diallo",
  "telephone": "+245955123456",
  "sexePlaignant": "M",
  "plaignantEstBeneficiaire": true,
  "objet": "Paiement non recu",
  "description": "Je n'ai pas recu mon paiement du mois de decembre...",
  "module": "protection_sociale",
  "categorie": "retard_paiement",
  "priorite": "moyenne",
  "localisation": "Farim Centro",
  "secteurId": "550e8400-e29b-41d4-a716-446655440001",
  "localiteId": "550e8400-e29b-41d4-a716-446655440002",
  "emailPlaignant": "mamadou@email.gw",
  "adresse": "Quartier Central",
  "latitudePlaignant": "12.345678",
  "longitudePlaignant": "-15.678901",
  "canalReception": "telephone",
  "typePlainteNonSensible": "retard_paiement",
  "estSensible": false,
  "commentairesInternes": "A verifier",
  "beneficiaireId": "550e8400-e29b-41d4-a716-446655440003",
  "projetId": "550e8400-e29b-41d4-a716-446655440004"
}

Champs requis

objet : Objet de la plainte
description : Description detaillee
plaignant : Nom du plaignant (sauf si estAnonyme: true)

Detection de doublons

Si des plaintes similaires sont detectees (score >= 90%), l'API retourne une erreur 409:

{
  "success": false,
  "error": "Plaintes similaires detectees",
  "code": "DUPLICATES_DETECTED",
  "data": {
    "duplicates": [
      {
        "id": "...",
        "reference": "PLT-2025-001230",
        "plaignant": "Mamadou Diallo",
        "objet": "Paiement non recu",
        "score": 95,
        "raisons": ["Meme telephone", "Objet similaire"]
      }
    ],
    "highRiskCount": 1,
    "message": "Utilisez forceCreate=true pour creer malgre tout."
  }
}

Forcer la creation

{
  "plaignant": "Mamadou Diallo",
  "objet": "...",
  "description": "...",
  "forceCreate": true
}

Reponse succes

{
  "success": true,
  "message": "Plainte creee avec succes",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference": "PLT-2025-001234",
    "phase": "reception",
    "phaseLabel": "Reception",
    "dateEcheancePhase": "2025-01-16T10:00:00+00:00"
  },
  "warnings": {
    "similarPlaintesFound": 2
  }
}

Modifier une plainte

Endpoint

PUT /api/plaintes/{id}

PATCH /api/plaintes/{id}

Corps de la requete

{
  "plaignant": "Mamadou Diallo",
  "telephone": "+245955123456",
  "sexePlaignant": "M",
  "categorie": "retard_paiement",
  "objet": "Paiement de decembre non recu",
  "description": "Description mise a jour...",
  "priorite": "haute",
  "localisation": "Farim Centro",
  "emailPlaignant": "mamadou@email.gw",
  "adresse": "Nouvelle adresse",
  "canalReception": "telephone",
  "typePlainteNonSensible": "retard_paiement",
  "estSensible": false,
  "commentairesInternes": "Verifie avec OM - paiement en cours",
  "propositionSolution": "Relancer le transfert",
  "reponsePlaignant": "Accepte la proposition",
  "solutionsAccordees": "Paiement effectue le 16/01",
  "incidentConfirme": true,
  "dateClotureVerification": "2025-01-16",
  "typeVbgConfirme": null,
  "entiteNotifiee": false,
  "dateNotificationEntite": null,
  "actionSanctionVerifiee": null
}

Reponse

{
  "success": true,
  "message": "Plainte mise a jour"
}

Supprimer une plainte

Endpoint

DELETE /api/plaintes/{id}

Contraintes

La plainte doit etre en statut ouverte

Reponse

{
  "success": true,
  "message": "Plainte supprimee",
  "data": {
    "reference": "PLT-2025-001234"
  }
}

Création hors ligne (`clientId`)

Une plainte saisie sans réseau est envoyée plus tard avec un identifiant généré par le poste, clientId (8 à 64 caractères parmi lettres, chiffres, - et _). L'envoi est idempotent : si une plainte porte déjà ce clientId, l'API ne crée rien et renvoie la plainte existante.

{
  "success": true,
  "message": "Plainte déjà créée",
  "dejaCreee": true,
  "data": { "id": "…", "reference": "PLT-2026-000123", "phase": "reception", "phaseLabel": "Réception", "dateEcheancePhase": "…" }
}

Un clientId mal formé renvoie 400 clientId invalide. L'historique de la plainte note « saisie hors ligne ».

Synchronisation incrémentale

GET /api/plaintes/sync?depuis=2026-09-29T08:00:00+00:00&page=1&limit=200

Renvoie les plaintes modifiées depuis depuis (ISO 8601), avec leurs commentaires, dans le périmètre de l'utilisateur. limit vaut 200 par défaut et 500 au plus. Sans depuis, la synchronisation est complète.

{
  "success": true,
  "data": [ { "…": "plainte" } ],
  "meta": { "depuis": "…", "jusqua": "…", "page": 1, "limit": 200, "total": 42, "pages": 1 }
}

Les plaintes sensibles (VBG, EAS/HS) ne sont jamais renvoyées par cette route. Une suppression n'est pas propagée : seule une synchronisation complète la répercute. Un depuis invalide renvoie 400.

Actions sur une plainte

Endpoint	Accès	Corps	Effet
`POST /api/plaintes/{id}/accuse-reception`	connecté	`emailPlaignant`, `telephone` (optionnels)	Envoie l'accusé de réception au plaignant
`POST /api/plaintes/{id}/prendre-en-charge`	connecté		Passe la plainte en traitement
`POST /api/plaintes/{id}/resoudre`	connecté	`resolution` (obligatoire)	Résout la plainte
`POST /api/plaintes/{id}/non-eligible`	connecté	`motif` (obligatoire)	Classe la plainte non éligible
`POST /api/plaintes/{id}/notifier-plaignant`	connecté	`emailPlaignant`, `telephone`	Informe le plaignant ; plainte résolue ou rejetée seulement
`POST /api/plaintes/{id}/fermer`	`ROLE_ADMIN`		Ferme une plainte résolue
`POST /api/plaintes/{id}/rouvrir`	`ROLE_ADMIN`	`motif` (obligatoire)	Rouvre une plainte fermée
`POST /api/plaintes/{id}/escalader`	assigné, superviseur ou admin	`motif`	Voir Escalade
`POST /api/plaintes/{id}/assigner`	connecté	`userId`, `motif`	Assigne la plainte
`POST /api/plaintes/{id}/reassigner`	connecté	`userId`, `motif` (obligatoire)	Change d'assigné
`POST /api/plaintes/{id}/desassigner`	`ROLE_SS_SPECIALIST`	`motif`	Retire l'assignation
`POST /api/plaintes/{id}/pieces-justificatives`	connecté		Ajoute une pièce justificative

Une action incompatible avec le statut courant renvoie 400 avec le statut actuel dans le message. Les listes d'assignation se lisent avec GET /api/plaintes/mes-assignations, /non-assignees et /agents-disponibles.

Les plaintes sensibles ont leurs propres routes (marquer-sensible, consentement, sensible-details, referer-sanitaire, referer-psychologique, suivi-survivant, notifier-banque-mondiale, notifier-coordination), réservées aux permissions plaintes.sensibles_manage (écriture) et plaintes.sensibles_view (lecture).

Statuts disponibles

Statut	Description
`ouverte`	Plainte nouvellement creee
`en_cours`	Plainte en cours de traitement
`resolue`	Plainte resolue
`fermee`	Plainte fermee
`rejetee`	Plainte rejetee

Priorites

Priorite	Description
`basse`	Priorite basse
`moyenne`	Priorite moyenne (defaut)
`haute`	Priorite haute
`urgente`	Priorite urgente

Modules

Module	Description
`protection_sociale`	Protection sociale (defaut)
`paiement`	Paiements
`enregistrement`	Enregistrement
`vbg`	Violence basee sur le genre

Canaux de reception

Canal	Description
`telephone`	Appel telephonique
`sms`	SMS
`email`	Email
`web`	Formulaire web
`terrain`	En personne sur le terrain
`courrier`	Courrier postal

Phases du workflow

Phase	Description
`reception`	Reception initiale
`tri`	Tri et categorisation
`investigation`	Investigation
`resolution`	Resolution proposee
`cloture`	Cloture

Vue d'ensemble​

Endpoints CRUD principal​

Liste des plaintes​

Endpoint​

Parametres de requete​

Champs de tri disponibles​

Reponse​

Detail d'une plainte​

Endpoint​

Reponse​

Creer une plainte​

Endpoint​

Corps de la requete​

Champs requis​

Detection de doublons​

Forcer la creation​

Reponse succes​

Modifier une plainte​

Endpoint​

Corps de la requete​

Reponse​

Supprimer une plainte​

Endpoint​

Contraintes​

Reponse​

Création hors ligne (clientId)​

Synchronisation incrémentale​

Actions sur une plainte​

Statuts disponibles​

Priorites​

Modules​

Canaux de reception​

Phases du workflow​

Vue d'ensemble

Endpoints CRUD principal

Liste des plaintes

Endpoint

Parametres de requete

Champs de tri disponibles

Reponse

Detail d'une plainte

Endpoint

Reponse

Creer une plainte

Endpoint

Corps de la requete

Champs requis

Detection de doublons

Forcer la creation

Reponse succes

Modifier une plainte

Endpoint

Corps de la requete

Reponse

Supprimer une plainte

Endpoint

Contraintes

Reponse

Création hors ligne (`clientId`)

Synchronisation incrémentale

Actions sur une plainte

Statuts disponibles

Priorites

Modules

Canaux de reception

Phases du workflow