VibeFox iMile for PrestaShop — Aide

Prérequis

PrestaShop : de 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Tarif iMile : les prix convenus avec l'équipe commerciale d'iMile. Vous les saisissez dans le tableau de prix, dans la devise par défaut de votre boutique.

Compte API iMile (uniquement pour l'estimation en direct) : l'estimation en direct utilise l'OpenAPI d'iMile « Estimated order delivery costs ». Il vous faut un Customer ID et une Secret key (la clé API délivrée par iMile avec votre Customer ID). Pour un client de test, inscrivez-vous sur le portail développeurs d'iMile (developer.imile.com). Les clés de production sont fournies par votre responsable de compte iMile. Si vous n'utilisez que le tableau de prix, vous n'avez pas besoin de clés API.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox iMile dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez vos prix iMile dans le Price table. Vous pouvez éventuellement remplir la section Live rates (API) et activer Live estimate (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur iMile avec le texte de délai de livraison Courier delivery. Le transporteur est assigné à toutes les zones et à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. N'y définissez pas de prix : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox iMile > Configure. Ils s'appliquent à chaque zone du transporteur. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les estimations iMile en cache et les jetons d'accès.

Lorsque Live estimate est activé mais ne peut pas fonctionner, des avertissements apparaissent au-dessus des réglages : le Customer ID ou la Secret key est vide, la ville ou le pays d'expédition est absent (ou le pays n'est pas un marché iMile), il n'y a aucun taux de change, ou le tableau de prix est vide et aucun prix n'existe pour les autres pays. Un avertissement apparaît aussi lorsque le module ne reconnaît pas l'unité de poids de la boutique : les poids des produits sont alors pris en kilogrammes. Définissez donc l'unité dans International > Localization (Local units). À l'enregistrement, le module vérifie que le Method title est valide (64 caractères maximum), que les champs de montant et de poids sont des nombres égaux ou supérieurs à 0, que le Minimum weight n'est pas supérieur au Maximum weight et que la règle de taxe existe. Sinon, il affiche une erreur et n'enregistre rien.

Général

Enable iMile : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et au paiement. Par défaut : iMile. Obligatoire.

Tarifs en direct (API) (facultatif)

Si iMile ne renvoie aucune estimation (pas de clés, ville pas encore saisie, erreur, délai dépassé, pas de taux de change), le tableau de prix est utilisé.

Live estimate : activez-le pour obtenir le coût d'expédition auprès d'iMile. Par défaut : désactivé. Lorsque l'estimation en direct est désactivée, rien n'est envoyé à iMile pendant le paiement.

Environment : Production (openapi.imile.com) (par défaut) ou Test (test-openapi.52imile.cn). Les clés de test ne fonctionnent qu'avec le serveur de test et donnent des prix de test.

Customer ID : le code client (customerId) délivré par iMile, par exemple C2102192601. Le vider efface aussi la Secret key enregistrée.

Secret key : la clé secrète (clé API) délivrée par iMile avec le Customer ID. Elle signe les requêtes. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Signature : la façon dont les requêtes sont signées.

Ship-from country : le pays depuis lequel vous expédiez. Par défaut, c'est le pays de votre boutique (Shop country). La liste ne contient que les pays pour lesquels le module dispose de codes pays iMile.

Ship-from city : la ville depuis laquelle vos colis sont expédiés, orthographiée comme dans la liste des villes iMile (par exemple Dubai, Riyadh). Laissez vide pour utiliser la ville de la boutique indiquée dans Shop Parameters > Contact > Stores.

Ship-from province : facultatif, par exemple Dubai ou Riyadh Province.

iMile service : le type de commande envoyé à iMile : Delivery order (100) (par défaut) ou Express order (1100). L'option Express doit être activée pour votre compte et votre pays.

Goods category : le type de marchandise envoyé à iMile : Normal goods (par défaut), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents ou Parcel.

Exchange rates : iMile calcule ses estimations dans la devise du pays de destination. Saisissez une ligne par devise avec le prix de 1 unité dans la devise par défaut de votre boutique, par exemple « AED = 0.25 » ou « SAR = 0.24 ». Le point et la virgule sont acceptés comme séparateur décimal. Un taux n'est pas nécessaire pour la devise de la boutique elle-même. Sans taux, les estimations dans cette devise ne sont pas utilisées et le tableau de prix est utilisé à la place. Le même taux convertit la valeur du panier déclarée à iMile. Les lignes invalides sont supprimées à l'enregistrement.

