VibeFox Mercado Envios 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).

PHP : 8.0 ou ultérieur.

Compte Mercado Pago (pour les tarifs en temps réel uniquement) : les tarifs en temps réel proviennent du calculateur 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 du jeton d'accès de production (il commence par APP_USR-) : dans Mercado Pago Developers, ouvrez votre application et ses identifiants de production. Il n'y a pas de bouton de connexion : vous collez le jeton dans les réglages de l'extension. 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

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_mercado_envios-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_mercado_envios.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_mercado_envios-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 Mercado Envios 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 du bloc de licence en haut de la page Edit et cliquez sur Activate (voir Clé de licence).

5. Pour les tarifs en temps réel, collez le jeton d'accès, choisissez le pays Mercado Envios et, si la devise par défaut de votre boutique n'est ni ARS, ni BRL, ni MXN, le taux de change. Vous pouvez éventuellement remplir Country prices et Fallback cost (utilisés sans tarifs en temps réel). Activez Enable Mercado Envios shipping et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_mercado_envios.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 Mercado Envios, 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 Mercado Envios shipping 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 Mercado Envios > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les tarifs Mercado Envios en cache et la dernière erreur de l'API. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Les avertissements de la section General (et après chaque enregistrement) signalent les problèmes de configuration : un taux de change manquant, aucun jeton d'accès ni aucun prix (le mode n'est alors jamais affiché), la dernière erreur de l'API Mercado Envios avec sa date, et une unité de poids ou de longueur de la boutique que l'extension ne connaît pas (elle est alors lue en kg ou en cm). Si Name est vide ou dépasse 64 caractères, si Exchange rate n'est pas un nombre positif, si un autre champ numérique n'est pas un nombre égal ou supérieur à 0, ou si Min weight est supérieur à Max weight, la page affiche une erreur et rien n'est enregistré.

Général

Le client voit un seul tarif Mercado Envios. Vous pouvez limiter le mode à une zone géographique ou à des pays dans Availability. Ces réglages s'appliquent à toutes les zones.

Enable Mercado Envios shipping: affiche ou masque Mercado Envios 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 : Mercado Envios. Obligatoire, 64 caractères maximum.

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Mercado Envios annonce des prix finaux. No tax les affiche tels quels ; une classe de taxe ajoute votre taxe de livraison par-dessus.

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

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

Access token: votre jeton d'accès Mercado Pago de production (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. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved access token: activez-le et enregistrez pour supprimer le jeton enregistré. Seuls les prix ci-dessous sont alors utilisés. Un jeton saisi ci-dessus remplace à la place celui qui est enregistré.

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 cotés dans sa devise.

Exchange rate: nécessaire uniquement lorsque 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 de jeton d'accès, pour les destinations hors du pays Mercado Envios, et lorsque l'API ne fournit pas de tarif (une requête échouée est renouvelée après 5 minutes). 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 le bouton de suppression 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 du panier. Une colonne vide ou égale à 0 utilise Price. Un Price de 0 signifie livraison gratuite vers ce pays. Les valeurs 9.99 et 9,99 sont acceptées. 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 fournissent de prix. Laissez-le vide pour masquer le mode dans ce cas.

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

Disponibilité

Min weight (kg): le poids minimum du panier pour que ce mode apparaisse. 0 signifie aucune limite (par défaut).

Max weight (kg): masque le mode lorsque le panier pèse davantage. Par défaut : 25. Vide signifie 25 kg, 0 signifie aucune limite.

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

Geo zone: ne propose Mercado Envios 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.

Ignore shipping zones: propose le mode pour les pays indiqués ci-dessous, quelle que soit la zone géographique sélectionnée.

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

Livraison gratuite

Free shipping from: le sous-total des produits à expédier (après le coupon, avant taxes) à partir duquel ce mode est gratuit. Aucune requête API n'est faite dans ce cas. Laissez vide pour désactiver.

Avancé

Debug log: écrit les requêtes API et le calcul des tarifs dans storage/logs/vfd_mrcv_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_mrcv_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. Le jeton d'accès et les adresses des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_mrcv_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 tarifs en cache sont toujours supprimés. Les données Mercado Envios des commandes passées sont toujours conservées dans l'historique des commandes.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le jeton d'accès n'est pas exporté.

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. Le jeton d'accès enregistré est conservé.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Mercado Envios. Si une Geo zone est définie et que l'adresse est en dehors, Mercado Envios n'est pas proposé (sauf si Ignore shipping zones est activé ; c'est alors Countries qui décide). 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. L'extension vérifie ensuite le poids du panier et le sous-total minimum. Le sous-total 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 le crédit 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 à Mercado Envios.

