API VBG Analytics

L'API VBG Analytics permet d'analyser et d'importer des données VBG depuis des fichiers Excel ou KoBoToolbox.

Vue d'ensemble

Toutes les routes demandent la permission servicesVBG.view.

Endpoint	Méthode	Description
/api/vbg-analytics/upload	POST	Analyse un fichier Excel ou CSV envoyé
/api/vbg-analytics/analyze	POST	Analyse des soumissions fournies en JSON
/api/vbg-analytics/sample	GET	Analyse sur des données d'exemple générées
/api/vbg-analytics/kobo/status	GET	Statut connexion Kobo
/api/vbg-analytics/kobo/forms	GET	Liste formulaires Kobo
/api/vbg-analytics/kobo/sync/{formUid}	POST	Analyse les soumissions d'un formulaire Kobo et synchronise les services
/api/vbg-analytics/kobo/preview/{formUid}	GET	Aperçu des soumissions (limit, 10 par défaut)
/api/vbg-analytics/kobo/fields/{formUid}	GET	Champs d'un formulaire
/api/vbg-analytics/import/services	POST	Importer les services
/api/vbg-analytics/import/agents	POST	Importer les agents
/api/vbg-analytics/rubrique-analysis	GET	Analyse par rubrique
/api/vbg-analytics/payment-by-secteur	GET	Paiements par secteur

Les routes d'analyse acceptent includePilot=true pour inclure les données de la phase pilote, et locale (ou l'en-tête X-Locale) pour la langue des libellés.

---

Analyse d'un fichier

Endpoint

POST /api/vbg-analytics/upload

Corps multipart/form-data avec un champ file (Excel .xlsx, .xls ou CSV). Le fichier n'est pas conservé : l'analyse est renvoyée directement.

{
  "success": true,
  "data": { "…": "indicateurs agrégés par région, secteur, type de service et rubrique" }
}

Erreurs 400 : Aucun fichier fourni, Format de fichier non supporté. Utilisez Excel (.xlsx, .xls) ou CSV.

---

Analyse de données JSON

POST /api/vbg-analytics/analyze

Le corps est un tableau de soumissions, ou un objet { "results": [ … ] } au format de l'API KoboToolbox. Réponse au même format que l'analyse d'un fichier.

---

Données d'exemple

GET /api/vbg-analytics/sample

Analyse sur des soumissions générées aléatoirement, pour démonstration. La réponse porte "isSample": true.

---

Statut connexion KoBoToolbox

Endpoint

GET /api/vbg-analytics/kobo/status

Réponse

{
  "success": true,
  "configured": true
}

---

Liste des formulaires Kobo

Endpoint

GET /api/vbg-analytics/kobo/forms

Réponse

{
  "success": true,
  "data": [
    {
      "uid": "aXb2c3D4eFgHiJkL",
      "name": "Enregistrement Services VBG",
      "description": "Formulaire d'enregistrement des services VBG",
      "deploymentStatus": "deployed",
      "submissions": 156,
      "dateCreated": "2024-06-01T08:00:00+00:00",
      "dateModified": "2025-03-10T14:00:00+00:00"
    },
    {
      "uid": "mNoPqRsTuVwXyZ12",
      "name": "Suivi Cas VBG",
      "description": "Formulaire de suivi des cas",
      "deploymentStatus": "deployed",
      "submissions": 1250,
      "dateCreated": "2024-06-15T10:00:00+00:00",
      "dateModified": "2025-03-14T16:30:00+00:00"
    }
  ]
}

---

Synchroniser depuis KoBoToolbox

Endpoint

POST /api/vbg-analytics/kobo/sync/{formUid}

Lit toutes les soumissions du formulaire, produit l'analyse et met à jour les services VBG correspondants.

Réponse

{
  "success": true,
  "data": { "…": "analyse" },
  "submissionCount": 156,
  "filteredCount": 150,
  "source": "kobo",
  "formUid": "<uid du formulaire>",
  "serviceSyncStats": { "…": "services créés ou mis à jour" },
  "debug": { "availableFields": [], "choiceLabelsCount": 0, "fieldDiagnostics": {} }
}

Erreurs : KoboToolbox n'est pas configuré., Aucune soumission trouvée pour ce formulaire.

---

Aperçu données Kobo

Endpoint

GET /api/vbg-analytics/kobo/preview/{formUid}?limit=10

Renvoie les premières soumissions avec les libellés résolus (région, secteur…).

---

Champs d'un formulaire Kobo

Endpoint

GET /api/vbg-analytics/kobo/fields/{formId}

Réponse

