VibeFox iMile for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec la version 3.0.5.0) ou 4.0.2 et ultérieur (testé avec la version 4.1.0.3).

PHP : 8.0 ou ultérieur.

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

Compte d'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é d'API qu'iMile délivre 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 des prix, vous n'avez pas besoin de clés d'API.

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

Installation

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_imile-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_imile.ocmod.zip. N'installez que le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_imile-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas besoin d'actualiser Extensions > Modifications. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox iMile et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des réglages.

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

5. Saisissez vos tarifs iMile dans la Price table. Vous pouvez aussi remplir la section Live rates (API) et activer Live estimate (voir Configuration). Activez Enable iMile et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_imile.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension à partir du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox iMile, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions.

Après l'installation, le mode de livraison reste désactivé jusqu'à ce que vous activiez Enable iMile et enregistriez. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages iMile que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox iMile > Edit. Les sections sont listées à gauche. Un bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les estimations iMile en cache et les jetons d'accès. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Lors de l'enregistrement, l'extension vérifie que Method title est valide (64 caractères maximum, sans < > ; = # { }), que les champs de prix, de montant et de poids sont des nombres de 0 ou plus, que Minimum weight (kg) n'est pas supérieur à Maximum weight (kg), que Sort order est un nombre entier, et que la classe de taxe et la zone géographique existent. Sinon, elle affiche une erreur et n'enregistre rien.

Des avertissements apparaissent au-dessus des réglages (et de nouveau après un enregistrement) lorsque Live estimate est activé mais ne peut pas fonctionner : le Customer ID ou la Secret key est vide, la ville ou le pays d'expédition manque (ou le pays n'est pas un marché iMile), il n'y a pas de taux de change, ou le tableau des prix est vide et aucun prix n'est défini pour les autres pays. Un avertissement apparaît aussi lorsque la boutique n'a pas de classe de poids en kg et que l'unité de la classe de poids par défaut n'est pas reconnue par l'extension : les poids des produits sont alors considérés en kilogrammes, ajoutez donc une classe de poids kg dans System > Localisation > Weight Classes.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode de livraison à une zone géographique dans Conditions, ou activer Ignore shipping zones dans Countries pour le limiter à une liste de pays.

Enable iMile : affiche ou masque iMile au moment du paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client dans le panier et au moment du paiement. Par défaut : iMile. Obligatoire.

Sort order : la position d'iMile parmi les modes de livraison au moment du paiement. Un nombre entier.

Tarifs en direct (API) (facultatif)

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

Live estimate : activez-le pour obtenir le coût de livraison auprès d'iMile. Par défaut : désactivé. Lorsque l'estimation en direct est désactivée, rien n'est envoyé à iMile au moment du 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 tarifs 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é d'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. Ne saisissez une nouvelle valeur que pour la modifier.

Signature : la manière dont les requêtes sont signées.

Ship-from country : le pays depuis lequel vous expédiez. La première option, Store country, utilise le pays de votre boutique. La liste ne contient que les pays pour lesquels l'extension dispose des codes pays iMile.

Ship-from city : la ville depuis laquelle vos colis sont expédiés, orthographiée comme dans la liste des villes d'iMile (par exemple Dubai, Riyadh). Obligatoire pour les estimations en direct : OpenCart n'a pas de ville de boutique, donc sans ce champ seul le tableau des prix est utilisé.

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 marchandises envoyé à iMile : Normal goods (par défaut), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents ou Parcel.

Exchange rates : iMile estime dans la devise du pays de destination. Saisissez une ligne par devise avec le prix d'une unité dans la devise par défaut de votre boutique, par exemple « AED = 0.25 » ou « SAR = 0.24 ». Aucun taux n'est 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 des prix est appliqué à la place. Le même taux convertit aussi la valeur du panier déclarée à iMile.

