Import depuis KoboToolbox

Cette page documente l'importation des Community Workers (Cuidadoras) depuis KoboToolbox.

---

Vue d'ensemble

Le module permet d'importer les cuidadoras enregistrees via formulaire KoboToolbox directement dans le SIG.

Workflow d'import

┌────────────────┐      ┌────────────────┐      ┌────────────────┐
│    Terrain     │      │  KoboToolbox   │      │    PCH-SIG     │
│                │      │                │      │                │
│ Formulaire de  │ ──►  │ Soumissions    │ ──►  │ Community      │
│ collecte CW    │      │ stockees       │      │ Workers        │
└────────────────┘      └────────────────┘      └────────────────┘
        │                       │                       │
        │ Agent terrain         │ Sync automatique      │ Import manuel
        │ collecte donnees      │ ou webhook            │ ou synchronisation
        └───────────────────────┴───────────────────────┘

---

Endpoints API

Endpoint	Methode	Description
/api/community-workers/kobo/forms	GET	Liste des formulaires Kobo disponibles
/api/community-workers/kobo/config	GET	Configuration Kobo actuelle
/api/community-workers/kobo/sync	POST	Synchroniser depuis KoboToolbox
/api/community-workers/kobo/import	POST	Importer des soumissions
/api/community-workers/kobo/recent	GET	CW importes recemment
/api/community-workers/kobo/stats	GET	Statistiques d'import
/api/community-workers/kobo/check/{koboId}	GET	Verifier si une soumission existe

---

Configuration Kobo

Endpoint

GET /api/community-workers/kobo/config

Reponse

{
  "success": true,
  "data": {
    "koboConfigured": true,
    "hasDefaultFormUid": true,
    "defaultFormUid": "aXXXXXXXXXXXXXXX",
    "statuts": {
      "actif": "Actif",
      "suspendu": "Suspendu",
      "inactif": "Inactif"
    },
    "typesContrat": {
      "volontaire": "Volontaire",
      "contractuel": "Contractuel"
    }
  }
}

---

Liste des formulaires disponibles

Endpoint

GET /api/community-workers/kobo/forms

Reponse

{
  "success": true,
  "data": [
    {
      "uid": "aXXXXXXXXXXXXXXX",
      "name": "Registre Cuidadoras v7",
      "deployment_status": "deployed",
      "submissions": 450,
      "date_created": "2026-01-15T10:00:00+00:00",
      "date_modified": "2026-07-20T14:30:00+00:00"
    }
  ]
}

---

Synchronisation depuis Kobo

Synchronise automatiquement les nouvelles soumissions depuis KoboToolbox.

Endpoint

POST /api/community-workers/kobo/sync

Corps de la requete

{
  "assetUid": "aXXXXXXXXXXXXXXX",
  "updateExisting": false,
  "ignoreDuplicates": false
}

Parametre	Type	Requis	Description
assetUid	string	Non	UID du formulaire Kobo (utilise la config si absent)
updateExisting	boolean	Non	Mettre a jour les enregistrements existants
ignoreDuplicates	boolean	Non	Ignorer les alertes de doublons

Reponse

{
  "success": true,
  "message": "5 cuidador(es) importe(s), 2 doublon(s), 0 erreur(s)",
  "resultats": {
    "total": 10,
    "succes": 5,
    "doublons": 2,
    "mises_a_jour": 3,
    "erreurs": 0,
    "details": [
      {
        "koboId": "abc-123",
        "action": "created",
        "code": "CW-OIO-00123",
        "nomComplet": "Maria Silva"
      }
    ]
  }
}

---

Import manuel de soumissions

Permet d'importer des soumissions Kobo specifiques.

Endpoint

POST /api/community-workers/kobo/import

Import en lot

{
  "submissions": [
    {
      "_uuid": "abc-123",
      "nom_complet": "Maria Silva",
      "sexe": "F",
      "date_naissance": "1985-03-15",
      "telephone": "+245955123456",
      "region": "Oio",
      "secteur": "Farim"
    },
    {
      "_uuid": "def-456",
      "nom_complet": "Fatou Sane",
      "sexe": "F",
      "date_naissance": "1990-07-22",
      "telephone": "+245966789012",
      "region": "Bafata",
      "secteur": "Bafata"
    }
  ],
  "ignoreDuplicates": false
}

Import unitaire

{
  "_uuid": "abc-123",
  "nom_complet": "Maria Silva",
  "sexe": "F",
  "date_naissance": "1985-03-15",
  "telephone": "+245955123456"
}

Reponse (lot)

{
  "success": true,
  "message": "2 cuidador(es) importe(s), 0 doublon(s), 0 erreur(s)",
  "resultats": {
    "succes": 2,
    "doublons": 0,
    "erreurs": 0
  }
}

Reponse (unitaire)

{
  "success": true,
  "message": "Cuidador importe avec succes",
  "code": "CW-OIO-00123",
  "communityWorkerId": "550e8400-e29b-41d4-a716-446655440000"
}

Erreur doublon (409)

{
  "success": false,
  "error": "Un cuidador avec ce numero de telephone existe deja",
  "duplicata": true
}

---

CW importes recemment

Endpoint

GET /api/community-workers/kobo/recent?limit=50

Reponse

