VibeFox Mercado Envios for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Compte Mercado Pago (pour les tarifs en temps réel uniquement) : les tarifs en temps réel proviennent de la calculatrice Mercado Envios de votre compte Mercado Pago en Argentine, au Brésil ou au Mexique. Mercado Envios doit être activé pour le compte. Les colis sont cotés à partir de l'adresse d'expédition configurée dans ce compte. Vous avez besoin de l'Access Token de production (il commence par APP_USR-) : dans le panneau développeurs de Mercado Pago, ouvrez votre application et ses identifiants de production. Il n'y a pas de bouton de connexion : vous collez le token dans les réglages du module. Si vous utilisez uniquement des prix par pays, vous n'avez pas besoin de compte Mercado Pago.

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 Mercado Envios 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. Pour les tarifs en temps réel, collez l'Access Token, choisissez le pays de Mercado Envios et, si la devise par défaut de votre boutique n'est pas ARS, BRL ou MXN, le taux de change. Vous pouvez aussi remplir Country prices et Fallback cost (utilisés sans tarifs en temps réel). Cliquez sur Save.

À l'installation, le module crée le transporteur Mercado Envios avec le texte de délai de livraison Mercado Envios delivery. Le transporteur est affecté à toutes les zones et à tous les groupes de clients, sans règle de taxe. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Mercado Envios > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs Mercado Envios mis en cache et la dernière erreur de l'API.

Les avertissements en haut de la page signalent les problèmes de configuration : un taux de change manquant, pas d'access token ni de prix, la dernière erreur de l'API Mercado Envios avec sa date, et une unité de poids ou de dimension de la boutique que le module ne connaît pas (elle est alors lue en kg ou en cm). Si le transporteur a été supprimé, la section General indique : The Mercado Envios carrier was not found — reset the module to create it again.

Général

Ajoutez les zones de vos clients au transporteur Mercado Envios dans Shipping > Carriers, ou utilisez Ignore shipping zones ci-dessous. Ces réglages s'appliquent à toutes les zones.

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

Name : le nom du transporteur affiché aux clients au moment du paiement. Par défaut : Mercado Envios. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax (par défaut). Mercado Envios calcule des prix finaux. No tax les affiche tels que calculés ; une règle de taxe ajoute votre taxe de livraison en plus.

API Mercado Envios (tarifs en temps réel) (sans token, seuls les prix ci-dessous sont utilisés)

Access token : votre Access Token de production Mercado Pago (APP_USR-...). Il n'est envoyé qu'à api.mercadopago.com et n'est jamais journalisé. 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 arrêter d'utiliser les tarifs en temps réel, cochez Remove the saved access token (only the prices below are used then) puis enregistrez.

Mercado Envios country : le pays de votre compte Mercado Pago : Argentina (ARS) (par défaut), Brazil (BRL) ou Mexico (MXN). Les tarifs en temps réel ne sont demandés que pour les destinations de ce pays et sont calculés dans sa devise.

Exchange rate : nécessaire uniquement si la devise par défaut de votre boutique diffère de la devise de Mercado Envios : le prix de 1 ARS, BRL ou MXN dans votre devise par défaut, par exemple 0.001. Sans lui, les tarifs en temps réel ne sont pas utilisés. Il doit s'agir d'un nombre positif. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Prix sans tarifs en temps réel

Ces prix sont utilisés lorsqu'il n'y a pas d'access token, pour les destinations hors du pays de Mercado Envios, et lorsque l'API ne renvoie aucun tarif. Ils sont exprimés dans la devise par défaut de votre boutique, hors taxes.

Country prices : un tableau de pays de destination et de prix. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * All other countries pour tous les pays qui n'ont pas leur propre ligne. Price est le prix du pays. Les colonnes XS (jusqu'à 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) et XL (plus de 5 kg) le remplacent pour ce poids de panier. Une colonne vide ou à 0 utilise Price. Un Price de 0 signifie livraison gratuite vers ce pays. 9.99 et 9,99 sont tous deux acceptés. Les valeurs qui ne sont pas des nombres sont signalées après l'enregistrement puis effacées. Les lignes sans aucun prix sont supprimées lors de l'enregistrement.

Fallback cost : utilisé lorsque ni l'API ni Country prices ne donnent de prix. Laissez-le vide pour masquer le transporteur dans ce cas.

Calculation type : Per order facture le prix une seule fois. Per item (each item priced by its own weight x quantity) recherche dans Country prices (ou le Fallback cost) le prix du poids de chaque produit et le multiplie par sa quantité. Si un produit n'obtient pas de prix, le transporteur est masqué. Les tarifs Mercado Envios en temps réel portent toujours sur le colis entier.

Disponibilité

Min weight : le poids minimum du panier en kg pour que ce transporteur apparaisse. 0 signifie aucune limite.

Max weight : masque le transporteur lorsque le panier pèse davantage, en kg. Vide signifie 25 kg, 0 signifie aucune limite. Un Min weight supérieur à Max weight est refusé à l'enregistrement.