{
  "success": true,
  "data": {
    "formId": "aXb2c3D4eFgHiJkL",
    "formName": "Enregistrement Services VBG",
    "fields": [
      {
        "name": "service_code",
        "label": "Code du service",
        "type": "text",
        "required": true
      },
      {
        "name": "service_name",
        "label": "Nom du service",
        "type": "text",
        "required": true
      },
      {
        "name": "region_name",
        "label": "Région",
        "type": "select_one",
        "choices": ["Oio", "Bafata", "Gabu", "Cacheu"]
      },
      {
        "name": "type_service",
        "label": "Type de service",
        "type": "select_one",
        "choices": ["centre_ecoute", "centre_sante", "poste_police"]
      },
      {
        "name": "gps_location",
        "label": "Coordonnées GPS",
        "type": "geopoint"
      }
    ]
  }
}

---

Importer les services

Endpoint

POST /api/vbg-analytics/import/services

Corps de la requête

{
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "mapping": {
    "code": "code_service",
    "nom": "nom_service",
    "typeService": "type",
    "region": "region_nom",
    "secteur": "secteur_nom",
    "telephone": "tel",
    "responsable": "nom_responsable"
  },
  "options": {
    "updateExisting": true,
    "skipErrors": false,
    "dryRun": false
  }
}

Réponse

{
  "success": true,
  "message": "Import terminé avec succès",
  "data": {
    "totalRows": 156,
    "imported": 145,
    "updated": 8,
    "skipped": 3,
    "errors": [
      {"row": 45, "message": "Région 'Unknown' non trouvée"},
      {"row": 89, "message": "Code service déjà existant"}
    ]
  }
}

---

Importer les agents

Endpoint

POST /api/vbg-analytics/import/agents

Corps de la requête

{
  "fileId": "550e8400-e29b-41d4-a716-446655440001",
  "mapping": {
    "nom": "nom_agent",
    "prenom": "prenom_agent",
    "fonction": "fonction",
    "telephone": "telephone",
    "serviceId": "code_service"
  },
  "options": {
    "updateExisting": true,
    "linkToService": true
  }
}

Réponse

{
  "success": true,
  "message": "Import des agents terminé",
  "data": {
    "totalRows": 320,
    "imported": 310,
    "updated": 5,
    "skipped": 5,
    "errors": [
      {"row": 78, "message": "Service 'VBG-XXX' non trouvé"}
    ]
  }
}

---

Analyse par rubrique

Endpoint

GET /api/vbg-analytics/rubrique-analysis

Paramètres de requête

Paramètre	Type	Requis	Description
region	UUID	Non	Filtrer par région
secteur	UUID	Non	Filtrer par secteur
dateDebut	date	Non	Date de début
dateFin	date	Non	Date de fin
rubrique	string	Non	Filtrer par rubrique

Réponse

{
  "success": true,
  "data": {
    "periode": {
      "debut": "2025-01-01",
      "fin": "2025-03-15"
    },
    "totalCas": 1250,
    "parRubrique": [
      {
        "rubrique": "violence_physique",
        "label": "Violence physique",
        "count": 450,
        "pourcentage": 36.0,
        "evolution": "+5.2%",
        "parRegion": [
          {"region": "Oio", "count": 120},
          {"region": "Bafata", "count": 180}
        ]
      },
      {
        "rubrique": "violence_sexuelle",
        "label": "Violence sexuelle",
        "count": 280,
        "pourcentage": 22.4,
        "evolution": "-2.1%"
      },
      {
        "rubrique": "violence_psychologique",
        "label": "Violence psychologique",
        "count": 320,
        "pourcentage": 25.6,
        "evolution": "+8.3%"
      },
      {
        "rubrique": "violence_economique",
        "label": "Violence économique",
        "count": 200,
        "pourcentage": 16.0,
        "evolution": "+1.5%"
      }
    ],
    "tendance": {
      "mois": ["Jan", "Fév", "Mar"],
      "donnees": [
        {"rubrique": "violence_physique", "valeurs": [140, 155, 155]},
        {"rubrique": "violence_sexuelle", "valeurs": [95, 90, 95]}
      ]
    },
    "alertes": [
      {
        "type": "hausse",
        "rubrique": "violence_psychologique",
        "region": "Bafata",
        "message": "Augmentation de 15% des cas de violence psychologique à Bafata"
      }
    ]
  }
}

Rubriques disponibles

Rubrique	Description
violence_physique	Violence physique
violence_sexuelle	Violence sexuelle
violence_psychologique	Violence psychologique/émotionnelle
violence_economique	Violence économique
mariage_force	Mariage forcé/précoce
mutilation_genitale	Mutilation génitale féminine
exploitation	Exploitation et traite
autre	Autres formes de VBG