VibeFox Mondial Relay for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3), avec le thème par défaut.

PHP : 8.0 ou ultérieur.

Compte Mondial Relay : le code enseigne (Enseigne) et la clé privée sont fournis avec un compte professionnel Mondial Relay : consultez la section professionnels de mondialrelay.fr, votre espace client « Connect » ou votre contact commercial. Le sélecteur de carte n'a besoin que du code enseigne. La liste des points les plus proches nécessite les deux. Pour les tests, Mondial Relay fournit le code enseigne BDTEST13 avec la clé privée PrivateK.

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

Installation

Le téléchargement est un fichier zip unique contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_mondialrelay-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_mondialrelay.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_mondialrelay-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'Installer, vous pouvez 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 Mondial Relay et cliquez sur Install (le bouton vert +).

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

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

5. Saisissez votre code enseigne (Enseigne) et, pour le mode liste, la clé privée. Remplissez Country prices (par exemple une ligne pour la France) ou un Fallback cost, activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_mondialrelay.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension 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é.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Mondial Relay, 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 identiques dans les deux versions.

Après l'installation, le mode est désactivé tant que vous n'avez pas activé Enable/Disable et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les listes de points de retrait en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Les avertissements en haut de la page signalent les problèmes qui masquent le mode : code enseigne manquant, clé privée manquante en mode liste, aucun prix pour la France, la Belgique ou l'Espagne, et une unité de poids de la boutique que l'extension ne connaît pas (les poids des produits sont alors pris en kg). Si Name est vide, dépasse 64 caractères ou contient un des caractères < > ; = # { }, si Min weight (kg) est supérieur à Max weight (kg), ou si le code enseigne n'est pas valide, la page affiche une erreur et rien n'est enregistré. Un champ numérique dont la valeur n'est pas un nombre (ou qui est négatif) est signalé après Save et conserve sa valeur précédente ; les autres réglages sont enregistrés.

Général

Livraison en Point Relais Mondial Relay pour la France, la Belgique, le Luxembourg, l'Espagne, le Portugal et les Pays-Bas. Le mode est proposé dans sa zone géographique (voir Availability) ou, avec Ignore shipping zones, dans les pays listés.

Enable/Disable: affiche ou masque Mondial Relay au moment du paiement. Par défaut : désactivé.

Name: le nom du mode de livraison affiché aux clients dans le panier et lors du paiement. Par défaut : Mondial Relay Point Relais. Obligatoire, 64 caractères maximum.

Tax status: None (par défaut) signifie que les prix du tableau sont définitifs. Une option Taxable avec le nom d'une classe de taxe signifie qu'OpenCart ajoute par-dessus les prix la taxe de livraison de cette classe.

Sort order: la position de Mondial Relay parmi les modes de livraison au moment du paiement. Un nombre entier.

Compte Mondial Relay

Brand code (Enseigne): obligatoire, jusqu'à 8 lettres et chiffres, par exemple BDTEST13 pour les tests. Utilisé par la carte des points de retrait et par le Web Service. Sans lui, les clients ne peuvent pas choisir de Point Relais : le mode n'est donc pas affiché au moment du paiement.

Private Key: nécessaire uniquement pour le sélecteur List of nearest points. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Pour supprimer la clé enregistrée, cochez Remove the saved Private Key et cliquez sur Save. Lorsque le code enseigne et la clé privée sont renseignés, la connexion au Web Service de Mondial Relay est testée à chaque enregistrement des réglages, et un message indique si elles sont valides.

Sélecteur de point de retrait

Le client doit choisir un Point Relais avant de passer à l'étape de paiement. Le point est enregistré dans la commande.

Sélecteur : la manière dont le client choisit un Point Relais.

Tarifs (dans la devise par défaut de votre boutique, hors taxes)

Mondial Relay ne propose pas d'API publique de tarifs : le prix provient de ce tableau.

Country prices: prix par pays de destination et par poids du colis. Cliquez sur Add country pour ajouter une ligne, et sur le bouton de suppression pour en supprimer une. Choisissez * Default comme pays pour tous les autres pays. Chaque ligne contient un Price et des colonnes de poids : XS jusqu'à 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg et XL au-delà de 5 kg. Une colonne de poids vide ou égale à 0 utilise la colonne Price. Si Price est également vide, la livraison pour ce poids est gratuite ; renseignez donc Price si vous n'utilisez que certaines colonnes de poids. Décimales avec un point ou une virgule (4.90 ou 4,90). Les lignes sans aucun prix et les lignes avec un pays inconnu sont supprimées à l'enregistrement, et les valeurs qui ne sont pas des nombres sont signalées et laissées vides.

Fallback cost: utilisé pour les pays absents du tableau. Laissez-le vide pour masquer le mode pour eux.

