VibeFox Mercado Envios for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

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éveloppeur de Mercado Pago, 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. Si vous n'utilisez que des prix par pays, vous n'avez pas besoin d'un compte Mercado Pago.

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 de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_mercado_envios dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Mercado Envios, ou cliquez sur Settings sous le nom de l'extension 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. Pour les tarifs en temps réel, collez l'Access Token, choisissez le pays de Mercado Envios et, si la devise de votre boutique n'est pas ARS, BRL ou MXN, le taux de change. Facultativement, remplissez Country prices et Fallback cost (utilisés sans tarifs en temps réel).

6. Ajoutez VibeFox Mercado Envios à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

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

Title (zone) : le nom de cette option au paiement. Laissez-le vide pour utiliser le Name général.

Les avertissements en haut de la page signalent les problèmes de configuration : taux de change manquant, absence de jeton d'accès et de prix, ainsi que la dernière erreur de l'API Mercado Envios avec sa date. À chaque enregistrement des réglages, les tarifs en cache sont effacés.

Général

Enable/Disable : active ou désactive la livraison Mercado Envios dans toutes les zones à la fois.

Name : le nom de la méthode de livraison affiché aux clients au paiement. Par défaut : Mercado Envios.

Tax status : Mercado Envios donne des prix finaux. None les affiche tels quels ; Taxable ajoute votre taxe de livraison WooCommerce.

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

Access token : votre Access Token de production Mercado Pago (APP_USR-...). Il n'est envoyé qu'à Mercado Pago et n'est jamais journalisé.

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 si la devise de votre boutique diffère de celle de Mercado Envios : le prix de 1 ARS, BRL ou MXN dans la devise de votre boutique, par exemple 0.001. Sans lui, les tarifs en temps réel ne sont pas utilisés. Le point et la virgule sont 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 de Mercado Envios et lorsque l'API ne renvoie aucun tarif.

Country prices : prix dans la devise de votre boutique. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * All other countries pour tous les pays sans ligne propre. 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 égale à 0 utilise Price. 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 à l'enregistrement.

Fallback cost : utilisé lorsque ni l'API ni Country prices ne donnent de prix. Laissez-le vide pour masquer la méthode 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 dans le Fallback cost) le prix correspondant au poids de chaque article et le multiplie par sa quantité. Les tarifs Mercado Envios en temps réel concernent toujours le colis entier.

Disponibilité

Min weight (kg) : le poids minimum du panier pour que cette méthode apparaisse. 0 signifie sans limite.

Max weight (kg) : masque la méthode lorsque le panier pèse davantage. Par défaut : 25. 0 signifie sans limite.

Minimum subtotal : n'affiche la méthode que si le sous-total du panier atteint au moins ce montant. Laissez vide pour l'afficher toujours.

Excluded shipping classes : masque la méthode lorsqu'un article du panier appartient à l'une de ces classes d'expédition WooCommerce.

Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, même sans l'avoir ajoutée à une zone de livraison.

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

Livraison gratuite

Free shipping from : le sous-total du panier à partir duquel cette méthode est gratuite. Aucune requête n'est alors envoyée à Mercado Envios. Laissez vide pour désactiver.

Avancé

Debug log : journalise les requêtes API et le calcul des tarifs dans WooCommerce > Status > Logs (source vfd-mercado-envios). Les erreurs sont toujours journalisées, même si cette option est désactivée. Le jeton d'accès et les adresses des clients ne sont jamais journalisés.

Remove data on uninstall : lorsqu'elle est activée, la suppression de l'extension efface tous ses réglages et les méthodes des zones. La désactivation de l'extension ne supprime jamais les réglages.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, sous-total minimum et classes d'expédition exclues. Si la livraison gratuite s'applique, la méthode coûte 0 et aucune requête n'est envoyée à Mercado Envios.

Pour une destination du pays de Mercado Envios avec un code postal valide, l'extension décrit le panier comme un seul colis : la plus grande largeur et la plus grande longueur des articles, la somme des hauteurs de tous les articles 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 reçoivent tout de même un tarif. La valeur du panier est transmise comme prix de l'article dans la devise de Mercado Envios. La moins chère des options renvoyées par Mercado Envios est convertie dans la devise de votre boutique et affichée sous le nom de votre méthode.

Chaque devis est mis en cache pendant 1 heure, afin qu'un 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 ou rejette le jeton, tous les devis 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 de Mercado Envios, que le code postal est absent ou non valide, que le taux de change manque, 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. La ligne du pays (ou la ligne *) est utilisée, sinon le coût de repli. S'il n'existe aucun prix, la méthode est masquée. Le client ne voit jamais d'erreur d'API.

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

L'extension calcule uniquement les 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 tarif par méthode, l'option Mercado Envios la moins chère, et non un choix entre toutes les options ; elle n'a pas de sélecteur de point relais (agence).

Commandes

Lorsque la commande est passée avec un tarif en temps réel, le nom du service et le délai de livraison estimé en jours sont enregistrés sur la ligne d'expédition de la commande sous les noms Mercado Envios service et Estimated delivery. Les commandes existantes conservent leurs lignes d'expédition.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Mercado Envios. Collez la clé dans License key puis cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

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

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

Dépannage

Mercado Envios 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 avertissements en haut de la page des réglages, les limites de poids, Minimum subtotal et Excluded shipping classes. La méthode a besoin d'un prix : un jeton d'accès valide pour les adresses du pays de Mercado Envios, ou Country prices ou Fallback cost.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez la page de paiement et ouvrez WooCommerce > Status > Logs, source vfd-mercado-envios. Causes habituelles : pas de jeton, une destination hors du pays de Mercado Envios, un code postal absent ou non valide, 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éveloppeur 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 et Fallback cost sont exprimés dans la devise 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.

Les tarifs semblent périmés après une modification : enregistrez la page des réglages. Cela efface les tarifs 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, l'extension continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation de l'extension conserve tous les réglages. Seul le cache des tarifs est vidé. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de licence de cette extension, les tarifs en cache et la dernière erreur d'API sont toujours supprimés. Les réglages et les méthodes des zones 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.

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