API KoBoToolbox

L'API KoBoToolbox permet d'intégrer les formulaires de collecte de données KoBoToolbox avec le SIG.

Vue d'ensemble

Endpoint	Méthode	Description
/api/kobo/forms	GET	Liste des formulaires
/api/kobo/forms/{uid}	GET	Détails d'un formulaire
/api/kobo/forms/{uid}/configure	POST	Configurer un formulaire
/api/kobo/forms/{uid}/sync	POST	Synchroniser les soumissions
/api/kobo/forms/{uid}/sync-filtered	POST	Synchronisation filtrée
/api/kobo/forms/{uid}/submissions	GET	Liste des soumissions
/api/kobo/forms/{uid}/preview	GET	Aperçu des soumissions
/api/kobo/forms/{uid}/webhook	POST	Configurer un webhook
/api/kobo/form-types	GET	Types de formulaires
/api/kobo/stats	GET	Statistiques

Permissions requises

• kobo.view : Consultation
• kobo.configure : Configuration
• kobo.sync : Synchronisation

---

Liste des formulaires

Endpoint

GET /api/kobo/forms

Réponse

{
  "success": true,
  "data": [
    {
      "uid": "aXb2c3D4eFgHiJkL",
      "name": "Enquête PMT 2025",
      "deployment_status": "deployed",
      "submissions": 3500,
      "date_created": "2024-06-01T08:00:00+00:00",
      "date_modified": "2025-03-10T14:00:00+00:00",
      "local": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "pmt",
        "lastSync": "2025-03-15T10:30:00+00:00",
        "submissionCount": 3450
      }
    },
    {
      "uid": "mNoPqRsTuVwXyZ12",
      "name": "Validation communautaire",
      "deployment_status": "deployed",
      "submissions": 1250,
      "date_created": "2024-07-15T10:00:00+00:00",
      "date_modified": "2025-03-14T16:30:00+00:00",
      "local": null
    }
  ]
}

Erreur si non configuré

{
  "success": false,
  "error": "KoboToolbox n'est pas configuré. Veuillez définir KOBO_API_TOKEN dans le fichier .env",
  "code": "KOBO_NOT_CONFIGURED"
}

---

Détails d'un formulaire

Endpoint

GET /api/kobo/forms/{uid}

Réponse

{
  "success": true,
  "data": {
    "uid": "aXb2c3D4eFgHiJkL",
    "name": "Enquête PMT 2025",
    "description": "Formulaire de collecte pour le Proxy Means Test",
    "deployment_status": "deployed",
    "deployment__active": true,
    "deployment__submission_count": 3500,
    "date_created": "2024-06-01T08:00:00+00:00",
    "date_modified": "2025-03-10T14:00:00+00:00",
    "owner__username": "pch_gw",
    "asset_type": "survey",
    "content": {
      "survey": [...],
      "choices": [...]
    }
  }
}

---

Configurer un formulaire

Endpoint

POST /api/kobo/forms/{uid}/configure

Corps de la requête

{
  "type": "pmt",
  "mapping": {
    "code_menage": "household_code",
    "nom_chef": "head_name",
    "region": "region_name",
    "secteur": "sector_name"
  },
  "active": true
}

Types de formulaires

Type	Description
pmt	Enquête PMT (Proxy Means Test)
validation	Validation communautaire
suivi	Suivi des bénéficiaires
plainte	Enregistrement des plaintes

Réponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uid": "aXb2c3D4eFgHiJkL",
    "title": "Enquête PMT 2025",
    "type": "pmt"
  }
}

---

Synchroniser les soumissions

Endpoint

POST /api/kobo/forms/{uid}/sync

Corps de la requête

{
  "force": false
}

Paramètre	Type	Description
force	boolean	Re-traiter les soumissions déjà importées

Réponse

{
  "success": true,
  "data": {
    "total": 3500,
    "nouveaux": 50,
    "mis_a_jour": 5,
    "ignores": 3445,
    "erreurs": []
  }
}

Réponse avec debug (si aucune importation)

{
  "success": true,
  "data": {
    "total": 3500,
    "nouveaux": 0,
    "mis_a_jour": 0,
    "ignores": 3500,
    "debug": {
      "rawCount": 10,
      "submissions": [
        {"_id": 12345, "_validation_status": {"uid": "validation_status_approved"}}
      ]
    }
  }
}

