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

Endpoint	Méthode	Description
`/api/vbg-analytics/upload`	POST	Upload fichier Excel
`/api/vbg-analytics/analyze/{id}`	GET	Analyser un fichier
`/api/vbg-analytics/sample/{id}`	GET	Aperçu des données
`/api/vbg-analytics/kobo/status`	GET	Statut connexion Kobo
`/api/vbg-analytics/kobo/forms`	GET	Liste formulaires Kobo
`/api/vbg-analytics/kobo/sync`	POST	Synchroniser depuis Kobo
`/api/vbg-analytics/kobo/preview`	POST	Aperçu données Kobo
`/api/vbg-analytics/kobo/fields/{formId}`	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

Permissions requises

vbg.analytics_view : Consultation et analyse
vbg.analytics_import : Import de données

Upload fichier Excel

Endpoint

POST /api/vbg-analytics/upload

Corps de la requête

Content-Type: multipart/form-data

Champ	Type	Requis	Description
`file`	file	Oui	Fichier Excel (.xlsx ou .xls)
`type`	string	Non	Type de données (services, agents, cas)

Réponse

{
  "success": true,
  "message": "Fichier uploadé avec succès",
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "vbg_services_oio.xlsx",
    "size": 125430,
    "sheets": ["Services", "Agents", "Cas"],
    "rowCount": 156
  }
}

Analyser un fichier

Endpoint

GET /api/vbg-analytics/analyze/{fileId}

Réponse

{
  "success": true,
  "data": {
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "vbg_services_oio.xlsx",
    "analysis": {
      "totalRows": 156,
      "validRows": 150,
      "invalidRows": 6,
      "columns": [
        {"name": "code", "type": "string", "filled": 156, "unique": 156},
        {"name": "nom", "type": "string", "filled": 156, "unique": 155},
        {"name": "region", "type": "string", "filled": 156, "unique": 8},
        {"name": "type_service", "type": "string", "filled": 152, "unique": 7}
      ],
      "errors": [
        {"row": 45, "column": "telephone", "message": "Format de téléphone invalide"},
        {"row": 89, "column": "region", "message": "Région 'Unknown' non trouvée"}
      ],
      "warnings": [
        {"row": 23, "column": "email", "message": "Email manquant"}
      ],
      "duplicates": [
        {"column": "code", "value": "VBG-001", "rows": [12, 78]}
      ]
    },
    "mappingSuggestion": {
      "code": "code",
      "nom": "nom",
      "region": "region.nom",
      "type_service": "typeService"
    }
  }
}

Aperçu des données

Endpoint

GET /api/vbg-analytics/sample/{fileId}

Paramètres de requête

Paramètre	Type	Requis	Description
`sheet`	string	Non	Nom de la feuille
`limit`	int	Non	Nombre de lignes (défaut: 10)

Réponse

{
  "success": true,
  "data": {
    "headers": ["code", "nom", "region", "type_service", "telephone"],
    "rows": [
      ["VBG-OIO-001", "Centre Farim", "Oio", "centre_ecoute", "+245955123456"],
      ["VBG-OIO-002", "Poste Mansoa", "Oio", "poste_police", "+245955789012"]
    ],
    "totalRows": 156
  }
}

Statut connexion KoBoToolbox

Endpoint

GET /api/vbg-analytics/kobo/status

Réponse

{
  "success": true,
  "data": {
    "connected": true,
    "apiUrl": "https://kf.kobotoolbox.org/api/v2",
    "username": "pch_gw",
    "lastSync": "2025-03-15T10:30:00+00:00",
    "formsCount": 5
  }
}

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

Corps de la requête

{
  "formId": "aXb2c3D4eFgHiJkL",
  "mapping": {
    "code": "service_code",
    "nom": "service_name",
    "region": "region_name",
    "typeService": "type_service"
  },
  "options": {
    "updateExisting": true,
    "skipDuplicates": false,
    "dateFrom": "2025-01-01"
  }
}

Réponse

{
  "success": true,
  "message": "Synchronisation terminée",
  "data": {
    "totalRecords": 156,
    "imported": 145,
    "updated": 8,
    "skipped": 3,
    "errors": [
      {"submission": "sub_123", "message": "Région non trouvée"}
    ]
  }
}

Aperçu données Kobo

Endpoint

POST /api/vbg-analytics/kobo/preview

Corps de la requête

{
  "formId": "aXb2c3D4eFgHiJkL",
  "limit": 10
}

Réponse

{
  "success": true,
  "data": {
    "formName": "Enregistrement Services VBG",
    "totalSubmissions": 156,
    "fields": ["service_code", "service_name", "region_name", "type_service"],
    "sample": [
      {
        "service_code": "VBG-OIO-001",
        "service_name": "Centre Farim",
        "region_name": "Oio",
        "type_service": "centre_ecoute"
      }
    ]
  }
}

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

Vue d'ensemble​

Permissions requises​

Upload fichier Excel​

Endpoint​

Corps de la requête​

Réponse​

Analyser un fichier​

Endpoint​

Réponse​

Aperçu des données​

Endpoint​

Paramètres de requête​

Réponse​

Statut connexion KoBoToolbox​

Endpoint​

Réponse​

Liste des formulaires Kobo​

Endpoint​

Réponse​

Synchroniser depuis KoBoToolbox​

Endpoint​

Corps de la requête​

Réponse​

Aperçu données Kobo​

Endpoint​

Corps de la requête​

Réponse​

Champs d'un formulaire Kobo​

Endpoint​

Réponse​

Importer les services​

Endpoint​

Corps de la requête​

Réponse​

Importer les agents​

Endpoint​

Corps de la requête​

Réponse​

Analyse par rubrique​

Endpoint​

Paramètres de requête​

Réponse​

Rubriques disponibles​

Vue d'ensemble

Permissions requises

Upload fichier Excel

Endpoint

Corps de la requête

Réponse

Analyser un fichier

Endpoint

Réponse

Aperçu des données

Endpoint

Paramètres de requête

Réponse

Statut connexion KoBoToolbox

Endpoint

Réponse

Liste des formulaires Kobo

Endpoint

Réponse

Synchroniser depuis KoBoToolbox

Endpoint

Corps de la requête

Réponse

Aperçu données Kobo

Endpoint

Corps de la requête

Réponse

Champs d'un formulaire Kobo

Endpoint

Réponse

Importer les services

Endpoint

Corps de la requête

Réponse

Importer les agents

Endpoint

Corps de la requête

Réponse

Analyse par rubrique

Endpoint

Paramètres de requête

Réponse

Rubriques disponibles