Calculation type: la manière dont le prix est calculé.

Free shipping from: le sous-total du panier (après remises, hors taxes) à partir duquel la livraison est gratuite. Laissez-le vide s'il n'y a pas de livraison gratuite.

Disponibilité

Min weight (kg): masque le mode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).

Max weight (kg): masque le mode lorsque le panier pèse davantage. Mondial Relay accepte les colis jusqu'à 30 kg en Points Relais. Par défaut : 30. 0 signifie aucune limite. Un champ vide signifie 30 kg.

Minimum subtotal: n'affiche le mode que lorsque le sous-total du panier (produits à expédier, après remises, hors taxes) atteint au moins ce montant. Laissez-le vide pour l'afficher toujours.

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

Ignore shipping zones: lorsqu'il est activé, la Geo zone n'est pas vérifiée : le mode n'est proposé que dans les pays indiqués ci-dessous, ou dans tous les pays pris en charge si la liste est vide.

Countries (ignore zones): les pays de destination pour ce mode. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé. La liste ne contient que les pays disposant de Points Relais.

Avancé

Debug log: écrit les calculs de tarifs, les appels au Web Service et les choix de points dans storage/logs/vfd_mrel_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_mrel_debug.log.php). Ce fichier ne peut pas être lu depuis le web. Les erreurs sont toujours journalisées, même avec cette option désactivée. Les clés et les données clients ne sont jamais journalisées. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_mrel_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: lorsqu'il est activé, la désinstallation de l'extension supprime les réglages et le journal. Lorsqu'il est désactivé (par défaut), ils sont conservés pour une réinstallation. Les listes de points en cache sont toujours supprimées. Les points de retrait enregistrés dans les commandes sont conservés.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON, sans la clé privé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 mêmes vérifications que pour Save s'appliquent. La clé privée enregistrée est conservée.

Fonctionnement au moment du paiement

Le mode n'est proposé que pour les pays disposant de Points Relais : France, Belgique, Luxembourg, Espagne, Portugal et Pays-Bas. Il est masqué lorsque les clients ne pourraient pas choisir de point : sans code enseigne, ou en mode liste sans la clé privée. Si une Geo zone est définie et que l'adresse est en dehors, le mode n'est pas proposé. Avec Ignore shipping zones activé, la zone géographique n'est pas vérifiée et seuls les pays de cette liste sont desservis (tous les pays pris en charge si elle est vide).

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Les poids des produits sont convertis de leur classe de poids OpenCart en kg. Le sous-total est le prix des produits à expédier, après la remise du coupon et avant taxes. L'extension vérifie le poids du panier et le sous-total minimum. Le prix provient de la ligne du pays (ou de la ligne *) : la colonne de poids, sinon Price. Sans ligne, le coût de repli est utilisé. S'il n'y a aucun prix, le mode est masqué. Si le sous-total atteint Free shipping from, le prix devient 0. Le prix est calculé dans la devise par défaut de votre boutique, arrondi à ses décimales et affiché dans la devise du client avec la taxe du Tax status sélectionné. Aucune requête n'est envoyée à Mondial Relay pour calculer le prix.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Mondial Relay dans la fenêtre Shipping method options. Les tarifs sont les mêmes que sur OpenCart 3.

L'extension ne demande pas de tarifs en temps réel : Mondial Relay ne propose pas d'API publique de tarifs. Elle ne crée pas d'envois, n'imprime pas d'étiquettes et ne suit pas les colis. Créez les envois dans votre espace « Connect » Mondial Relay en utilisant le numéro de Point Relais affiché dans la commande. La livraison à domicile (Domicile) n'est pas proposée.

Points de retrait

Lorsque le client sélectionne l'option Mondial Relay à l'étape du mode de livraison, un encadré Mondial Relay pickup point apparaît sous celle-ci.

Mode carte : le bouton Choose a Point Relais ouvre dans une fenêtre la carte officielle de Mondial Relay pour le pays de livraison, le code postal et le poids du colis. Une fois le point choisi par le client, il est affiché sous la forme Selected: et le bouton devient Change Point Relais. Le widget de carte est chargé depuis widget.mondialrelay.com et sa bibliothèque de cartes depuis unpkg.com uniquement lorsque le client ouvre la carte. Mentionnez-le dans votre politique de confidentialité.

