VibeFox Mondial Relay for PrestaShop — Aide

Prérequis

PrestaShop: 8.0 à 9.x. Le paiement fonctionne avec les thèmes Classic et Hummingbird.

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

Compte Mondial Relay: le code Enseigne et la Private Key sont fournis avec un compte professionnel Mondial Relay : consultez la rubrique 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 Private Key PrivateK.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Mondial Relay 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 votre code Enseigne et, pour le mode liste, la Private Key. Renseignez Country prices puis cliquez sur Save.

À l'installation, le module crée le transporteur Mondial Relay Point Relais avec le texte de délai de livraison Delivery to a Mondial Relay Point Relais of your choice. Le transporteur est affecté à tous les groupes de clients et aux zones de France, Belgique, Luxembourg, Espagne, Portugal et Pays-Bas. 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 Mondial Relay > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Chaque enregistrement vide aussi les listes de points de retrait en cache.

Des avertissements en haut de la page signalent les problèmes qui masquent le transporteur : code Enseigne manquant, Private Key manquante en mode liste, aucun prix pour la France, la Belgique ou l'Espagne, ou transporteur supprimé. Les valeurs qui ne peuvent pas être enregistrées sont signalées après Save : un champ numérique dont la valeur n'est pas un nombre (ou est négative) conserve sa valeur précédente. Un nom de plus de 64 caractères ou un Min weight (kg) supérieur à Max weight (kg) est refusé, et rien n'est enregistré. Si l'unité de poids de la boutique ne fait pas partie de celles que le module connaît, un avertissement indique que les poids des produits sont pris en kg.

Général

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

Name: le nom du transporteur affiché aux clients au moment de la commande. Par défaut : Mondial Relay Point Relais. Obligatoire, 64 caractères maximum.

Tax status: None signifie que les prix du tableau sont définitifs. L'option Taxable avec le nom d'une règle de taxe signifie que PrestaShop ajoute la taxe de livraison de cette règle aux prix.

Compte Mondial Relay

Brand code (Enseigne): obligatoire, 8 lettres et chiffres maximum, 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, et le transporteur n'est pas affiché au moment de la commande.

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. Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer la clé enregistrée, cochez Remove the saved Private Key puis cliquez sur Save. Lorsque le code Enseigne et la Private Key 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

Selector: la manière dont le client choisit un Point Relais.

Mondial Relay map (official widget, brand code only): le Mondial Relay Parcel Shop Picker officiel, chargé depuis widget.mondialrelay.com lorsque le client l'ouvre. C'est l'option par défaut.

List of nearest points (Web Service, needs the Private Key): une liste déroulante des points les plus proches du code postal de livraison, chargée par votre serveur. Si le Web Service échoue, la carte est proposée à la place.

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

Country prices: prix par pays de destination et poids du colis. Cliquez sur + Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * Default comme pays pour tous les autres pays. Chaque ligne comporte une colonne 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 lorsque 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 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 ce champ vide pour masquer le transporteur dans ces pays.

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

Per order (weight of the whole parcel): un seul prix pour le panier, avec la colonne de poids choisie selon le poids total du panier. C'est l'option par défaut.

Per item (each item priced by its own weight): chaque produit est tarifé selon son propre poids et multiplié par sa quantité, puis les prix sont additionnés.

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

Disponibilité

Min weight (kg): masque le transporteur lorsque le panier pèse moins. 0 signifie aucune limite.

Max weight (kg): masque le transporteur lorsque le panier pèse plus. Mondial Relay accepte les colis jusqu'à 30 kg dans les Points Relais. Par défaut : 30. 0 signifie aucune limite. Un champ vide équivaut à 30 kg. Il ne peut pas être inférieur à Min weight (kg).

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

