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

1Dans l’application Zeyini, ouvrez Compte puis Connecter mon site. Indiquez votre boutique, votre site et le point où le livreur récupère les colis.
2Nous vérifions votre demande, en général sous 48 heures.
3Générez votre clé d’accès et donnez-la à votre développeur avec cette page. Il branche votre site en une heure environ.
4À chaque commande, votre site demande un livreur. Le client reçoit un code à 4 chiffres qu’il donne au livreur à la remise : la livraison est alors confirmée.

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.

ChampDescription
client_lat, client_lngPosition du client (obligatoire pour un prix exact).
retrait_lat, retrait_lngFacultatif : un autre point de retrait que celui de votre fiche.
prixFacultatif : 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.

ChampDescription
refVotre numéro de commande.
client.nom, client.telLe client (téléphone obligatoire).
client.adresse, client.lat, client.lngAdresse lisible et position. Au moins l’adresse, idéalement les deux.
colisTaille ou emballage (« carton 30 × 20 × 10 cm »). N’y mettez pas le contenu : le livreur le lit.
gabaritFacultatif : 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_kgFacultatif : poids approximatif du colis, en kilos. Affiché au livreur.
payeurQui 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_adresseFacultatif : un autre point de retrait que celui de votre compte (marketplace à plusieurs vendeurs).
retrait.nom, retrait.tel, retrait.detailsFacultatif : qui remet le colis au livreur, et comment le trouver.
a_encaisserFacultatif : 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_retraitFacultatif : 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é.
codeFacultatif : le code à 4 chiffres déjà donné à votre client. Sinon Zeyini en crée un.
prioriteFacultatif : express (ou "express": true). La course est proposée aux livreurs avant les autres. Le prix du livreur ne change pas.
prixFacultatif : 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"}

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.