---

Synchronisation filtrée

Endpoint

POST /api/kobo/forms/{uid}/sync-filtered

Corps de la requête

{
  "region": "550e8400-e29b-41d4-a716-446655440010",
  "secteur": "550e8400-e29b-41d4-a716-446655440011",
  "localite": "550e8400-e29b-41d4-a716-446655440012",
  "enqueteur": "Mamadou Diallo",
  "groupBy": "both",
  "force": false
}

Modes de regroupement

Mode	Description
enqueteur	Regrouper par enquêteur
zone	Regrouper par zone géographique
both	Regrouper par enquêteur et zone

Réponse

{
  "success": true,
  "data": {
    "total": 500,
    "nouveaux": 500,
    "lots": [
      {
        "enqueteur": "Mamadou Diallo",
        "zone": "Farim",
        "count": 150
      },
      {
        "enqueteur": "Fatou Sane",
        "zone": "Mansoa",
        "count": 200
      }
    ]
  }
}

---

Liste des soumissions

Endpoint

GET /api/kobo/forms/{uid}/submissions

Paramètres de requête

Paramètre	Type	Requis	Description
since	date	Non	Soumissions depuis cette date
limit	int	Non	Nombre max (défaut: 100)

Réponse

{
  "success": true,
  "count": 100,
  "data": [
    {
      "_id": 12345,
      "_submission_time": "2025-03-15T10:30:00+00:00",
      "_validation_status": {"uid": "validation_status_approved"},
      "household_code": "MEN-OIO-001",
      "head_name": "Mamadou Diallo",
      "region_name": "Oio"
    }
  ]
}

---

Aperçu des soumissions

Endpoint

GET /api/kobo/forms/{uid}/preview

Réponse

{
  "success": true,
  "data": {
    "total": 3500,
    "parEnqueteur": [
      {"enqueteur": "Mamadou Diallo", "count": 450},
      {"enqueteur": "Fatou Sane", "count": 380}
    ],
    "parZone": [
      {"region": "Oio", "secteur": "Farim", "count": 1200},
      {"region": "Oio", "secteur": "Mansoa", "count": 850}
    ],
    "parStatut": {
      "approved": 3400,
      "pending": 80,
      "rejected": 20
    }
  }
}

---

Configurer un webhook

Endpoint

POST /api/kobo/forms/{uid}/webhook

Corps de la requête

{
  "url": "https://api.pch-sig.gw/api/kobo/webhook"
}

Réponse

{
  "success": true,
  "data": {
    "hookId": "hook_abc123",
    "url": "https://api.pch-sig.gw/api/kobo/webhook",
    "active": true
  }
}

---

Types de formulaires

Endpoint

GET /api/kobo/form-types

Réponse

{
  "success": true,
  "data": [
    {
      "code": "pmt",
      "label": "Enquête PMT (Proxy Means Test)",
      "description": "Collecte des données socio-économiques pour le ciblage"
    },
    {
      "code": "validation",
      "label": "Validation communautaire",
      "description": "Validation des ménages par la communauté"
    },
    {
      "code": "suivi",
      "label": "Suivi des bénéficiaires",
      "description": "Visites de suivi et vérification des conditionnalités"
    },
    {
      "code": "plainte",
      "label": "Enregistrement des plaintes",
      "description": "Collecte des plaintes et réclamations via MGP"
    }
  ]
}

---

Statistiques de synchronisation

Endpoint

GET /api/kobo/stats

Réponse

{
  "success": true,
  "data": {
    "forms": 5,
    "total_submissions": 8500,
    "last_sync": "2025-03-15T10:30:00+00:00",
    "by_type": {
      "pmt": {
        "count": 2,
        "submissions": 5000
      },
      "validation": {
        "count": 1,
        "submissions": 2000
      },
      "suivi": {
        "count": 2,
        "submissions": 1500
      }
    }
  }
}

---

Compteurs de statut (Debug)

Endpoint

GET /api/kobo/forms/{uid}/status-counts

Réponse

{
  "success": true,
  "data": {
    "validation_status_approved": 3400,
    "validation_status_not_approved": 20,
    "validation_status_on_hold": 80,
    "no_status": 0
  }
}