Pular para o conteúdo principal

API KoBoToolbox

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

Vue d'ensemble​

EndpointMéthodeDescription
/api/kobo/formsGETListe des formulaires
/api/kobo/forms/{uid}GETDétails d'un formulaire
/api/kobo/forms/{uid}/configurePOSTConfigurer un formulaire
/api/kobo/forms/{uid}/syncPOSTSynchroniser les soumissions
/api/kobo/forms/{uid}/sync-filteredPOSTSynchronisation filtrée
/api/kobo/forms/{uid}/submissionsGETListe des soumissions
/api/kobo/forms/{uid}/previewGETAperçu des soumissions
/api/kobo/forms/{uid}/webhookPOSTConfigurer un webhook
/api/kobo/forms/{uid}/attendance-sheetGETFeuille de présence PDF
/api/kobo/form-typesGETTypes de formulaires
/api/kobo/statsGETStatistiques

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​

TypeDescription
pmtEnquête PMT (Proxy Means Test)
validationValidation communautaire
suiviSuivi des bénéficiaires
plainteEnregistrement 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ètreTypeDescription
forcebooleanRe-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​

ModeDescription
enqueteurRegrouper par enquêteur
zoneRegrouper par zone géographique
bothRegrouper 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ètreTypeRequisDescription
sincedateNonSoumissions depuis cette date
limitintNonNombre 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
  }
}

Feuille de présence PDF​

Génère une feuille de présence PDF pour une session de formation ou activité terrain basée sur les soumissions du formulaire.

Endpoint​

GET /api/kobo/forms/{uid}/attendance-sheet

Paramètres de requête​

ParamètreTypeRequisDescription
datedateNonDate de la session (format: YYYY-MM-DD)
regionUUIDNonFiltrer par région
secteurUUIDNonFiltrer par secteur
enqueteurstringNonNom de l'enquêteur/formateur
titrestringNonTitre de la session
formatstringNonFormat de sortie: pdf (défaut), xlsx

Réponse PDF​

Le fichier PDF est retourné directement avec les headers appropriés :

Content-Type: application/pdf
Content-Disposition: attachment; filename="feuille_presence_2026-07-31.pdf"

Contenu de la feuille​

SectionDescription
En-têteLogos officiels (selon configuration branding)
TitreTitre de la session et date
InformationsRégion, secteur, formateur
TableauListe des participants avec colonnes signature
Pied de pageTotaux et espace pour validation

Colonnes du tableau​

ColonneDescription
N°Numéro d'ordre
Nom completNom du participant
FonctionRôle ou fonction
TéléphoneNuméro de contact
SignatureEspace pour signature manuscrite
ObservationsNotes additionnelles

Exemple cURL​

curl -X GET "https://api.example.com/api/kobo/forms/{uid}/attendance-sheet?date=2026-07-31&region={region_id}&titre=Formation%20VBG" \
  -H "Authorization: Bearer <token>" \
  -o feuille_presence.pdf

Cas d'utilisation​

  • Formations terrain : Liste des participants à une session de formation
  • Réunions communautaires : Présence aux réunions de validation
  • Activités de suivi : Participants aux visites de suivi
  • Sessions de sensibilisation : Feuilles d'émargement