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

Permissions requises

ROLE_USER : Consultation, creation, modification
ROLE_ADMIN : Suppression
plaintes.sensibles_view : Voir plaintes sensibles
plaintes.sensibles_edit : Modifier plaintes sensibles

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

Requiert ROLE_ADMIN
La plainte doit etre en statut ouverte

Reponse

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

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​

Permissions requises​

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​

Statuts disponibles​

Priorites​

Modules​

Canaux de reception​

Phases du workflow​

Vue d'ensemble

Endpoints CRUD principal

Permissions requises

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

Statuts disponibles

Priorites

Modules

Canaux de reception

Phases du workflow