VibeFox Melhor Envio for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

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 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 bac à sable (sandbox) de Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Les jetons de production et du bac à sable sont différents. Il n'y a pas de bouton « connecter » : vous collez le jeton dans les réglages du module. Sans jeton, le transporteur utilise les prix de secours.

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 Melhor Envio 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. Collez le jeton d'accès, votre e-mail de contact et le CEP d'origine. Si la devise par défaut de votre boutique n'est pas le BRL, renseignez BRL exchange rate. Vous pouvez aussi compléter la grille de prix de secours (par exemple pour le Brésil) ou un coût de secours. Cliquez sur Save.

À l'installation, le module crée le transporteur Melhor Envio avec le texte de délai de livraison Delivery by the carriers of your Melhor Envio account. Le transporteur est associé à toutes les zones et à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. N'y définissez pas de prix : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Melhor Envio > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs de Melhor Envio et la dernière erreur de l'API.

Des avertissements en haut de la page signalent une configuration incomplète : un CEP d'origine vide ou ne comptant pas 8 chiffres, un e-mail de contact manquant, un taux de change BRL manquant, la dernière erreur de l'API de Melhor Envio avec sa date, l'absence de jeton, l'absence de prix de secours (dans ce cas, le transporteur n'est jamais affiché), ou une unité de poids ou de dimensions de la boutique que le module ne connaît pas (elle est alors lue comme kg ou cm). Si un champ numérique contient autre chose qu'un nombre supérieur ou égal à 0, si Min weight est supérieur à Max weight, ou si Default product size n'est pas au format longueur x largeur x hauteur, la page affiche une erreur et rien n'est enregistré.

General

Enable Melhor Envio 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 paiement. Par défaut : Melhor Envio. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax. Les prix de Melhor Envio sont des prix finaux du transporteur. Choisissez No tax si PrestaShop ne doit pas ajouter de taxe à ces prix.

Melhor Envio API

Access token : le jeton de l'environnement sélectionné ci-dessous. Il est envoyé à Melhor Envio comme jeton Bearer. Après l'enregistrement, le champ reste vide et affiche A token is saved — leave empty to keep it. Saisissez un nouveau jeton uniquement pour le remplacer. Pour supprimer le jeton enregistré, cochez Remove the saved token et enregistrez. Le jeton n'est jamais écrit dans le journal.

Sandbox : utilise le bac à sable de Melhor Envio (sandbox.melhorenvio.com.br) pour les tests. Utilisez-le avec un jeton du bac à sable. Par défaut : désactivé.

Contact e-mail : une adresse e-mail de contact technique, envoyée à Melhor Envio dans l'en-tête User-Agent de chaque requête. Melhor Envio l'exige de toutes les intégrations. Une adresse invalide n'est pas enregistrée et un avertissement le signale.

Origin CEP : le CEP (8 chiffres) d'où les colis sont expédiés, par exemple 01310-100. Il est enregistré au format 00000-000. Sans CEP d'origine valide, aucun tarif n'est demandé.

Services : identifiants de services Melhor Envio séparés par des virgules, à demander en tarif (facultatif), 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 au paiement, par exemple « 3-5 business days ». Par défaut : activé.

Declared value : déclare la valeur des produits (assurance) dans les tarifs. Lorsque l'option est désactivée, les tarifs sont demandés sans valeur déclarée : ils sont 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. Ce champ n'est nécessaire que 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 tarifs en direct ne sont pas utilisés. La valeur doit être supérieure à 0. La valeur déclarée est convertie en BRL avec le même taux. Si votre devise par défaut est le BRL, le champ affiche Store currency is BRL.

Default product weight : en kg, pour les produits sans poids, à la fois pour les tarifs et pour les limites de poids. Doit être supérieur à 0. Par défaut : 0.3.

Default product size : longueur x largeur x hauteur en cm, pour les produits sans dimensions. Par défaut : 16x11x5.

Prix de secours (dans la devise par défaut de votre boutique)

Les prix de secours sont utilisés lorsqu'il n'y a pas de jeton, que le CEP de destination est absent ou que l'API ne donne pas de tarif (erreur, délai dépassé, pas de couverture).

Fallback price table : prix par pays et par poids du panier. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * Default comme pays pour tous les pays qui n'ont pas leur propre ligne. 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 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 ne contient pas non plus de prix. Laissez-le vide pour masquer le transporteur 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é. Si un article n'a pas de prix, le transporteur est masqué. Cela ne s'applique qu'aux prix de secours. Les tarifs de Melhor Envio incluent déjà tous les articles.

Disponibilité

Min weight : masque le transporteur lorsque le panier pèse moins, en kg. 0 signifie aucune limite.

Max weight : masque le transporteur lorsque le panier pèse plus, en kg. Par défaut : 30. 0 signifie aucune limite. Un champ vide signifie 30 kg dans les zones du transporteur, et aucune limite uniquement pour les pays de Ignore shipping zones situés en dehors de celles-ci.

Minimum subtotal : n'affiche le transporteur que si le sous-total du panier (produits nécessitant une livraison, après remises, avant taxes) atteint au moins 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.

Ignore shipping zones : propose le transporteur dans les pays indiqués ci-dessous même s'il n'est pas associé à leurs zones. Tant que cette option est activée, le transporteur est lié à toutes les zones, y compris les zones inactives et celles créées ultérieurement. Lorsque vous la désactivez, le transporteur retrouve ses propres zones.

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 logs/vfd_menv_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même si cette option est désactivée. Le jeton n'est jamais journalisé et le CEP du client est raccourci à ses 5 premiers chiffres.

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 : lorsque l'option est activée, la désinstallation du module supprime tous ses réglages, le transporteur et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Le cache des tarifs est toujours supprimé. Les services enregistrés avec les commandes font partie de l'historique des commandes et sont conservés.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix de Melhor Envio. Seuls les produits nécessitant une livraison 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 : les pays de Ignore shipping zones, le poids du panier et le sous-total minimum.

Pour une adresse de livraison au Brésil avec un CEP de 8 chiffres, le module 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 votre devise par défaut, triés par prix, puis affichés dans la devise du panier du client. Si la livraison gratuite s'applique, le service le moins cher coûte 0.

Avec One option - the cheapest service, le transporteur affiche le prix du service le moins cher et la ligne Delivery estimate : sous le transporteur si Delivery time est activé. Avec One option per service, le client voit Choose a delivery service : sous le transporteur, avec un bouton radio par service, son prix et le délai estimé. Le choix est enregistré immédiatement, et le prix du transporteur ainsi que le récapitulatif du panier sont mis à jour. Si le service n'est plus proposé pour l'adresse, le client voit This service is not available for your address any more. Please choose another one. et son choix précédent est rétabli.

Chaque tarif est mis en cache pendant 1 heure par colis, CEP, jeton et environnement, ainsi 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'attente de l'API est de 12 secondes.

S'il n'y a pas de jeton, si l'adresse se situe 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, le transporteur est affiché sans frais, même sans prix. S'il n'existe aucun prix, le transporteur est masqué. Le client ne voit jamais d'erreur de l'API.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne calcule que des prix. Il 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). Il ne propose pas la sélection 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 les envois dans votre panneau Melhor Envio. Melhor Envio n'expédie qu'à l'intérieur du Brésil. Les autres pays ne reçoivent que les prix de secours.

Commandes

Lorsqu'une commande est passée avec un tarif en direct, le module enregistre avec la commande le service Melhor Envio et son délai de livraison estimé. La page de commande du back office affiche un bloc Melhor Envio avec Melhor Envio service (avec l'identifiant du service) et Delivery estimate, pour que vous sachiez quel service acheter dans Melhor Envio. Le client voit les mêmes informations sur la page de sa commande dans son compte. Dans l'e-mail de confirmation de commande, elles sont ajoutées après le nom du transporteur. Les commandes passées avec un prix de secours n'ont pas de service. Les commandes existantes ne sont pas affectées.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Melhor Envio est le premier bloc de Modules > Module Manager > VibeFox Melhor Envio > Configure, 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), 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-melhor-envio 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 : celui 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Melhor Envio n'est pas affiché aux clients au moment du paiement, et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back office : le transporteur est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au 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 votre travail dans le back office : 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 ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Melhor Envio n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Melhor Envio 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 vérifiez Countries. Consultez les avertissements en haut de la page du module, les limites de poids et Minimum subtotal. Sans jeton ni tarif, le transporteur a besoin d'un prix de secours : une ligne dans Fallback price table ou un Fallback cost. Les produits peuvent aussi être limités à certains transporteurs sur leur page produit.

Seuls les prix de secours s'affichent : activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Causes habituelles : pas de jeton, CEP d'origine ne comptant 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 incorrect, expiré ou révoqué, ou il appartient à l'autre environnement. Générez un nouveau jeton et vérifiez que Sandbox correspond.

Le client voit « The service could not be saved. Please try again. » : le choix n'a pas atteint la boutique, par exemple à cause d'une erreur réseau. Le client peut choisir à nouveau le service. Le service sélectionné au moment où le client clique sur Continue est aussi enregistré.

La taxe est ajoutée au prix de Melhor Envio : réglez Tax sur No tax.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs.

La page indique que le transporteur Melhor Envio 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 Melhor Envio et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le cache des tarifs est toujours supprimé. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ses propres zones sont restaurées, et les réglages, les choix de service des paniers ouverts et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur le statut qu'il avait auparavant. Les services enregistrés avec les commandes sont toujours conservés.

Melhor Envio est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à Melhor Envio, ni approuvé par Melhor Envio.