VibeFox Melhor Envio 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 Melhor Envio (uniquement pour les tarifs en direct) : les tarifs en direct nécessitent un jeton d'accès. Dans votre compte Melhor Envio, ouvrez la page des autorisations d'accès pour les jetons (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) et générez un jeton avec l'autorisation « shipping-calculate ». Pour les tests, générez un jeton dans le sandbox de Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Les jetons de production et de sandbox sont différents. Les jetons expirent. Il n'y a pas de bouton « connecter » : vous collez le jeton dans les réglages. Sans jeton, la méthode utilise les prix de secours.
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_melhor_envio dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Melhor Envio, ou cliquez sur Settings sous le nom de l'extension dans la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Collez le jeton d'accès, votre e-mail de contact et le CEP d'origine. Si la devise de votre boutique n'est pas le BRL, renseignez le BRL exchange rate. Vous pouvez aussi remplir la grille de prix de secours (par exemple pour le Brésil) ou un coût de secours.
6. Ajoutez une zone pour le Brésil dans WooCommerce > Settings > Shipping > Shipping zones et ajoutez-y VibeFox Melhor Envio, ou activez Ignore shipping zones et choisissez des pays.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Melhor Envio. 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 global.
Des avertissements en haut de la page signalent une configuration incomplète : un CEP d'origine qui ne compte pas 8 chiffres, un e-mail de contact manquant, un taux de change BRL manquant, la dernière erreur de l'API Melhor Envio avec sa date, ou l'absence de jeton et de prix de secours. À chaque enregistrement des réglages, les tarifs en cache sont vidés.
Général
Enable/Disable : active ou désactive la livraison Melhor Envio dans toutes les zones à la fois.
Name : le nom de la méthode de livraison affiché aux clients au paiement. Par défaut : Melhor Envio.
Tax status : Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas.
API Melhor Envio
Access token : le jeton de l'environnement sélectionné ci-dessous. Il n'est jamais écrit dans le journal.
Sandbox : utilise le sandbox de Melhor Envio (sandbox.melhorenvio.com.br) pour les tests. Utilisez-le avec un jeton de sandbox. Par défaut : désactivé.
Contact e-mail : une adresse e-mail de contact technique, envoyée à Melhor Envio avec chaque requête. Melhor Envio l'exige de toutes les intégrations.
Origin CEP : le CEP (8 chiffres) d'où les colis sont expédiés, par exemple 01310-100. Sans CEP d'origine valide, aucun tarif n'est demandé.
Services : identifiants de service Melhor Envio facultatifs, séparés par des virgules, à demander, par exemple 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Laissez vide pour demander tous les services de votre compte.
Quotes at checkout : la manière dont les tarifs sont affichés.
Delivery time : affiche le délai de livraison estimé par Melhor Envio à côté du nom, par exemple « (3-5 business days) ». Par défaut : activé.
Declared value : déclare la valeur des produits (assurance) dans les tarifs. Lorsqu'elle est désactivée, les tarifs sont demandés sans valeur déclarée : moins chers, mais les colis ne sont pas assurés. Par défaut : activé.
BRL exchange rate : Melhor Envio établit ses tarifs en reais brésiliens. Nécessaire uniquement si la devise de votre boutique n'est pas le BRL : saisissez le prix de 1 BRL dans la devise de votre boutique, par exemple 0.17. Sans ce taux, les tarifs en direct ne sont pas utilisés. La valeur déclarée est convertie en BRL au même taux.
Default product weight (kg) : utilisé pour les produits sans poids, aussi bien dans les tarifs que pour les limites de poids. Par défaut : 0.3.
Default product size (cm) : longueur x largeur x hauteur utilisées pour les produits sans dimensions. Par défaut : 16x11x5.
Fallback prices (dans la devise de votre boutique)
Les prix de secours sont utilisés lorsqu'il n'y a pas de jeton, que le CEP de destination est manquant ou que l'API ne fournit aucun tarif (erreur, délai dépassé, absence de couverture).
Fallback price table : prix par pays et par poids du panier. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * Any country pour tous les pays sans ligne propre. Chaque ligne comporte 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 vide ou à 0 utilise le Price. « 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 et ignorées.
Fallback cost : utilisé lorsque la grille n'a pas de prix non plus. Laissez-le vide pour masquer la méthode dans ce cas.
Fallback calculation : Per order facture le prix de secours une seule fois. Per item (each item priced by its own weight x quantity) recherche le prix de secours pour le poids de chaque article (le poids par défaut s'il n'en a pas) et le multiplie par sa quantité. Cela ne s'applique qu'aux prix de secours. Les tarifs de Melhor Envio incluent déjà tous les articles.
Availability
Min weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie aucune limite.
Max weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 30. 0 signifie aucune limite.
Minimum subtotal : affiche la méthode seulement si le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour l'afficher toujours.
Free shipping from : le sous-total du panier à partir duquel la livraison est gratuite. Avec une option par service, seul le service le moins cher devient gratuit. Les services plus rapides conservent leur prix. Laissez vide pour désactiver.
Excluded shipping classes : masque la méthode lorsque le panier contient des articles appartenant à 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 si elle n'est pas 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é.
Advanced
Debug log : enregistre les requêtes API et le calcul des tarifs dans WooCommerce > Status > Logs (source vfd-melhor-envio). Les erreurs sont toujours enregistrées, même lorsque cette option est désactivée. Le jeton et les adresses des clients ne sont jamais enregistré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 de livraison exclues.
Pour une adresse de livraison au Brésil avec un CEP à 8 chiffres, l'extension envoie à Melhor Envio les CEP d'origine et de destination, ainsi que chaque article expédiable avec son poids, sa taille, sa quantité et sa valeur déclarée, plus la liste des services si vous en avez défini une. Les tarifs sont convertis dans la devise de votre boutique et triés par prix. Le client voit le service le moins cher ou une option par service, avec le délai estimé si celui-ci est activé. Si la livraison gratuite s'applique, le service le moins cher coûte 0.
Chaque tarif est mis en cache pendant 1 heure par colis, CEP et environnement, pour qu'un même panier ne déclenche pas une nouvelle requête. Un appel échoué est retenu pendant 5 minutes, afin qu'une panne de l'API ne ralentisse pas chaque actualisation du paiement. Le délai d'attente de l'API est de 12 secondes.
S'il n'y a pas de jeton, si l'adresse est hors du Brésil ou n'a pas encore de CEP valide, si le taux de change BRL manque, ou si Melhor Envio renvoie une erreur ou aucun service pour l'itinéraire, les prix de secours sont utilisés : la ligne du pays (ou la ligne *), sinon le coût de secours. Si la livraison gratuite s'applique, la méthode est affichée sans frais même sans prix. 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 sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension ne calcule que les prix. Elle n'achète ni ne génère d'étiquettes, n'ajoute pas d'envois au panier de Melhor Envio, ne suit pas les colis, ne planifie pas d'enlèvements et n'envoie pas les données de facture (NF-e). Elle n'offre pas le choix d'agences (points de dépôt) Jadlog, Azul ou LATAM, ni les services supplémentaires « remise en main propre » et « accusé de réception ». Gérez vos envois dans votre espace Melhor Envio. Melhor Envio n'expédie qu'au Brésil. Les autres pays ne reçoivent que les prix de secours.
Commandes
Lorsque la commande est passée avec un tarif en direct, le service et le délai estimé sont enregistrés sur la ligne de livraison de la commande. Ils sont affichés sur l'écran de commande et dans les e-mails de commande sous les libellés Melhor Envio service et Delivery estimate, pour que vous sachiez quel service acheter dans Melhor Envio. Les commandes existantes conservent leurs lignes de livraison.
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 Melhor Envio. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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, Melhor Envio n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique 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 Extensions et sur les pages WooCommerce. 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 en arrière-plan.
Dépannage
Melhor Envio 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é). Consultez les avertissements en haut de la page des réglages, les limites de poids, Minimum subtotal et Excluded shipping classes. Sans jeton ni tarif, la méthode a besoin d'un prix de secours : une ligne dans la Fallback price table ou un Fallback cost.
Seuls les prix de secours s'affichent : activez le Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd-melhor-envio. Causes fréquentes : pas de jeton, un CEP d'origine qui ne compte pas 8 chiffres, pas de BRL exchange rate pour une devise de boutique autre que le BRL, pas encore de CEP de destination ou aucun service ne couvre l'itinéraire.
HTTP 401 ou 403 dans le journal ou les avertissements : Melhor Envio a rejeté le jeton d'accès. Il est incorrect, expiré ou révoqué, ou il appartient à l'autre environnement. Générez un nouveau jeton et vérifiez que Sandbox correspond à ce jeton.
Le prix vu par les clients : avec une option, le service le moins cher renvoyé par Melhor Envio. Avec une option par service, chaque service desservant l'itinéraire. Per item ne s'applique qu'aux prix de secours.
Les tarifs semblent périmés après une modification : enregistrez la page des réglages. Cela vide 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 statut 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 le statut de licence de cette extension, ainsi que les tarifs en cache, 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 future réinstallation. Les commandes existantes conservent leurs lignes de livraison.
Melhor Envio est une marque déposée de son titulaire. Cette extension n'est ni affiliée à Melhor Envio ni approuvée par Melhor Envio.