Créer des livraisons
Destination, encaissement, référence de commande, statuts et annulation.
La destination
Deux cas, selon ce que vous savez de l’adresse du client :
| Vous connaissez… | Envoyez | Résultat |
|---|---|---|
| La position exacte (coordonnées GPS) | dropoff: { lat, lng, landmark? } | Statut SEARCHING_COURIER, prix définitif, un livreur est recherché tout de suite. |
| Seulement le client | rien dans dropoff | Statut AWAITING_LOCATION, prix estimé par zone. Le client reçoit un lien WhatsApp et place son repère ; le prix devient définitif à ce moment. |
Le second cas est le plus courant en e-commerce au Bénin, où les adresses écrites sont rarement assez précises. landmark est un point de repère facultatif (« Portail bleu après la pharmacie »).
Le client
customer.lastName, customer.firstName et customer.phone sont obligatoires. Le numéro est un numéro béninois qui reçoit WhatsApp : 0197000000 et +229 01 97 00 00 00 sont acceptés.
Le colis
| Champ | Valeurs |
|---|---|
parcel.category | FASHION, BEAUTY, FOOD, ELECTRONICS, DOCUMENTS, OTHER |
parcel.size | SMALL, MEDIUM, LARGE (un grand colis peut être majoré) |
parcel.fragile | true si le colis demande des précautions (peut être majoré) |
instructions (facultatif, texte court) est transmis au livreur.
L’encaissement
| Champ | Rôle |
|---|---|
payment.mode | CASH_ON_DELIVERY : le client paie à la livraison. PREPAID : rien à encaisser. |
payment.goodsAmount | Montant de la marchandise à encaisser, en FCFA (0 si déjà payée). |
payment.feePayer | Qui paie la course : CUSTOMER (ajoutée au montant payé par le client) ou MERCHANT (votre boutique). |
payment.collection | SECURE : le client paie par mobile money via Fofo Express, la vente vous est versée. DIRECT : le client vous paie sur votre numéro. Par défaut : le réglage de votre boutique. |
Le livreur ne manipule jamais d’argent. Le montant payé par le client est renvoyé dans payment.amountToCollect, et l’état du paiement dans payment.status.
Le paiement sécurisé suppose que votre boutique a renseigné le numéro mobile money qui reçoit ses
ventes. Sinon, l’API répond PAYOUT_ACCOUNT_REQUIRED.
Référence de commande et idempotence
externalRef: votre numéro de commande (64 caractères au plus), unique par boutique. Il est renvoyé partout et sert de filtre :GET /deliveries?externalRef=WC-10482. Une deuxième livraison avec la même référence est refusée (EXTERNAL_REF_TAKEN).- En-tête
Idempotency-Keyobligatoire à la création (8 à 100 caractères : lettres, chiffres,-et_). Si votre appel échoue sur le réseau, renvoyez-le avec la même clé : vous obtenez la même livraison, jamais une seconde. Utilisez par exemple l’identifiant de la commande.
Statuts
| Statut | Signification |
|---|---|
AWAITING_LOCATION | En attente de la position du client. |
SEARCHING_COURIER | Recherche d’un livreur proche. |
ASSIGNED | Un livreur a accepté et vient chercher le colis. |
IN_TRANSIT | Colis enlevé, en route vers le client. |
DELIVERED | Remis au client, qui a donné son code de confirmation. |
FAILED | Échec de la remise (failureReason : client absent, refus, adresse introuvable…). |
RETURNED | Colis rapporté à la boutique après un échec. |
CANCELLED | Annulée. |
EXPIRED | Aucune position ou aucun livreur dans le délai. |
GET /deliveries/{id}/events renvoie l’historique daté des statuts.
Annuler
curl -X POST https://api.fofoexpress.com/api/v1/partner/deliveries/LIVRAISON_ID/cancel \
-H "Authorization: Bearer $FOFO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "Commande annulée par le client" }'Une annulation est gratuite tant que le livreur n’est pas arrivé à votre boutique ; ensuite, des frais d’annulation s’appliquent et sont renvoyés dans cancellationFee.