VibeFox iMile for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Tarif iMile : les prix convenus avec l'équipe commerciale d'iMile. Vous les saisissez dans le tableau de prix, dans la devise 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 ». Vous avez besoin d'un Customer ID et d'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 gestionnaire 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_imile dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox iMile, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

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

6. Ajoutez VibeFox iMile à une zone d'expédition dans WooCommerce > Settings > Shipping > Shipping zones (par exemple « United Arab Emirates »), ou activez Ignore shipping zones et choisissez des pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox iMile. Ils s'appliquent à toutes les zones d'expédition. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone) : le nom que voient les clients pour cette zone. Laissez vide pour utiliser le Method title général.

Chaque fois que vous enregistrez les réglages, les estimations iMile en cache et les jetons d'accès sont effacés. Lorsque l'estimation en direct est activée mais ne peut pas fonctionner (pas de clés, pas de ville ou de pays d'expédition, pas de taux de change, tableau de prix vide), des avertissements apparaissent au-dessus des réglages.

Général

Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois.

Method title : le nom de la méthode d'expédition affiché dans le panier et au paiement. Une zone peut le remplacer. Par défaut : iMile.

Tarifs en direct (API) (facultatif)

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

Live estimate : activez-la pour obtenir le coût d'expédition auprès d'iMile. Par défaut : désactivée. 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 ne donnent que des prix de test.

Customer ID : le code client (customerId) délivré par iMile, par exemple C2102192601.

Secret key : la clé secrète (clé d'API) délivrée par iMile avec le Customer ID. Elle signe les requêtes.

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

Ship-from country : le pays depuis lequel vous expédiez. Par défaut, il s'agit du pays de votre boutique. La liste contient les pays pour lesquels le plugin dispose des codes pays iMile.

Ship-from city : la ville depuis laquelle vos colis sont expédiés, écrite comme dans la liste des villes iMile (par exemple Dubai, Riyadh). Laissez vide pour utiliser la ville de la boutique définie dans WooCommerce > Settings > General.

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 calcule ses estimations dans la devise du pays de destination. Saisissez une ligne par devise, avec le prix de 1 unité dans la devise de votre boutique, par exemple « AED = 0.25 » ou « SAR = 0.24 ». La virgule et le point sont acceptés comme séparateur décimal. 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 de prix est appliqué à la place. Le même taux convertit la valeur du panier déclarée à iMile. Les lignes invalides sont supprimées à l'enregistrement.

Prix (utilisé lorsque l'estimation en direct est désactivée, et en secours lorsque iMile ne renvoie aucune estimation)

Saisissez votre tarif iMile dans la devise de la boutique. 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 la croix 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. Les lignes sans prix, les codes pays invalides 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 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 vide pour masquer la méthode 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 des produits sont convertis de l'unité de poids de votre boutique en kilogrammes.

Conditions

Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie aucune limite.

Maximum weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 30. 0 signifie aucune limite.

Minimum order amount : n'affiche la méthode que si le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour l'afficher toujours.

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.

Excluded shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Tax status : Taxable ajoute la taxe WooCommerce au coût d'expédition, None ne l'ajoute pas. Choisissez None si les prix du tableau et les estimations iMile incluent déjà la TVA.

Disponibilité sans zones d'expédition

Ignore shipping zones : propose iMile pour les pays indiqués ci-dessous, même si la méthode n'est ajoutée à aucune zone d'expédition.

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

Avancé

Debug log : écrit les calculs de tarifs dans WooCommerce > Status > Logs (source « vfd_imile »). Aucune clé ni adresse de client n'est journalisée. Les requêtes iMile en échec sont toujours journalisées, même lorsque le journal de débogage est désactivé. Désactivez le journal une fois vos vérifications terminées.

Remove data on uninstall : lorsque l'option est activée, la suppression du plugin efface tous les réglages iMile, les méthodes de zone et les estimations en cache. La désactivation du plugin ne supprime jamais rien.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande au plugin un tarif. Le plugin vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimum de commande et classes d'expédition exclues. Si la livraison gratuite s'applique, le client voit la méthode sans frais et aucune requête n'est envoyée à iMile.

Avec l'estimation en direct activée, le plugin 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³ (à 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 prépayé, donc les frais de contre-remboursement ne sont pas inclus. Une estimation en direct n'est demandée qu'une fois que le client a saisi une ville, et seulement si chaque colis 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 de la boutique avec vos taux de change. Si iMile ne donne aucune estimation exploitable (clés non renseignées, ville non saisie, ville inconnue, erreur, délai d'attente, 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, la méthode est masquée. La raison est écrite dans le journal.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

Le plugin 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 encaissements à la livraison et ne propose pas de points relais ni de casiers. Utilisez le portail iMile pour les envois.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox iMile. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas l'emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, iMile n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

iMile n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. Vérifiez que le pays ou * a une ligne dans la Price table, ou que Price for countries not in the table est renseigné.

Le prix du tableau s'affiche à la place de l'estimation iMile : ouvrez WooCommerce > Status > Logs, source « vfd_imile », et activez Debug log pour les détails. Causes fréquentes : Live estimate est désactivée, 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'existe pas de taux de change pour la devise de destination, ou une erreur d'API. Consultez 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 filtre vfd_imile_live_request, et les codes pays avec le filtre vfd_imile_live_country_code.

Les prix sont dans la mauvaise devise : le tableau de prix est exprimé dans la devise de la boutique (WooCommerce > Settings > General). Convertissez un 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 status sur None.

Les estimations semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les estimations iMile en cache.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net, puis cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, le plugin continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation du plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages, les méthodes de zone et les estimations en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes d'expédition.

iMile est une marque déposée de son titulaire respectif. Ce plugin n'est pas affilié à iMile et n'est pas approuvé par iMile.