Prix (utilisés lorsque l'estimation en direct est désactivée, et en 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 dans une autre devise, convertissez-le au préalable.

Price table : une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne, et sur le bouton × pour en supprimer une. Choisissez * All other countries pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne comporte 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 tous deux acceptés.

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 ce champ vide pour masquer le mode de livraison dans ce cas.

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

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

Les poids des produits sont convertis de leur classe de poids OpenCart en kilogrammes, et les dimensions de leur classe de longueur en centimètres.

Conditions

Minimum weight (kg) : masque le mode de livraison en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Maximum weight (kg) : masque le mode de livraison au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite. Si vous laissez le champ vide, 30 kg sont utilisés.

Minimum order amount : n'affiche le mode de livraison que lorsque le sous-total des produits à expédier (après le coupon, avant taxes) atteint ce montant. Laissez ce champ vide pour toujours l'afficher.

Free shipping from : le sous-total des produits à expédier (après le coupon, avant taxes) à partir duquel la livraison iMile est gratuite. Laissez ce champ vide pour ne jamais proposer la livraison gratuite.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Choisissez No tax si les prix du tableau et les estimations iMile incluent déjà la TVA.

Geo zone : ne propose iMile que pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. La zone géographique n'est pas vérifiée lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Pays

Ignore shipping zones : lorsque l'option est activée, la Geo zone n'est pas vérifiée et iMile est proposé pour les pays indiqués ci-dessous. Lorsqu'elle est désactivée (par défaut), seule la Geo zone s'applique.

Countries : les pays de destination autorisés. Laissez ce champ vide pour autoriser tous les pays activés dans la boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_imle_debug.log.php (sous OpenCart 4 system/storage/logs/vfd_imle_debug.log.php). Le fichier ne peut pas être lu depuis le web. Aucune clé et aucune adresse de client ne sont journalisées. Les requêtes iMile en échec sont toujours journalisées, même avec le journal de débogage désactivé. Désactivez le journal lorsque vous avez fini. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_imile_debug.old.log.php et un nouveau journal est démarré.

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 : lorsque l'option est activée, la désinstallation de l'extension supprime les réglages iMile et le journal. Lorsqu'elle est désactivée (par défaut), les réglages sont conservés pour une réinstallation. Les estimations en cache et les jetons d'accès sont toujours supprimés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La Secret key n'est pas exportée.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. La Secret key enregistrée est conservée.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix iMile. Si une Geo zone est définie, que Ignore shipping zones est désactivé et que l'adresse se situe hors de la zone géographique, iMile n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite les conditions : pays autorisés (lorsque Ignore shipping zones est activé), poids du panier et montant minimal de commande. Le montant de la commande est le prix des produits à expédier, après la remise du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à iMile.

Lorsque l'estimation en direct est activée, l'extension envoie à iMile le pays, la province et la ville d'expédition, le pays de destination, la région, la ville et le code postal de destination, le poids du panier en kg, la taille en cm³ (à partir des dimensions des produits), la valeur du panier, le service iMile et la catégorie de marchandises. L'estimation est toujours demandée en mode prépayé, les frais de paiement à la livraison ne sont donc 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 lorsque 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 interrogé pendant 2 minutes ; après des clés rejeté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 à l'aide de vos taux de change. Si iMile ne fournit aucune estimation exploitable (clés non renseignées, ville non 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 mode de livraison est masqué. La raison est écrite dans le journal. Le prix est calculé dans votre devise par défaut, arrondi à ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit iMile dans la fenêtre Shipping method options. Le mode de livraison fonctionne de la même manière que sur OpenCart 3.

L'extension ne fait que calculer les tarifs. Elle 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 de retrait ni de casiers. Elle n'ajoute rien aux commandes : la commande affiche le nom du mode de livraison et le coût de livraison comme tout autre mode de livraison OpenCart. Utilisez le portail iMile pour les envois.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox iMile est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox iMile > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est valide 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-imile et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de l'extension peuvent changer la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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 mode de livraison iMile n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de livraison est masqué pour tout le monde. Une fois la page Edit ouverte une fois, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. Les commandes existantes ne sont pas concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 de l'extension 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é. Contrôlez Geo zone, Ignore shipping zones et Countries, les limites de poids et Minimum order amount. Vérifiez que le pays ou * All other countries a une ligne dans la Price table, ou que Price for countries not in the table est renseigné. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Le prix du tableau s'affiche à la place de l'estimation iMile : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Raisons fréquentes : Live estimate est désactivé, les clés manquent, Ship-from city est vide, 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'existe 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 rejeté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 d'iMile. Les développeurs peuvent modifier la requête avec l'événement OpenCart vfd_imile/live_request, et les codes pays avec l'événement vfd_imile/live_country_code.

Les prix sont dans la mauvaise devise : le tableau des prix est dans la devise par défaut de la boutique. Convertissez tout tarif en AED, SAR ou MXN lors de la saisie. Les estimations en direct sont converties avec Exchange rates.

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

Les estimations semblent périmées après un changement : cliquez sur Save sur la page de l'extension. Cela efface les estimations iMile en cache.

La page indique « Warning: You do not have permission to modify VibeFox iMile! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_imile (OpenCart 3) ou extension/vfd_imile/shipping/vfd_imile (OpenCart 4) dans System > Users > User Groups.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox iMile. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable iMile, Sort order, Tax class et Geo zone. Les estimations en cache et les jetons d'accès sont toujours supprimés. Si Remove data on uninstall est activé, les réglages iMile et le journal de débogage sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation. Les commandes existantes gardent leur mode de livraison et leur coût.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox iMile dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléversé.

iMile est une marque déposée de son propriétaire. Cette extension n'est ni affiliée à iMile ni approuvée par iMile.