Zeyini
Branchez votre site sur le réseau de livreurs Zeyini
Chaque commande de votre boutique en ligne appelle automatiquement le livreur disponible le plus proche. Votre site suit la livraison en direct, du retrait jusqu’à la remise au client.
Comment ça marche
Pour le développeur
Adresse de l’API : https://zeyini.com. Chaque appel porte la clé dans l’en-tête X-Cle. Les échanges sont en JSON.
POST/api/v1/devis
Le prix de la livraison avant de la commander, par exemple pour l’afficher au panier.
| Champ | Description |
|---|---|
client_lat, client_lng | Position du client (obligatoire pour un prix exact). |
retrait_lat, retrait_lng | Facultatif : un autre point de retrait que celui de votre fiche. |
prix | Facultatif : le prix de livraison que vous comptez facturer à votre client. Zeyini retient le plus haut des deux, le vôtre ou son barème. |
curl -X POST https://zeyini.com/api/v1/devis \
-H "X-Cle: lv_votre_cle" -H "Content-Type: application/json" \
-d '{"client_lat": 6.3654, "client_lng": 2.4183, "prix": 900}'
{"prix": 900, "distance_km": 5.7, "prix_retenu": 900, "commission": 315, "commission_pct": 35, "total": 1215}
prix revient au livreur. commission revient à Zeyini : elle s’ajoute au prix retenu (0 avec un abonnement mensuel). total est ce que vous paierez pour cette livraison : affichez-le à votre client avant qu’il paie.
POST/api/v1/courses
Demande un livreur pour une commande. Envoyer deux fois la même ref ne crée qu’une seule course.
| Champ | Description |
|---|---|
ref | Votre numéro de commande. |
client.nom, client.tel | Le client (téléphone obligatoire). |
client.adresse, client.lat, client.lng | Adresse lisible et position. Au moins l’adresse, idéalement les deux. |
colis | Taille ou emballage (« carton 30 × 20 × 10 cm »). N’y mettez pas le contenu : le livreur le lit. |
gabarit | Facultatif : sac, moto (par défaut), kloboto (tricycle) ou camionnette. Seuls les livreurs dont le véhicule convient reçoivent la course. Valeur inconnue : moto. |
poids_kg | Facultatif : poids approximatif du colis, en kilos. Affiché au livreur. |
payeur | Qui paie la livraison : client (le destinataire la règle au livreur, avec le montant à encaisser) ou entreprise (elle va sur votre facture de quinzaine, le livreur n’encaisse que les marchandises). Sans ce champ, une course sans encaissement reste client, et une course avec a_encaisser prend le choix inscrit sur votre fiche, réglé dans l’onglet Factures de votre espace. Par défaut : entreprise. Toute autre valeur est refusée. |
retrait_lat, retrait_lng, retrait_adresse | Facultatif : un autre point de retrait que celui de votre compte (marketplace à plusieurs vendeurs). |
retrait.nom, retrait.tel, retrait.details | Facultatif : qui remet le colis au livreur, et comment le trouver. |
a_encaisser | Facultatif : montant en espèces que le livreur encaisse à la remise (paiement à la livraison). Zeyini vous le reverse. Le champ payeur dit si le livreur encaisse aussi la livraison. |
frais_retrait | Facultatif : la part de a_encaisser qui correspond aux frais de retrait Mobile Money que vous avez déjà facturés à votre client. Zeyini retire ce montant avant de calculer la commission d’encaissement, qui porte ainsi sur le seul prix des marchandises, comme chez vous. Sans ce champ, la commission se lit sur tout a_encaisser : si vos frais y sont compris, elle peut monter d’un palier et vous coûter plus que ce que vous avez encaissé. |
code | Facultatif : le code à 4 chiffres déjà donné à votre client. Sinon Zeyini en crée un. |
priorite | Facultatif : express (ou "express": true). La course est proposée aux livreurs avant les autres. Le prix du livreur ne change pas. |
prix | Facultatif : le prix de livraison que vous facturez à votre client. Zeyini retient le plus haut des deux, ce prix ou son barème, et y ajoute sa commission sur votre facture ; le livreur ne le voit jamais et reste payé au prix calculé par Zeyini. |
curl -X POST https://zeyini.com/api/v1/courses \
-H "X-Cle: lv_votre_cle" -H "Content-Type: application/json" \
-d '{"ref": "CMD-1042",
"client": {"nom": "Awa", "tel": "0169483448", "adresse": "Akpakpa, près du marché",
"lat": 6.3654, "lng": 2.4183},
"colis": "sachet 1 kg", "payeur": "client"}'
{"course": {"id": "a1b2…", "ref_externe": "CMD-1042", "statut": "en_attente", "prix": 900, …},
"code": "4821"}
$corps = json_encode([
"ref" => "CMD-1042",
"client" => ["nom" => "Awa", "tel" => "0169483448", "adresse" => "Akpakpa", "lat" => 6.3654, "lng" => 2.4183],
"colis" => "sachet 1 kg", "payeur" => "client",
]);
$ch = curl_init("https://zeyini.com/api/v1/courses");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_POSTFIELDS => $corps,
CURLOPT_HTTPHEADER => ["X-Cle: lv_votre_cle", "Content-Type: application/json"]]);
$rep = json_decode(curl_exec($ch), true);
$code = $rep["code"]; // à envoyer au client (SMS, e-mail, page de commande)
const rep = await fetch("https://zeyini.com/api/v1/courses", {
method: "POST",
headers: { "X-Cle": process.env.ZEYINI_CLE, "Content-Type": "application/json" },
body: JSON.stringify({ ref: "CMD-1042", payeur: "client", colis: "sachet 1 kg",
client: { nom: "Awa", tel: "0169483448", adresse: "Akpakpa", lat: 6.3654, lng: 2.4183 } })
}).then(r => r.json());
console.log(rep.code); // à donner au client
Le code est à transmettre à votre client : il le donne au livreur quand il reçoit sa commande.
Paiement de vos courses : en paiement différé, elles vont sur votre facture de quinzaine, dans la limite de votre encours ; au-delà, elles se prépaient sur le porte-monnaie de votre compte Zeyini. Sans paiement différé, chaque course se prépaie sur ce porte-monnaie dès sa création (la réponse porte "facturation": "prepaye"). S’il ne suffit pas, la course est refusée (code 400, avec "prepaiement": true et le montant qui manque dans manque) et rien n’est prélevé : rechargez le porte-monnaie, puis renvoyez la même demande. Une course annulée avant que le colis soit récupéré est remboursée sur le porte-monnaie.
GET/api/v1/courses/{ref}
L’état d’une course : en_attente, sans_livreur, proposee, acceptee, recuperee, en_retour (livraison impossible, le colis revient), retournee (colis rendu à votre point de retrait), livree ou annulee. Une fois acceptée, elle contient aussi le livreur (prénom, téléphone, véhicule, photo, position).
POST/api/v1/courses/{ref}/annuler
Annule la course tant que le colis n’a pas été récupéré. Si un livreur avait déjà accepté la course et s’était mis en route, vous pouvez le dédommager de son déplacement : {"dedommagement": 500}. Il reçoit la somme en entier ; elle va sur votre facture de la quinzaine, ou elle est retenue sur le remboursement d’une course prépayée. Jamais plus que ce que la course aurait coûté, et rien si aucun livreur ne l’avait acceptée. La réponse donne le montant retenu dans dedommagement.
POST/api/v1/courses/{ref}/messages
Transmet un message au livreur pendant la livraison : {"texte": "Je descends", "auteur": "client"}. L’auteur est client (votre client), vendeur (la boutique) ou equipe (votre équipe). GET sur la même adresse rend tous les messages de la course.
Être prévenu en direct
Indiquez une adresse de retour dans votre fiche (par exemple https://maboutique.bj/zeyini). À chaque étape, Zeyini y envoie :
POST https://maboutique.bj/zeyini
X-Signature: 5f2c… (HMAC-SHA256 du corps avec votre secret)
{"evenement": "course.livree", "id": "9f1c…", "envoye_le": 1767225600,
"course": {"ref_externe": "CMD-1042", "statut": "livree", …}}
Quand le livreur écrit à votre client, vous recevez l’évènement course.message, avec "message": {"auteur": "livreur", "prenom": "Yao", "texte": "Bonjour, je suis là.", "le": 1767225600} : transmettez-le à votre client.
Appels dans votre application, sans numéro : quand le livreur appelle votre client, vous recevez course.appel avec "appel": {"id": "…", "statut": "sonne", "prenom": "Yao"} (puis le même évènement à la fin : fini, manque, refuse, annule). Faites sonner votre client, puis relayez avec votre clé : GET /api/v1/appels/{id} (l’offre WebRTC à lire), POST /api/v1/appels/{id}/repondre {"reponse": "v=0…"}, POST /api/v1/appels/{id}/raccrocher. Votre client appelle le livreur par POST /api/v1/courses/{ref}/appels {"offre": "v=0…", "prenom": "Bio"}. Les serveurs de connexion : GET /api/v1/appels/ice.
Chaque avis porte un identifiant unique (id) et son heure d’envoi (envoye_le, en secondes), couverts par la signature : ignorez un id déjà reçu, ou un avis de plus de cinq minutes.
Vérifiez la signature avec le secret affiché en même temps que votre clé :
// PHP
$ok = hash_equals(hash_hmac("sha256", file_get_contents("php://input"), $secret), $_SERVER["HTTP_X_SIGNATURE"]);
// Node.js
const ok = crypto.createHmac("sha256", secret).update(corpsBrut).digest("hex") === req.headers["x-signature"];
Questions fréquentes
Mon site est sous WordPress, Shopify ou un autre outil ? Votre développeur appelle /api/v1/courses quand une commande passe au statut « payée » ou « à expédier ». Sans développeur, vous pouvez aussi demander vos livreurs à la main depuis l’application, rubrique Colis.
Combien ça coûte ? Le prix de chaque livraison suit le barème du livreur, selon la distance. Zeyini y ajoute sa commission, payée en plus, et l’accès à l’interface technique est facturé une fois par an. La demande de prix vous donne le total de chaque course ; les montants sont dans votre contrat et dans l’onglet Factures.
Une clé a fuité ? Générez-en une nouvelle dans l’application : l’ancienne cesse aussitôt de marcher.