Mode liste : une liste déroulante - Choose a Point Relais - affiche les 10 points les plus proches du code postal de livraison, avec leur distance. Le point choisi est affiché avec ses horaires. La liste est chargée par votre serveur : aucun script tiers ne s'exécute donc dans le navigateur pour elle. Les listes sont mises en cache pendant 12 heures, une réponse vide pendant 1 heure, et une requête échouée est mémorisée pendant 5 minutes. Le délai d'expiration du Web Service est de 10 secondes. Sans code postal, le client voit Enter your postcode to see the nearest pickup points. Si aucun point n'est trouvé ou si la liste n'est pas disponible, le client voit un message tel que « La liste des points de retrait n'est pas disponible pour le moment. Veuillez utiliser la carte. » et la carte lui est proposée.

Le point choisi est enregistré immédiatement pour la session du client. Un point est obligatoire. Lorsque le client clique sur Continue, la boutique vérifie à nouveau le point. Sans point, le client voit Please choose a Mondial Relay pickup point. et ne peut pas passer au paiement. Un point situé dans un autre pays que l'adresse de livraison est refusé avec un message indiquant que le point ne se trouve pas dans le pays de livraison. En mode liste, le point est en outre vérifié par rapport à la liste pour l'adresse. Une fois la commande passée, le choix est effacé, de sorte que le panier suivant choisit à nouveau.

Sur OpenCart 4, l'encadré Mondial Relay pickup point apparaît dans la fenêtre Shipping method options, sous l'option Mondial Relay, et la carte s'ouvre à l'intérieur de cette fenêtre. La touche Échap ferme uniquement la carte. Le bouton Continue de la fenêtre ne permet pas de continuer sans point valide, avec les mêmes messages.

Lorsque la commande est passée, le point reste associé à la commande. Le mode de livraison de la commande affiche le nom du mode suivi du nom, de l'adresse et du numéro du point, par exemple Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974), afin que le client le voie dans l'e-mail de commande et dans l'historique des commandes de son compte. L'e-mail de nouvelle commande destiné à la boutique affiche le point avec son numéro dans le bloc de commentaires. Dans Sales > Orders, la page de commande affiche un encadré Mondial Relay pickup point avec le nom du point, l'adresse et le numéro Point Relais, ou No Point Relais was saved for this order. Sur OpenCart 4, l'encadré s'affiche au-dessus de History. OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau ; le point de la commande est mis à jour avec elle. Si le client fait passer cette commande à un autre mode de livraison, son point est supprimé.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Mondial Relay est le premier bloc de Extensions > Extensions > Shipping > VibeFox Mondial Relay > 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 active et votre domaine) et 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: opencart-shipping-mondialrelay 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 pour 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é une place 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 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 Mondial Relay n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (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 la méthode est masquée pour tout le monde. Après avoir ouvert une fois la page Edit, 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 affecté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 licence.

Dépannage

Mondial Relay n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo zone, ou Ignore shipping zones et sa liste de pays. Consultez les avertissements en haut de la page de l'extension : le mode est masqué sans code enseigne, en mode liste sans la clé privée, pour un pays sans prix, en dehors des limites de poids et de sous-total, et pour les pays sans Points Relais. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Le test du Web Service a échoué après l'enregistrement : le message affiche l'erreur de Mondial Relay, par exemple un code enseigne invalide ou une clé de sécurité invalide. Vérifiez le code enseigne et la clé privée auprès de Mondial Relay.

La liste des points est vide ou indisponible : le client doit d'abord saisir un code postal de livraison. Si le Web Service échoue, la carte est proposée à la place. Activez Debug log, rechargez la page de paiement et consultez le champ Log de la page de l'extension pour en connaître la raison.

La carte ne s'ouvre pas : la carte est chargée depuis widget.mondialrelay.com et unpkg.com. Vérifiez qu'un bloqueur de confidentialité ou de scripts, ou une politique de sécurité du contenu (Content Security Policy) de votre boutique, ne les bloque pas. Si la carte ne peut pas être chargée, le client voit « La carte Mondial Relay n'a pas pu être chargée. Veuillez réessayer plus tard ou choisir un autre mode de livraison. »

La page de commande indique No Point Relais was saved for this order : la commande a été passée sans point du pays de livraison. La raison est écrite dans le journal. Demandez au client le Point Relais avant de créer l'envoi.

La page affiche "Warning: You do not have permission to modify VibeFox Mondial Relay!" : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_mondialrelay (OpenCart 3) ou extension/vfd_mondialrelay/shipping/vfd_mondialrelay (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 Mondial Relay. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax status et Geo zone. Les listes de points en cache sont toujours supprimées. Si Remove data on uninstall est activé, les autres réglages et le journal de débogage sont également supprimés. S'il est désactivé, ils sont conservés et réutilisés lorsque vous réinstallez l'extension. Les points de retrait enregistrés dans les commandes sont toujours conservés, et 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 et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Mondial Relay dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

Mondial Relay est une marque de son propriétaire respectif. Cette extension n'est ni affiliée ni approuvée par Mondial Relay.