{
  "success": true,
  "count": 50,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "CW-OIO-00123",
      "nomComplet": "Maria Silva",
      "sexe": "F",
      "telephone": "+245955123456",
      "region": "Oio",
      "secteur": "Farim",
      "localite": "Farim Centro",
      "statut": "actif",
      "koboSubmissionId": "abc-123",
      "koboSubmissionTime": "2026-07-20T10:30:00+00:00",
      "agentCollecte": "Mamadou Diallo",
      "createdAt": "2026-07-20T11:00:00+00:00"
    }
  ]
}

---

Statistiques d'import

Endpoint

GET /api/community-workers/kobo/stats

Reponse

{
  "success": true,
  "data": {
    "totalImportes": 450,
    "importesAujourdHui": 12,
    "importesCetteSemaine": 45,
    "importesCeMois": 120,
    "parRegion": [
      {"region": "Oio", "count": 150},
      {"region": "Bafata", "count": 120},
      {"region": "Gabu", "count": 100}
    ],
    "parAgent": [
      {"agent": "Mamadou Diallo", "count": 85},
      {"agent": "Fatou Sane", "count": 72}
    ]
  }
}

---

Verifier l'existence d'une soumission

Endpoint

GET /api/community-workers/kobo/check/{koboId}

Reponse (existe)

{
  "success": true,
  "exists": true,
  "communityWorker": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "CW-OIO-00123",
    "nomComplet": "Maria Silva",
    "createdAt": "2026-07-20T11:00:00+00:00"
  }
}

Reponse (n'existe pas)

{
  "success": true,
  "exists": false
}

---

Mapping des champs Kobo

Le service d'import mappe automatiquement les champs du formulaire Kobo vers l'entite CommunityWorker.

Champs standards

Champ Kobo	Champ CommunityWorker
nom_complet / prenom + nom	prenom, nom
sexe	sexe
date_naissance	dateNaissance
lieu_naissance	lieuNaissance
telephone / numero_telephone	telephone
email	email
region	region (relation)
secteur	secteur (relation)
localite / tabanca	localite (relation)
type_contrat	typeContrat
niveau_instruction	niveauInstruction
_submitted_by	agentCollecte
_submission_time	koboSubmissionTime
_uuid	koboSubmissionId

Champs formulaire v7

Champ Kobo	Champ CommunityWorker
langues_parlees	languesParlees
autre_langue	autreLangue
type_document	typeDocument
numero_document	numeroDocument
date_expiration_document	dateExpirationDocument
numero_orange	numeroOrange
numero_mtn	numeroMtn
numero_telecel	numeroTelecel
sim_telecel_enregistree	simTelecelEnregistree
compte_mobile_money	compteMobileMoney

Champs GPS

Champ Kobo	Champ CommunityWorker
_geolocation[0]	latitude
_geolocation[1]	longitude
altitude	altitude
precision	precisionGps

---

Gestion des doublons

Le systeme detecte les doublons sur plusieurs criteres :

1. Numero de telephone - Correspondance exacte
2. Numero de document - Correspondance exacte
3. Nom + Date de naissance - Correspondance exacte
4. Geolocalisation - Proximite < 50m

Options de gestion

Option	Comportement
ignoreDuplicates: false	Retourne erreur 409 si doublon detecte
ignoreDuplicates: true	Ignore silencieusement les doublons
updateExisting: true	Met a jour l'enregistrement existant

---

Telechargement des photos depuis Kobo

Lors de l'import, le systeme telecharge automatiquement les photos attachees dans le formulaire Kobo.

Types de photos supportees

Type	Champ Kobo	Stockage
Photo recto document	documento/photo_document_recto	cw-photos/{cwId}/...
Photo verso document	documento/photo_document_verso	cw-photos/{cwId}/...
Photo de profil	photo_caregiver	cw-photos/{cwId}/...
Signature/consentement	consentement/photo_consentement	cw-photos/{cwId}/...

Processus de telechargement

1. Le service detecte les attachments dans _attachments de la soumission
2. Pour chaque photo identifiee par son question_xpath, il telecharge l'image
3. L'image est stockee dans var/uploads/cw-photos/{cwId}/
4. Le chemin relatif est enregistre dans l'entite CommunityWorker

Configuration requise

Le token Kobo doit avoir les permissions necessaires pour acceder aux fichiers media. L'appel suivant est fait par le SIG vers l'API de KoboToolbox (pas vers l'API du SIG) :

GET https://<serveur-kobo>/api/v2/assets/{uid}/data/{submissionId}/attachments/
Authorization: Token {KOBO_API_TOKEN}

Notes techniques

• Les images sont telechargeees en resolution "medium" pour optimiser l'espace
• Les photos sont servies par l'API via /api/photos/cw/{cwId}/{filename}, avec une signature valable 12 heures (voir Photos)
• Les types MIME acceptes: image/jpeg, image/png, image/gif, image/webp

---

Permissions requises

Endpoint	Permission
/api/community-workers/kobo/forms	community_workers.view
/api/community-workers/kobo/config	community_workers.view
/api/community-workers/kobo/sync	community_workers.create
/api/community-workers/kobo/import	community_workers.create
/api/community-workers/kobo/recent	community_workers.view
/api/community-workers/kobo/stats	community_workers.view
/api/community-workers/kobo/check/{id}	community_workers.view