Guide de l'API Kolia

Introduction

L'API Kolia est une API REST : URLs prévisibles, corps JSON, codes HTTP standards. Toutes les routes sont préfixées par /v1 et servies en HTTPS depuis https://api.kolia.juali.pro.

Les montants sont exprimés en FCFA entiers (pas de décimales) et arrondis au multiple de 5. Les statuts et champs métiers sont en français — ils reflètent le vocabulaire du terrain.

Démarrage rapide

1. Créez votre compte commerçant et validez votre profil (KYC pour activer le COD).
2. Générez une clé API depuis le dashboard (Paramètres → Développeurs) ou via POST /v1/developer/api-keys.
3. Demandez un devis, créez l'expédition, suivez-la.

# 1. Devis
curl -X POST https://api.kolia.juali.pro/v1/quotes \
  -H "X-API-Key: kolia_sk_xxx" -H "Content-Type: application/json" \
  -d '{"origineLat":6.3654,"origineLng":2.4183,"destLat":6.4489,"destLng":2.3556,"serviceLevel":"STANDARD"}'

# → {"prixCourse":1200,"distanceKm":9.8,"serviceLevel":"STANDARD"}

# 2. Expédition
curl -X POST https://api.kolia.juali.pro/v1/shipments \
  -H "X-API-Key: kolia_sk_xxx" -H "Content-Type: application/json" \
  -d '{"destinataireNom":"Josuas A.","destinataireTel":"+22997550123","destAdresse":"Calavi","contenu":"Colis","modePaiement":"PREPAYE"}'

Authentification

Deux mécanismes, selon le contexte :

Environnements

Devis & tarification

Le prix d'une course dépend de la distance, du niveau de service et des éventuels coupons. Demandez toujours un devis avant de créer l'expédition : le prix renvoyé est celui qui sera facturé.

Coupons : passez codeCoupon dans le devis (WELCOME10, KOLIA20…). La réponse détaille la remise appliquée.

Expéditions

Créer

{
  "destinataireNom": "Josuas A.",
  "destinataireTel": "+22997550123",
  "destAdresse":     "Abomey-Calavi, Aganmandin",
  "destLat": 6.4489, "destLng": 2.3556,
  "contenu":         "Repas chaud",
  "serviceLevel":    "EXPRESS",
  "modePaiement":    "COD",
  "montantCod":      12000,
  "pickupPointId":   "pp_…"   // point d'enlèvement enregistré
}

La réponse contient reference (format KOL-2026-XXXXX), le statut initial et lienSuivi à partager au destinataire. Le dispatch démarre automatiquement : pas d'appel supplémentaire.

Suivre, annuler, relancer

• GET /v1/shipments/:id — détail complet : livreur affecté, chronologie horodatée, preuve de livraison, répartition financière.
• POST /v1/shipments/:id/cancel — annulation, permise tant que le colis n'est pas pris en charge.
• POST /v1/shipments/:id/retry — nouvelle tentative après un échec de livraison.

Statuts & machine à états

Chaque expédition suit une machine à états stricte. Les transitions illégales sont refusées avec 409.

Suivi public

Chaque expédition a une page de suivi publique https://api.kolia.juali.pro/t/:reference — carte en direct, chronologie, contact du livreur pendant la course, notation à la livraison. Pour construire votre propre interface :

• GET /v1/tracking/:reference — état JSON public (sans clé).
• WebSocket /tracking (Socket.IO) — positions du livreur en temps réel, salle :reference.

Webhooks

Souscrivez un endpoint HTTPS et recevez chaque événement du cycle de vie. Réponse attendue : un code 2xx en moins de 10 s. En cas d'échec, relivraison automatique avec backoff exponentiel.

{ "url": "https://votre-site.com/webhooks/kolia", "events": ["shipment.delivered", "shipment.failed"] }
// "events": ["*"] pour tout recevoir. La réponse contient le secret de signature (montré une seule fois).

Vérifier la signature

Chaque livraison porte trois en-têtes : X-Kolia-Event (type), X-Kolia-Delivery (id unique) et X-Kolia-Signature (HMAC-SHA256 du corps brut, avec votre secret). Vérifiez-la systématiquement :

import { verifyWebhookSignature } from 'kolia-sdk';

app.post('/webhooks/kolia', (req, res) => {
  if (!verifyWebhookSignature(secret, req.rawBody, req.headers['x-kolia-signature'])) {
    return res.status(401).end();
  }
  // req.body = { type: 'shipment.delivered', data: { reference, statut, … } }
  res.status(200).end();
});

Codes d'erreur

Toutes les erreurs partagent le même format : { "statusCode": 403, "message": "…", "details": […] }, avec des messages en français prêts à afficher.

SDK officiels

Le code source des SDK est livré avec la plateforme (dossier kolia-sdk/) et documenté par des exemples exécutables.