Pour une destination du pays Mercado Envios avec un code postal valide (4 chiffres en Argentine, également à partir d'un CPA comme C1425ABC ; 8 chiffres au Brésil ; 5 chiffres au Mexique), l'extension 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. Les poids et dimensions des produits sont convertis à partir de leurs classes de poids et de longueur OpenCart. 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 quand 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, arrondie à ses décimales et affichée dans la devise du client avec la taxe de la Tax class sélectionnée.

Chaque devis est mis en cache pendant jusqu'à 1 heure (sans dépasser la durée de vie du cache OpenCart), 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, rejette le jeton, limite les requêtes ou répond dans une autre devise, 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 jeton, que la destination est hors du pays Mercado Envios, que le code postal est absent ou non valide, que le taux de change est absent, que le colis est plus lourd que la limite 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. On utilise la ligne du pays (ou la ligne *), sinon le coût de repli. S'il n'y a aucun prix, le mode est masqué. Le client ne voit jamais d'erreur API.

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

L'extension calcule uniquement des tarifs. Elle 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. Elle affiche un seul prix, l'option Mercado Envios la moins chère, et non un choix parmi toutes les options, et elle n'a pas de sélecteur de point de retrait (agence).

Commandes

Lorsqu'une commande est passée avec un tarif Mercado Envios en temps réel, l'extension conserve le nom du service, le délai de livraison estimé en jours et le tarif en temps réel. Dans Sales > Orders, la page de commande affiche un bloc Mercado Envios avec Mercado Envios service, Estimated delivery et Live rate (excl. tax). Le bloc s'affiche même si le mode est désactivé par la suite. Un client inscrit voit Mercado Envios service et Estimated delivery sous le mode de livraison sur la page de commande de son compte, et les mêmes lignes sont ajoutées à l'e-mail de nouvelle commande. Les commandes passées avec un prix de tableau ou le coût de repli n'ont pas de service. Les commandes existantes ne sont pas affectées par les changements de tarifs ultérieurs.

Sur OpenCart 4, le bloc Mercado Envios 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 service enregistré est mis à jour avec elle, et il est supprimé lorsque le client passe à un autre mode de livraison ou lorsque la commande reçoit un prix de tableau ou le coût de repli.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Mercado Envios est le premier bloc de Extensions > Extensions > Shipping > VibeFox Mercado Envios > 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-mercado-envios 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é 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 de la configuration OpenCart. Retirer la clé de la boutique ne libère pas sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, le mode de livraison Mercado Envios 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

Mercado Envios n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Mercado Envios shipping est activé. Vérifiez Geo zone, ou activez Ignore shipping zones et vérifiez Countries. Consultez les avertissements de la page de l'extension, les limites de poids et Minimum subtotal. Le mode a besoin d'un prix : un jeton d'accès valide pour les adresses du pays Mercado Envios, ou Country prices ou Fallback cost. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez la page de paiement et consultez le champ Log de la page de l'extension. Raisons courantes : pas de jeton, destination hors du pays Mercado Envios, code postal absent ou invalide, Exchange rate manquant, colis dépassant la limite de poids, ou aucune option Mercado Envios pour l'adresse.

HTTP 401 ou 403 dans les avertissements : le jeton d'accès est invalide ou expiré. Copiez à nouveau le jeton d'accès de production depuis Mercado Pago Developers.

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.

Devise des 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 de l'extension. Cela efface les tarifs en cache.

La page affiche "Warning: You do not have permission to modify VibeFox Mercado Envios!" : 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_mercado_envios (OpenCart 3) ou extension/vfd_mercado_envios/shipping/vfd_mercado_envios (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Mercado Envios peut être remplacée par le réglage vfd_mrcv_api_url (pour les tests) ; il n'a pas de champ sur la page de réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Mercado Envios. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Mercado Envios shipping, Sort order, Tax class et Geo zone. Les tarifs en cache et la dernière erreur de l'API sont toujours supprimés. Si Remove data on uninstall est activé, les autres réglages et le journal de débogage sont également supprimés. Si l'option est désactivée, ils sont conservés et réutilisés lorsque vous réinstallez l'extension. Les données Mercado Envios des commandes passées sont toujours conservées, 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 Mercado Envios dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

Mercado Envios et Mercado Pago sont des marques de leurs propriétaires respectifs. Cette extension n'est ni affiliée ni approuvée par Mercado Envios ou Mercado Pago.