Minimum subtotal : n'affiche le transporteur que lorsque le sous-total du panier (après remises, avant 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 sans configurer ses zones. À l'enregistrement, le transporteur est ajouté à toutes les zones, ainsi qu'aux zones créées ultérieurement. Désactiver l'option supprime les zones qu'elle a ajoutées, et le transporteur conserve ses propres zones.

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

Livraison gratuite

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel ce transporteur est gratuit. Aucune requête API n'est envoyée dans ce cas. Laissez vide pour désactiver.

Avancé

Debug log : écrit les requêtes API et le calcul des tarifs dans logs/vfd_mrcv_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même avec cette option désactivée. L'access token et les adresses des clients ne sont jamais journalisés.

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, le transporteur, les tarifs en cache et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

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

Pour une destination dans le pays de Mercado Envios avec un code postal valide, le module décrit le panier comme un seul colis : la plus grande largeur et longueur des produits, la somme des hauteurs de tous les produits et le poids total en grammes. Chaque côté et le poids sont relevés aux minimums Mercado Envios du pays, de sorte que les produits sans dimensions ni poids obtiennent tout de même un tarif. La valeur du panier est envoyée comme prix de l'article dans la devise de Mercado Envios. L'option la moins chère renvoyée par Mercado Envios est convertie dans la devise par défaut de votre boutique, puis affichée dans la devise du panier du client.

Chaque devis est mis en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle requête. Un devis échoué n'est pas renouvelé pendant 5 minutes. Si Mercado Pago est injoignable, refuse le token ou limite les requêtes, tous les tarifs en temps réel sont suspendus pendant 5 minutes, afin que le paiement n'attende pas l'API à chaque actualisation. Le délai d'expiration de l'API est de 10 secondes.

Les prix sans tarifs en temps réel sont utilisés à la place lorsqu'il n'y a pas de token, que la destination est hors du pays de Mercado Envios, que le code postal est absent ou non valide, que le taux de change est manquant, que le colis est plus lourd que la limite de Mercado Envios du pays (25 kg en Argentine, 15 kg au Brésil, 30 kg au Mexique), ou que Mercado Envios renvoie une erreur ou aucune option pour l'adresse. La ligne du pays (ou la ligne *) est utilisée, sinon le coût de repli. S'il n'y a pas de prix, le transporteur est masqué. Le client ne voit jamais d'erreur de l'API.

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 calcule uniquement les tarifs. Il ne crée pas d'envois, n'imprime pas d'étiquettes et ne suit pas les colis. Créez l'envoi dans votre compte Mercado Libre ou Mercado Pago. Il affiche un seul prix, l'option Mercado Envios la moins chère, et non un choix entre toutes les options, et il n'a pas de sélecteur de point relais (agence).

Commandes

Lorsqu'une commande est passée avec un tarif Mercado Envios en temps réel, le module conserve le nom du service, le délai de livraison estimé en jours et le tarif en temps réel. Dans le back-office, la page de commande affiche un bloc Mercado Envios avec Mercado Envios service, Estimated delivery et Live rate (excl. tax). Le client voit Mercado Envios service et Estimated delivery sur la page de détail de commande de son compte. Les commandes existantes ne sont pas affectées par les changements de tarifs ultérieurs.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Mercado Envios est le premier bloc de Modules > Module Manager > VibeFox Mercado Envios > 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-mercado-envios 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 Mercado Envios n'est pas affiché aux clients au moment du paiement 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 du paiement. 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

Mercado Envios n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Mercado Envios shipping 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 contrôlez Countries). Vérifiez les avertissements en haut de la page du module, les limites de poids et Minimum subtotal. Le transporteur a besoin d'un prix : un access token valide pour les adresses du pays de Mercado Envios, ou Country prices ou Fallback cost. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Causes typiques : pas de token, une destination hors du pays de Mercado Envios, un code postal absent ou invalide, un Exchange rate manquant, un colis au-delà de la limite de poids, ou aucune option Mercado Envios pour l'adresse.

HTTP 401 ou 403 dans les avertissements : l'access token est invalide ou expiré. Copiez à nouveau l'Access Token de production depuis le panneau développeurs de Mercado Pago.

Mercado Envios a répondu dans une autre devise : le pays du compte ne correspond pas à Mercado Envios country. Choisissez le pays de votre compte Mercado Pago.

Dans quelle devise sont les prix ? Country prices, Fallback cost et les seuils sont exprimés dans la devise par défaut de votre boutique. Les tarifs en temps réel arrivent dans la devise de votre compte Mercado Pago et sont convertis avec Exchange rate lorsque la boutique utilise une autre devise par défaut.

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

La page indique que le transporteur Mercado Envios 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 Mercado Envios et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages, le journal et les données de service enregistrées des commandes. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages et données de service des commandes sont conservés. Réinstaller le module rend au transporteur le statut qu'il avait avant la désinstallation.

Mercado Envios et Mercado Pago sont des marques de leurs propriétaires respectifs. Ce module n'est ni affilié à Mercado Envios ou Mercado Pago, ni approuvé par eux.