Aller au contenu

DéveloppeursAPI REST v1Webhooks signés

La livraison, en une requête.

POST votre-boutique.bj/koliaExemple
  1. 14:02:07shipment.created200
  2. 14:02:09shipment.assigned200
  3. 14:02:31shipment.accepted200
  4. 14:07:52shipment.pickup_started200
  5. 14:09:14shipment.picked_up200
  6. 14:09:40shipment.in_transit200
  7. 14:26:41shipment.delivered200
  8. 14:27:03payment.settled200
Exemple : les événements qu'un webhook reçoit pendant une course, de sa création à son règlement.

Un devis, puis une expédition. Kolia dispatche, suit, prouve et encaisse ; votre serveur reçoit chaque étape, signée.

01 — Démarrage

Une course,
trois appels.

Votre point de collecte, un devis, l'expédition. Authentification par l'en-tête X-API-Key, avec la clé que vous créez vous-même dans votre espace commerçant, rubrique Développeurs — y compris une clé de bac à sable kolia_tk_ pour tout essayer sans livreur ni argent réels.

# 1. Votre compte et vos points de collecte
curl https://api.kolia.juali.pro/v1/merchants/me \
  -H "X-API-Key: $KOLIA_API_KEY"

# 2. Le devis
curl -X POST https://api.kolia.juali.pro/v1/quotes \
  -H "X-API-Key: $KOLIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"pickupPointId":"b3e1…","destLat":6.3525,"destLng":2.3675,
       "modePaiement":"COD","montantCod":25000,"serviceLevel":"EXPRESS"}'

# 3. L'expédition, depuis le devis (valable 15 minutes)
curl -X POST https://api.kolia.juali.pro/v1/shipments \
  -H "X-API-Key: $KOLIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"quoteId":"9f0c…","pickupPointId":"b3e1…","destinataireNom":"Afi H.",
       "destinataireTel":"+22997000000","destAdresse":"Fidjrossè, rue de la plage",
       "contenu":"Commande 1042"}'

02 — Capacités

Tout le cycle
de vie, par API.

Expéditions

Devis, création, suivi, annulation, nouvelle tentative après un échec.

Webhooks signés

HMAC-SHA256 du corps brut. Sans réponse 2xx, rejoués après 1 min, 5 min, 30 min et 2 h.

Suivi en direct

Une page de suivi par colis, et la position du livreur en temps réel par WebSocket.

Paiement à la livraison

Le montant exact, encaissé en espèces ou en mobile money, crédité net sur votre compte.

Clés et portées

Plusieurs clés, chacune avec ses portées et son quota journalier, révocables à tout moment. Les clés de test se créent en libre-service.

Idempotence

Création d'expédition, recharges et reversements acceptent un en-tête Idempotency-Key : un appel rejoué ne crée ni ne débite jamais deux fois.

03 — Intégrations

Votre boutique,
livrée.

  1. 01

    Bac à sable

    En libre-service

    Une clé kolia_tk_ créée depuis votre espace, rubrique Développeurs : les expéditions sont isolées et avancent seules jusqu'à la livraison. Ni livreur, ni paiement, ni message réels. Comment ça marche

  2. 02

    SDK JavaScript

    Sur demande

    Node 18 et plus, zéro dépendance. Devis, expéditions, suivi, finances, et vérification de signature en temps constant. Non publié sur npm.

  3. 03

    SDK PHP

    Sur demande

    Une seule classe, cURL natif. Les mêmes méthodes, la même vérification de signature. Non publié sur Packagist.

  4. 04

    Extension WooCommerce

    Sur demande

    Chaque commande devient une livraison : devis et expédition créés automatiquement, lien de suivi sur la page de commande, commande terminée à la livraison prouvée. Non publiée sur WordPress.org.

  5. 05

    Sur mesure

    ERP, caisse, marketplace : l'API couvre le cycle complet. Parlons de votre intégration.

Les SDK et l'extension existent mais ne sont pas publiés sur npm, Packagist ou WordPress.org : ils vous sont remis sur demande à hello@juali.pro, objet « Développeurs ».

Une clé API,
et c'est parti.

Créez votre compte, puis votre clé dans l'espace commerçant, rubrique Développeurs : une clé de test pour essayer, une clé réelle pour expédier.