VibeFox Melhor Envio for OpenCart — Aide
Prérequis
OpenCart : 3.0.x (testé avec 3.0.5.0) ou 4.0.2 et ultérieur (testé avec 4.1.0.3).
PHP : 8.0 ou ultérieur.
Compte Melhor Envio (uniquement pour les devis en temps réel) : les devis en temps réel nécessitent un jeton d'accès. Dans votre compte Melhor Envio, ouvrez la page des jetons (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). Les jetons de production et ceux du sandbox sont différents. Il n'y a pas de bouton « connecter » : vous collez le jeton dans les réglages de l'extension. Sans jeton, la méthode utilise les tarifs de secours.
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_melhor_envio-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_melhor_envio.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_melhor_envio-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas besoin de rafraîchir Extensions > Modifications. Au lieu de l'installateur, 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 Melhor Envio et cliquez sur Install (le bouton vert +).
3. Cliquez sur Edit (le bouton en forme de 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. Collez le jeton d'accès, votre adresse e-mail de contact et le CEP d'origine. Si la devise par défaut de votre boutique n'est pas le BRL, réglez BRL exchange rate. Vous pouvez également remplir le tableau des tarifs de secours (par exemple pour le Brésil) ou un coût de secours. Activez Enable Melhor Envio shipping et cliquez sur Save.
OpenCart 4
1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_melhor_envio.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 Melhor Envio, 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, la méthode reste désactivée tant que vous n'activez pas Enable Melhor Envio shipping et n'enregistrez pas. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages que vous avez conservés sont de nouveau utilisés.
Configuration
Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. Les sections sont listées à gauche. Un bouton Save enregistre la page entière sans la recharger. Chaque enregistrement efface aussi les devis Melhor Envio 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.
Des avertissements en haut de la page (et après chaque enregistrement) signalent une configuration incomplète : un CEP d'origine vide ou ne comportant pas 8 chiffres, une adresse e-mail de contact manquante, un taux de change vers le BRL manquant, aucun jeton et aucun tarif de secours (dans ce cas la méthode n'est jamais affichée), la dernière erreur de l'API Melhor Envio avec sa date (lorsqu'un jeton est enregistré), ou une boutique sans classe de poids « kg » ni classe de longueur « cm » (les unités sont alors converties d'après leur nom, et les unités inconnues sont lues comme kg ou cm). Si Name est vide, trop long ou contient l'un des caractères < > ; = # { }, si un champ numérique contient autre chose qu'un nombre égal ou supérieur à 0, si Min weight est supérieur à Max weight, ou si Default product size n'a pas la forme longueur x largeur x hauteur, la page affiche une erreur et rien n'est enregistré.
Général
Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter la méthode à une zone géographique dans Availability. Le tarif provient toujours de l'extension.
Enable Melhor Envio shipping : affiche ou masque Melhor Envio au moment du paiement. Par défaut : off.
Name : le nom du mode de livraison affiché aux clients dans le panier et au moment du paiement. Par défaut : Melhor Envio. Obligatoire, 64 caractères maximum.
Sort order : la position de Melhor Envio parmi les modes de livraison au moment du paiement. Un nombre entier.
API Melhor Envio
Access token : le jeton de l'environnement sélectionné ci-dessous. Il est envoyé à Melhor Envio sous forme de jeton Bearer. Après l'enregistrement, le champ reste vide et affiche A token is saved — leave empty to keep it. Ne saisissez un nouveau jeton que pour le modifier. Pour supprimer le jeton enregistré, cochez Remove the saved token puis enregistrez. Le jeton n'est jamais écrit dans le journal.
Sandbox : utilisez le sandbox de Melhor Envio (sandbox.melhorenvio.com.br) pour les tests. Utilisez avec lui un jeton de sandbox. Par défaut : off.
Contact e-mail : une adresse e-mail de contact technique, transmise à Melhor Envio dans l'en-tête User-Agent de chaque requête, par exemple tech@example.com. Melhor Envio l'exige de chaque intégration. Une adresse non valide n'est pas enregistrée, et un avis le signale.
Origin CEP : le CEP (8 chiffres) d'où partent les colis, par exemple 01310-100. OpenCart ne dispose pas de code postal pour la boutique : les devis en temps réel nécessitent donc ce champ. Un CEP qui ne comporte pas 8 chiffres est enregistré avec un avis, mais aucun devis n'est demandé.
Services : identifiants de service Melhor Envio, séparés par des virgules et facultatifs, à chiffrer, par exemple 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Laissez vide pour chiffrer chaque service de votre compte.
Quotes at checkout : la manière dont les devis 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 : on.
Declared value : déclare la valeur des produits (assurance) dans les devis. Lorsqu'elle est désactivée, les devis sont établis sans valeur déclarée : moins chers, mais les colis ne sont pas assurés. Par défaut : on.
BRL exchange rate : Melhor Envio établit ses devis en réals brésiliens. Seulement nécessaire si la devise par défaut de votre boutique n'est pas le BRL : saisissez le prix de 1 BRL dans votre devise par défaut, par exemple 0.17. Sans lui, les devis en temps réel ne sont pas utilisés. La valeur doit être supérieure à 0. La valeur déclarée est convertie en BRL au même taux. Si votre devise par défaut est le BRL, le champ indique que les tarifs de Melhor Envio sont utilisés tels quels.
Default product weight (kg) : utilisé pour les produits sans poids, à la fois dans les devis et pour les limites de poids. Doit être supérieur à 0. Par défaut : 0.3.
Default product size (cm) : longueur x largeur x hauteur, utilisé pour les produits sans dimensions. Par défaut : 16x11x5.
Tarifs de secours (dans la devise par défaut de votre boutique)
Les tarifs 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 devis (erreur, délai dépassé, absence de couverture).
Fallback price table : tarif par pays et par poids du panier, hors taxes. Cliquez sur Add country pour ajouter une ligne (une nouvelle ligne commence par le Brésil) et sur le bouton de suppression pour en retirer une. Choisissez * Any country pour chaque pays sans ligne propre. Chaque ligne comporte un Price et des colonnes de poids : XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg et XL au-delà de 5 kg. Une colonne vide ou égale à 0 utilise le Price, et un Price de 0 signifie livraison gratuite. « 9.99 » et « 9,99 » sont acceptés. Les valeurs qui ne sont pas des nombres sont signalées après l'enregistrement et ignorées. Les lignes sans aucun tarif sont supprimées.
Fallback cost : utilisé lorsque le tableau ne donne pas non plus de tarif. Laissez le champ vide pour masquer la méthode dans ce cas.
Fallback calculation : Per order (par défaut) facture le tarif de secours une seule fois. Per item (each item priced by its own weight x quantity) recherche le tarif 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 tarifs de secours. Les devis de Melhor Envio incluent déjà tous les articles.
Disponibilité
Min weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).
Max weight (kg) : masque la méthode lorsque le panier pèse davantage. Par défaut : 30. 0 signifie aucune limite. Un champ vide signifie 30 kg, ou aucune limite lorsque Ignore shipping zones est activé.
Minimum subtotal : n'affiche la méthode que si le sous-total du panier (produits nécessitant une livraison, après le coupon, avant taxes) atteint au moins ce montant. Laissez le champ 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 tarif. Laissez le champ vide pour désactiver cette option.
Tax class : la classe de taxe ajoutée au coût de livraison, ou No tax (par défaut). Les tarifs de Melhor Envio sont des tarifs finaux des transporteurs. Choisissez No tax si OpenCart ne doit pas y ajouter de taxe.
Geo zone : propose Melhor Envio uniquement pour les adresses situées dans cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques sont gérées dans System > Localisation > Geo Zones. La zone géographique n'est pas vérifiée lorsque Ignore shipping zones est activé.
Disponibilité sans zones de livraison
En règle générale, la méthode est proposée dans la zone géographique sélectionnée dans Availability (toutes les zones si aucune n'est sélectionnée).
Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, quelle que soit la zone géographique sélectionnée. Dans ce mode, la zone géographique n'est pas vérifiée.
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é.
Avancé
Debug log : écrit les requêtes à l'API et le calcul des tarifs dans storage/logs/vfd_menv_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_menv_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. Le jeton n'est jamais journalisé, et le CEP du client est raccourci à ses 5 premiers chiffres. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_menv_debug.old.log.php et un nouveau journal est créé.
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 tous les réglages de l'extension ainsi que le journal. Lorsqu'il est désactivé (par défaut), ils sont conservés pour une réinstallation. Le cache des devis est toujours supprimé. Les services enregistrés avec les commandes font partie de l'historique des commandes et sont conservés.
Importer / Exporter
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 tarif de Melhor Envio. Si une Geo zone est définie et que l'adresse se trouve en dehors, Melhor Envio n'est pas proposé. Avec Ignore shipping zones, la zone géographique n'est pas vérifiée : Melhor Envio n'est proposé que si le pays figure dans Countries (ou si Countries est vide). Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. L'extension vérifie ensuite le poids du panier et le sous-total minimal.
Pour une adresse de livraison au Brésil avec un CEP de 8 chiffres, l'extension transmet à Melhor Envio le CEP d'origine et celui 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. Le Model du produit est transmis comme identifiant d'article. Les services en erreur ou sans tarif sont ignorés. Les devis sont convertis dans votre devise par défaut, arrondis à ses décimales, triés par prix et affichés dans la devise du client, avec la taxe de la Tax class sélectionnée. Si la livraison gratuite s'applique, le service le moins cher coûte 0.
Avec One option - the cheapest service, le client voit une seule option, par exemple Melhor Envio (6-7 business days). Avec One option per service, le client voit une option par service, par exemple Melhor Envio : Correios SEDEX (1-2 business days). Le délai estimé n'est ajouté que lorsque Delivery time est activé.
Chaque devis est mis en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle requête. Un appel échoué est mémorisé pendant 5 minutes, afin qu'une panne de l'API ne ralentisse pas chaque actualisation du paiement. Le délai d'expiration de l'API est de 12 secondes.
S'il n'y a pas de jeton, si l'adresse est située hors du Brésil ou n'a pas encore de CEP valide, si le taux de change vers le BRL est manquant, ou si Melhor Envio renvoie une erreur ou aucun service pour cet itinéraire, les tarifs de secours sont utilisés : la ligne du pays (ou la ligne * lorsque le pays n'a pas de ligne), sinon le coût de secours. Cette option porte simplement le nom indiqué dans Name. Si la livraison gratuite s'applique, la méthode est affichée sans frais, même sans tarif. S'il n'y a aucun tarif, la méthode est masquée. Le client ne voit jamais d'erreur d'API. La raison est écrite dans le journal.
Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit une option Melhor Envio dans la fenêtre Shipping method options. Les options et les tarifs sont les mêmes que sur OpenCart 3.
L'extension ne calcule que les tarifs. 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 ne propose pas de choisir une agence de transport (point de dépôt). Gérez vos envois dans votre espace Melhor Envio. Melhor Envio n'expédie qu'à l'intérieur du Brésil. Les autres pays ne reçoivent que les tarifs de secours.
Commandes
OpenCart enregistre le nom de l'option choisie comme mode de livraison de la commande : le service et le délai estimé apparaissent donc dans les e-mails de commande, dans le compte du client et dans Sales > Orders.
Lorsqu'une commande est passée avec un devis en temps réel, l'extension enregistre aussi le service Melhor Envio exactement tel que le client l'a vu à l'étape de livraison, sans nouvelle requête. La page de commande de l'administration, dans Sales > Orders, affiche un bloc Melhor Envio avec Melhor Envio service, Service ID et Delivery estimate, afin que vous sachiez quel service acheter dans Melhor Envio. Le client voit Melhor Envio service et Delivery estimate sur la page de commande de son compte. Les commandes passées avec un tarif de secours n'ont pas de service. Les commandes existantes ne sont pas affectées.
Sur OpenCart 4, le bloc Melhor Envio 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 tarif de secours.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Melhor Envio est le premier bloc de Extensions > Extensions > Shipping > VibeFox Melhor Envio > 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-melhor-envio et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation Modify pour l'extension peuvent modifier 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 issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, le mode de livraison Melhor Envio 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
Melhor Envio n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Melhor Envio shipping est activé. Contrôlez la Geo zone, ou activez Ignore shipping zones et contrôlez Countries. Consultez les avertissements en haut de la page de l'extension, les limites de poids et le Minimum subtotal. Sans jeton ni devis, la méthode a besoin d'un tarif de secours : une ligne dans le Fallback price table ou un Fallback cost. Vérifiez que les produits ont Requires Shipping réglé sur Yes.
Seuls les tarifs de secours s'affichent : activez Debug log, rechargez le paiement et regardez le champ Log sur la page de l'extension. Raisons habituelles : pas de jeton, un CEP d'origine ne comportant pas 8 chiffres, pas de BRL exchange rate pour une devise par défaut 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 refusé le jeton d'accès. Il est erroné, expiré ou révoqué, ou il appartient à l'autre environnement. Générez un nouveau jeton et vérifiez que Sandbox correspond.
Une taxe est ajoutée au tarif de Melhor Envio : réglez Tax class sur No tax.
Les devis semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide le cache des devis.
La page indique « Warning: You do not have permission to modify VibeFox Melhor Envio! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_melhor_envio (OpenCart 3) ou extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) dans System > Users > User Groups.
Pour les développeurs : l'adresse de l'API de devis de Melhor Envio peut être remplacée par le réglage vfd_menv_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 Melhor Envio. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Melhor Envio shipping, Sort order, Tax class et Geo zone. Le cache des devis est toujours supprimé. Si Remove data on uninstall est activé, les autres réglages et le journal de débogage sont également supprimés. S'il est désactivé, ils sont conservés et réutilisés lorsque vous réinstallez l'extension. Les services enregistrés avec les commandes sont toujours conservés, 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 Melhor Envio dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.
Melhor Envio est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Melhor Envio ni approuvée par Melhor Envio.