Tarifs (utilisés lorsque l'estimation en direct est désactivée, et en solution de repli lorsque iMile ne renvoie aucune estimation)

Saisissez votre tarif iMile dans la devise par défaut de la boutique, hors taxes. S'il est en AED, SAR ou une autre devise, convertissez-le d'abord.

Price table : une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * All other countries pour une ligne qui couvre chaque pays sans ligne propre. Chaque ligne contient un Base price et des colonnes de poids facultatives : XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg. Une colonne de poids vide (ou à 0) utilise le prix de base. Un prix de base de 0 signifie livraison gratuite vers ce pays. « 9.99 » et « 9,99 » sont acceptés. Les lignes sans aucun prix et les prix négatifs sont supprimés à l'enregistrement. Une seule ligne par pays est conservée.

Price for countries not in the table : un prix dans la devise par défaut de la boutique. Il est utilisé lorsque le tableau n'a pas de ligne pour le pays de destination (et pas de ligne *), ou lorsque la ligne n'a pas de prix pour ce poids. Laissez-le vide pour masquer le transporteur dans ce cas.

Price applies : la manière dont le prix du tableau est facturé.

Le même choix s'applique à l'estimation en direct : par commande, un seul colis contenant tout le panier est envoyé ; par article, une demande est faite pour chaque colis différent, multipliée par le nombre d'unités. Si le panier contient plus de 5 colis différents, le tableau de prix est utilisé.

Les poids et dimensions des produits sont convertis de vos unités de boutique en kilogrammes et centimètres.

Conditions

Minimum weight : masque le transporteur lorsque le panier pèse moins, en kg. 0 signifie pas de limite.

Maximum weight : masque le transporteur lorsque le panier pèse plus, en kg. Par défaut : 30. 0 signifie pas de limite.

Minimum order amount : affiche le transporteur uniquement lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison iMile est gratuite. Laissez vide pour ne jamais proposer la livraison gratuite.

Tax : la règle de taxe du transporteur, ou No tax. Choisissez No tax si les prix du tableau et les estimations iMile incluent déjà la TVA.

Disponibilité sans zones d'expédition

Ignore shipping zones : proposer iMile pour les pays ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones, et les zones créées plus tard le reçoivent aussi. Désactiver l'option supprime ces zones ajoutées, et le transporteur retrouve les zones qu'il avait auparavant.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays actifs. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_imle_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Aucune clé et aucune adresse de client n'est enregistrée. Les requêtes iMile en échec sont toujours enregistrées, même lorsque le journal de débogage est désactivé. Désactivez le journal une fois la vérification terminée.

Log : affiche la taille et les dernières entrées du journal de débogage. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages iMile, le transporteur, les estimations en cache et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au paiement

À l'étape d'expédition, PrestaShop demande au module le prix iMile. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : pays autorisés (lorsque Ignore shipping zones est activé), poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à iMile.

Avec l'estimation en direct activée, le module envoie à iMile le pays, la province et la ville d'expédition, le pays de destination, l'état, la ville et le code postal, le poids du panier en kg, la taille en cm³ (d'après les dimensions des produits), la valeur du panier, le service iMile et la catégorie de marchandises. L'estimation est toujours demandée comme prépayée, donc les frais de paiement à la livraison ne sont pas inclus. Une estimation en direct n'est demandée qu'après que le client a saisi une adresse de livraison avec une ville, et seulement si chaque produit du panier a un poids. Chaque réponse est mise en cache pendant 1 heure. Une requête en échec est mise en cache pendant 5 minutes. Après un délai d'attente ou une erreur serveur, iMile n'est pas sollicité pendant 2 minutes, après des clés refusées pendant 5 minutes, afin que le paiement n'attende pas iMile à chaque actualisation. Le délai d'attente de l'API est de 12 secondes. Un jeton d'accès expiré est renouvelé automatiquement.

L'estimation est convertie dans la devise par défaut de la boutique avec vos taux de change. Si iMile ne fournit aucune estimation exploitable (clés non renseignées, ville pas encore saisie, ville inconnue, erreur, délai dépassé, pas de taux de change), le client ne voit aucune erreur et le prix du tableau est utilisé. Si le tableau n'a pas non plus de prix, le transporteur est masqué. La raison est écrite dans le journal. Le prix est calculé dans votre devise par défaut, puis affiché dans la devise du panier du client.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne calcule que les tarifs. Il ne crée pas d'envois iMile, n'imprime pas d'étiquettes AWB, ne demande pas d'enlèvements, ne suit pas les colis, ne rapproche pas les paiements à la livraison et ne propose pas de points relais ni de consignes. Utilisez le portail iMile pour les envois.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox iMile est le premier bloc de Modules > Module Manager > VibeFox iMile > Configure, au-dessus des réglages. Saisissez la clé dans License key puis cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-imile et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur iMile n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais vous ne pouvez pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

iMile n'apparaît pas au paiement : vérifiez que la licence est active et que Enable iMile est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones et vérifiez Countries. Contrôlez les limites de poids et Minimum order amount. Vérifiez que le pays ou * a une ligne dans la Price table, ou que Price for countries not in the table est renseigné. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le prix du tableau s'affiche à la place de l'estimation iMile : activez le Debug log, rechargez le paiement et regardez le champ Log sur la page du module. Causes courantes : Live estimate est désactivé, les clés sont absentes, le client n'a pas encore saisi de ville, iMile ne reconnaît pas l'orthographe de la ville, les produits n'ont pas de poids, il n'y a pas de taux de change pour la devise de destination, ou une erreur d'API. Vérifiez aussi les avertissements au-dessus des réglages.

« sign is invalid » dans le journal : vérifiez la Secret key, puis essayez Signature = SimpleKey.

Les clés sont refusées : vérifiez le Customer ID, la Secret key et l'Environment. Les clés de test ne fonctionnent qu'avec le serveur de test.

Les noms de villes ne correspondent pas : les noms de villes doivent correspondre à la liste des villes iMile. Les développeurs peuvent les faire correspondre avec le hook actionVfdImileLiveRequest, et les codes pays avec le hook actionVfdImileLiveCountryCode.

Les prix sont dans la mauvaise devise : le tableau de prix est dans la devise par défaut de la boutique. Convertissez un tarif en AED, SAR ou MXN lorsque vous le saisissez. Les estimations en direct sont converties avec les Exchange rates.

La taxe est appliquée deux fois sur la livraison : si vos prix incluent déjà la TVA, réglez Tax sur No tax.

Les estimations semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les estimations iMile en cache.

La page indique que le transporteur iMile est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox iMile et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés.Les estimations en cache et les jetons d'accès sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) et les réglages et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module restaure le statut qu'avait le transporteur auparavant.

iMile est une marque appartenant à son propriétaire. Ce module n'est ni affilié à iMile ni approuvé par iMile.