Ignore shipping zones: propose le transporteur pour les pays indiqués ci-dessous, ou pour tous les pays pris en charge si la liste est vide, même lorsque les zones du transporteur ne les incluent pas. Tant que l'option est activée, le transporteur est lié à chaque zone active, y compris celles que vous créerez plus tard. Lorsque vous la désactivez, le transporteur retrouve les zones qu'il avait auparavant.

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 et les appels au Web Service dans logs/vfd_mrel_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée. Les clés et les données clients ne sont jamais journalisées.

Log: affiche la taille et les dernières entrées du journal. 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 et le transporteur. Lorsqu'elle est désactivée, la désinstallation désactive seulement le transporteur. Les points de retrait enregistrés dans les commandes sont conservés.

Fonctionnement au moment de la commande

Le transporteur 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 Private Key.

À l'étape de livraison, PrestaShop demande au module le prix. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module 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 frais de repli est utilisé. S'il n'y a pas de prix, le transporteur 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, puis affiché dans la devise du panier du client.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne demande pas de tarifs en temps réel : Mondial Relay ne propose pas d'API publique de tarifs. Il 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 » de 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 le transporteur Mondial Relay à l'étape de livraison, un encart Mondial Relay pickup point apparaît sous celui-ci.

Mode carte : le bouton Choose a Point Relais ouvre la carte officielle de Mondial Relay dans une fenêtre, pour le pays de livraison, le code postal et le poids du colis. Une fois le point choisi par le client, il s'affiche sous la mention 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 s'affiche avec ses horaires d'ouverture. La liste est chargée par votre serveur, donc aucun script tiers ne s'exécute dans le navigateur. Les listes sont mises en cache pendant 12 heures, une réponse vide pendant 1 heure, et une requête échouée est retenue pendant 5 minutes. Le délai d'attente 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 immédiatement enregistré dans le panier. Un point est obligatoire. 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é. En mode liste, le point est également vérifié par rapport à la liste de l'adresse.

Lorsque la commande est passée, le point reste associé à la commande. La page de commande du back-office affiche le bloc Mondial Relay pickup point avec le nom du point, son adresse et le Point Relais number (par exemple FR-066974). Le client voit le point sur la page de confirmation de commande et dans le détail de sa commande dans son compte. Dans l'e-mail de confirmation de commande et dans l'e-mail de nouvelle commande du module Alertes e-mail, le point est ajouté après le nom du transporteur.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Mondial Relay est le premier bloc de Modules > Module Manager > VibeFox Mondial Relay > Configure, au-dessus des réglages. Collez 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) 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: presta-shipping-mondialrelay 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 cet emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Mondial Relay n'est pas affiché aux clients au moment de la commande et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc aussi masqué pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais vous ne pouvez pas le tester au moment de la commande. Un rappel apparaît dans Modules > Module Manager, sous 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é automatiquement pendant que vous travaillez dans le back-office : une fois par jour pendant les 14 premiers jours suivant 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

Mondial Relay n'apparaît pas au moment de la commande: vérifiez que la licence est active et que Enable/Disable est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe de clients, ou activez Ignore shipping zones. Consultez les avertissements en haut de la page du module : le transporteur est masqué sans code Enseigne, en mode liste sans Private Key, pour un pays sans prix, en dehors des limites de poids et de sous-total, et pour les pays sans Points Relais. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le test du Web Service a échoué après l'enregistrement: le message affiche l'erreur de Mondial Relay, par exemple un code Enseigne ou une clé de sécurité invalide. Vérifiez le code Enseigne et la Private Key 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 le tunnel de commande et consultez le champ Log sur la page du module pour 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 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 inscrite dans le journal. Demandez au client son Point Relais avant de créer l'envoi.

La page indique que le transporteur Mondial Relay 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 Mondial Relay et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les listes de points de retrait en cache sont toujours supprimées. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), et les réglages, le journal et les points des paniers sans commande sont supprimés. Si l'option est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rétablit le statut du transporteur qu'il avait auparavant. Les points de retrait enregistrés dans les commandes sont toujours conservés.

Mondial Relay est une marque déposée de son propriétaire. Ce module n'est ni affilié à Mondial Relay ni approuvé par Mondial Relay.