Documentation

Introduction

L’API iKobi est une API REST qui échange du JSON en UTF-8. Toutes les requêtes passent par HTTPS sur https://api.ikobi.app. Les montants sont des nombres décimaux dans la devise indiquée (CDF aujourd’hui) ; les dates d’échéance sont au format AAAA-MM-JJ, les horodatages en ISO 8601 UTC.

Deux familles de routes :

API partenaire (/partner/v1) : pour les institutions, avec une clé API. Lecture seule, statistiques agrégées.
API de l’application (/v1) : utilisée par l’app iKobi, avec le jeton de session d’un membre.

Authentification

Clé API partenaire

Envoyez votre clé dans l’en-tête Authorization. L’en-tête X-API-Key est aussi accepté.

Authorization: Bearer ikb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

La clé est affichée une seule fois, à sa création. Gardez-la côté serveur : jamais dans une application mobile, une page web ou un dépôt de code. Si elle est exposée, demandez sa révocation à contact@ikobi.app.

Session membre (application)

Le membre reçoit un code à six chiffres sur WhatsApp, puis l’échange contre un jeton de session.

POST /v1/auth/otp/request   { "phone": "0812345678" }
POST /v1/auth/otp/verify    { "phone": "0812345678", "code": "123456", "name": "Aline" }
→ { "token": "eyJ…", "user": { "id": 1, "name": "Aline", … } }

Authorization: Bearer eyJ…

Erreurs

Les erreurs renvoient un code HTTP explicite et un corps de forme constante :

{
  "error": {
    "code": "validation",
    "message": "Données invalides",
    "details": [{ "path": "email", "message": "E-mail invalide" }]
  }
}

HTTP	Signification
400	Requête invalide (`validation`, `bad_json`, `payment_refused`…)
401	Clé ou jeton absent, invalide ou révoqué
403	Authentifié, mais sans le droit nécessaire
404	Ressource introuvable
409	Conflit d’état (déjà payé, tour non prêt, demande déjà traitée…)
429	Trop de requêtes
503	Service en configuration ou en maintenance

Limites de débit

API partenaire : 60 requêtes par minute et par adresse IP. Les en-têtes RateLimit-* indiquent le quota restant. Au-delà, l’API répond 429 : attendez la fin de la fenêtre avant de réessayer.

API partenaire

GET/partner/v1/ping

Vérifie votre clé. Renvoie le nom de l’organisation et les droits de la clé.

{ "ok": true, "partner": "Coopérative de Matete", "scopes": ["insights:read"] }

GET/partner/v1/insights

Statistiques agrégées de la plateforme. Droit requis : insights:read.

{
  "generatedAt": "2026-11-10T19:00:00.000Z",
  "available": true,
  "communities": { "total": 25, "forming": 3, "active": 18, "completed": 4 },
  "members": 500,
  "completedCycles": 112,
  "contributions": {
    "allTime":    [{ "currency": "CDF", "count": 5210, "volume": 104200000 }],
    "last30Days": [{ "currency": "CDF", "count": 1840, "volume": 36800000 }],
    "onTimeRate": 91.4
  },
  "note": "Chiffres agrégés et indicatifs…"
}

Tant que la plateforme compte moins de cinq communautés, la réponse vaut { "available": false, "reason": "…" }. Ces indicateurs ne constituent ni une évaluation de crédit ni une décision de financement.

D’autres ressources (suivi d’un pilote, export de rapports) seront ajoutées avec nos premiers partenaires. Dites-nous ce dont vous avez besoin dans votre demande de clé.

API de l’application

Routes utilisées par l’app iKobi. Elles exigent un jeton de session membre et ne sont pas ouvertes aux intégrations tierces.

GET/v1/config

Opérateurs et devises disponibles.

GET/v1/me

Profil du membre connecté.

GET/v1/groups

Tontines du membre, avec l’état du tour en cours.

POST/v1/groups

Crée une tontine : nom, montant, devise, fréquence, nombre de membres, première échéance, numéro de versement.

POST/v1/groups/join

Rejoint une tontine avec son code d’invitation.

GET/v1/groups/{id}

Détail : membres, calendrier, montants prévu, collecté, réglé et versé.

POST/v1/groups/{id}/start

Démarre la tontine (organisateur).

GET/v1/groups/{id}/contributions/quote?method=mpesa

Devis : cotisation, frais, total à payer.

POST/v1/groups/{id}/contributions

Lance une cotisation Mobile Money. Statut initial « pending ».

GET/v1/contributions/{id}

Statut d’une cotisation.

POST/v1/groups/{id}/cycles/{n}/payout-request

Demande le versement de la cagnotte (organisateur). Validé ensuite par l’équipe iKobi.

GET/v1/groups/{id}/history

Historique des cotisations et des versements.

Webhooks

iKobi reçoit les notifications de son partenaire de paiement et de WhatsApp. Chaque notification est authentifiée par signature, dédoublonnée et, pour un paiement réussi, reconfirmée auprès du fournisseur avant d’être prise en compte. L’envoi de webhooks vers les partenaires n’est pas encore proposé.

Données et confidentialité

L’API partenaire ne renvoie aucune donnée personnelle : ni nom, ni numéro, ni détail d’une tontine.
Chaque clé est liée à une organisation identifiée et à un usage déclaré ; son utilisation est journalisée.
Toute réidentification de membres, revente de données ou usage différent de celui déclaré entraîne la révocation de la clé.

Versions

La version figure dans le chemin (/v1, /partner/v1). Les ajouts compatibles (nouveaux champs, nouvelles routes) peuvent arriver à tout moment : ignorez les champs que vous ne connaissez pas. Une rupture de compatibilité donnera lieu à une nouvelle version annoncée à l’avance aux détenteurs de clé.