VibeFox Frenet for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec la version 3.0.5.0) ou 4.0.2 et ultérieur (testé avec la version 4.1.0.3).

PHP : 8.0 ou ultérieur.

Compte Frenet (uniquement pour les devis en temps réel) : créez un compte gratuit dans le panneau Frenet (painel.frenet.com.br), activez les transporteurs que vous utilisez et copiez votre jeton d'API. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de compte Frenet.

Produits : renseignez le poids et les dimensions pour des prix précis. Les produits sans ces données sont calculés comme 0,3 kg et 16 × 11 × 2 cm (le plus petit carton Correios).

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_frenet-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_frenet.ocmod.zip. Installez uniquement 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_frenet-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'installateur, vous pouvez aussi 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 Frenet et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des réglages.

4. Saisissez votre clé de licence VibeFox dans le champ 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'API et saisissez le CEP d'origine. Si votre devise par défaut n'est pas le BRL, saisissez le taux de change BRL. Vous pouvez aussi ajouter des prix fixes et un coût de secours. Activez Enable Frenet et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_frenet.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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é de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Frenet, 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'avez pas activé Enable Frenet et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Frenet que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Les sections sont listées à gauche. Un seul bouton Save, en bas, enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les devis Frenet en cache. Les champs de prix acceptent le point et la virgule comme séparateur décimal. Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison, par exemple Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. ou "…" must not be negative. Un BRL exchange rate égal ou inférieur à 0 et un Minimum weight (kg) supérieur au Maximum weight (kg) sont aussi refusés. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

En haut de la page, et de nouveau après chaque enregistrement, l'extension affiche des avertissements : pas de jeton d'API (seuls les prix fixes sont utilisés, ou la méthode n'apparaît jamais s'il n'y a pas non plus de prix fixes), pas de CEP d'origine, un CEP d'origine qui ne comporte pas 8 chiffres, ou une devise par défaut autre que le BRL sans taux de change. Elle signale aussi si votre boutique n'a pas de classe de poids avec l'unité kg ni de classe de longueur avec l'unité cm. Les poids et dimensions des produits sont alors convertis selon le nom d'unité de leur classe, et les unités inconnues sont lues comme kg ou cm. Vérifiez System > Localisation > Weight Classes et Length Classes.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter la méthode à une zone géographique dans Conditions, ou utiliser Ignore shipping zones. Le prix provient toujours de cette extension.

Enable Frenet : affiche ou masque Frenet au moment du paiement. Par défaut : désactivé.

Method title : le nom de la méthode d'expédition affiché au client dans le panier et lors du paiement. Par défaut : Frenet. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

Sort order : la position de Frenet parmi les méthodes d'expédition au moment du paiement. Un nombre entier.

Devis Frenet en temps réel

Frenet compare les transporteurs activés dans votre compte Frenet (Correios, Jadlog, Loggi et d'autres) et renvoie leurs prix pour le panier. Les devis en temps réel ne sont demandés que pour les adresses au Brésil avec un CEP complet de 8 chiffres. La section contient un lien vers le panneau Frenet.

API token : votre jeton d'API Frenet, issu du panneau Frenet. Laissez-le vide pour n'utiliser que les prix fixes. Après l'enregistrement, le champ reste vide et affiche A token is saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer le jeton enregistré, cochez Remove the saved token et enregistrez.

Origin CEP : le code postal (CEP) d'où partent les colis, par exemple 01001-000. OpenCart n'a pas de code postal de boutique, donc les devis en temps réel ont besoin de ce champ. Un CEP sans 8 chiffres est enregistré tel que saisi, et la page affiche Frenet: the origin CEP must have 8 digits.

Service to offer : Cheapest service (par défaut) ou Fastest service. Frenet renvoie plusieurs services, et la méthode affiche un seul prix. Le transporteur, le service et le délai de livraison choisis sont enregistrés avec la commande.

BRL exchange rate : Frenet calcule ses devis en réais brésiliens. Si votre devise par défaut n'est pas le BRL, saisissez la valeur de 1 BRL dans votre devise par défaut, par exemple 0.16. Le devis et la valeur déclarée de la commande sont convertis avec ce taux. Sans lui, les devis en temps réel ne sont pas utilisés. Lorsque votre devise par défaut est le BRL, le champ indique que les prix Frenet sont utilisés tels quels.

Prix fixes

Utilisés en l'absence de jeton d'API, pour les pays que Frenet ne dessert pas, et chaque fois que Frenet ne renvoie aucun prix (API indisponible, CEP non desservi).

Price per country : un tableau avec les colonnes Country, Price, XS, S, M, L et XL, avec des prix dans votre devise par défaut, hors taxes. Cliquez sur Add country pour ajouter une ligne. Les colonnes de taille dépendent du poids du panier : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg, XL au-delà de 5 kg. Price est utilisé lorsque la colonne de taille est vide. Un Price de 0 signifie livraison gratuite pour ce pays. Utilisez * Default (all other countries) pour tous les pays sans ligne propre. Les lignes sans aucun prix sont supprimées à l'enregistrement.

Fallback cost : utilisé lorsque ni Frenet ni le tableau ne donnent de prix. Laissez-le vide pour masquer la méthode.

Fixed price applies : Per order (par défaut) facture le prix une seule fois. Per item (price × quantity) le multiplie par le nombre d'articles. Cela ne s'applique qu'aux prix fixes et au coût de secours. Les devis Frenet couvrent déjà l'ensemble du panier.

Conditions

Minimum weight (kg) : masque la méthode en dessous de ce poids de panier. 0 signifie aucune limite.

Maximum weight (kg) : masque la méthode au-delà de ce poids de panier. Par défaut : 30 (utilisé aussi lorsque le champ est vide). 0 signifie aucune limite. Ce champ ne peut pas être inférieur à Minimum weight (kg).

Minimum order amount : n'affiche la méthode que si le sous-total des produits nécessitant une expédition (après le coupon, avant taxes) atteint au moins ce montant. Laissez-le vide pour toujours l'afficher.

Free shipping from : le sous-total (après le coupon, avant taxes) à partir duquel la livraison est gratuite. Laissez-le vide pour ne jamais offrir la livraison gratuite.

Tax class : la classe de taxe ajoutée au coût d'expédition, ou No tax. Les prix Frenet sont les prix finaux du transporteur. Choisissez No tax si OpenCart ne doit pas ajouter de taxe sur ces prix.

Geo zone : proposez Frenet uniquement pour les adresses de cette zone géographique. All zones signifie aucune limite. Non utilisé avec Ignore shipping zones. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Disponibilité sans zones d'expédition

En règle générale, la méthode est proposée dans la zone géographique sélectionnée dans Conditions (dans toutes les zones si aucune n'est sélectionnée).

Ignore shipping zones : proposez Frenet pour les pays indiqués ci-dessous, quelle que soit la zone géographique correspondante. La Geo zone de Conditions n'est alors pas vérifiée.

Countries : les pays de destination pour ce mode, choisis parmi les pays activés de votre boutique. Laissez-le vide pour utiliser tous les pays vers lesquels vous expédiez. Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : enregistre chaque demande et réponse de devis dans storage/logs/vfd_frn_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). Le fichier n'est pas lisible depuis le web. Les erreurs de l'API sont toujours journalisées. Le jeton n'est jamais journalisé et le CEP du client est raccourci. Désactivez-le quand vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_frn_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation de l'extension supprime tous les réglages Frenet et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les devis en cache sont toujours supprimés. Les services Frenet enregistrés avec les commandes font partie de l'historique des commandes et sont conservés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le jeton d'API 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'API enregistré est conservé.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les méthodes d'expédition, il demande à l'extension le prix Frenet. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Frenet n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite la liste des pays (si Ignore shipping zones est activé), le poids du panier et le montant minimum de commande. Le montant de la commande est le prix de ces produits, après la remise du coupon et avant taxes. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Frenet.

Pour une adresse au Brésil avec un CEP complet de 8 chiffres, et lorsque le jeton d'API et le CEP d'origine sont renseignés, l'extension envoie à Frenet les CEP d'origine et de destination, chaque article du panier (poids en kg, dimensions en cm, quantité, la Model du produit et ses catégories), la valeur de la commande en BRL et le code coupon du panier. Aucune requête n'est faite tant que le CEP est incomplet. Frenet renvoie les services de vos transporteurs activés. Les services en erreur ou sans prix sont ignorés. L'extension choisit le service le moins cher ou le plus rapide et convertit le prix dans votre devise par défaut. Le prix est arrondi aux décimales de votre devise par défaut et affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

Chaque réponse est mise en cache pendant 1 heure pour le même panier et la même adresse. Une requête échouée, ou un CEP qu'aucun transporteur activé ne dessert, est retenu pendant 10 minutes. Le délai d'attente de l'API est de 10 secondes. Dans ces cas, le client ne voit aucune erreur : le prix fixe ou le coût de secours est utilisé, ou la méthode est masquée s'il n'y en a aucun. La raison est écrite dans le journal. Pour les adresses hors du Brésil, seuls les prix fixes sont utilisés.

Sur OpenCart 4, le client clique sur Choose dans le bloc de méthode d'expédition de la page de paiement et choisit Frenet dans la fenêtre Shipping method options. La méthode fonctionne de la même façon que sur OpenCart 3.

L'extension ne calcule que des tarifs. Elle ne crée pas d'envois, n'imprime pas d'étiquettes et ne suit pas les colis. Elle affiche un seul service Frenet par panier, et non plusieurs, et ne propose ni points de retrait ni casiers. Frenet ne fournit des devis qu'au Brésil ; pour les autres pays, utilisez les prix fixes.

Commandes

Lorsqu'une commande est passée avec Frenet, l'extension enregistre la manière dont son prix d'expédition a été calculé : exactement l'option que le client a vue à l'étape d'expédition, sans nouvelle requête à Frenet. La page de commande dans Sales > Orders affiche alors un bloc Frenet avec ces lignes :

Carrier : le transporteur et le service Frenet, par exemple un service Correios ou Jadlog. Affiché pour les devis en temps réel.

Delivery time : le délai de livraison en jours ouvrés renvoyé par Frenet. Affiché pour les devis en temps réel.

Price source : Live Frenet quote, Fixed price (price per country), Fallback cost ou Free shipping.

Sur OpenCart 4, le bloc est affiché au-dessus de History. OpenCart 4 met à jour la même commande lorsque le client la confirme à nouveau : les données Frenet enregistrées sont mises à jour également, et si le client a choisi une autre méthode d'expédition, les données Frenet de la commande sont supprimées.

Le bloc est aussi affiché lorsque l'extension est désactivée. Ces données sont conservées lors de la désinstallation de l'extension, y compris avec Remove data on uninstall.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Frenet est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox Frenet > 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 se trouvent la ligne Product: opencart-shipping-frenet 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é un emplacement 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, Frenet n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un utilisateur 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. Une fois la page Edit ouverte une fois, 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 concerné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 la licence.

Dépannage

Frenet n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Frenet est activé. Vérifiez la Geo zone, ou Ignore shipping zones et Countries, les limites de poids et Minimum order amount. Consultez les avertissements en haut de la page de l'extension. Causes typiques : le client n'a pas encore saisi un CEP complet de 8 chiffres et il n'existe pas de prix fixes, ou Frenet n'a renvoyé aucun service pour ce trajet et il n'existe pas de prix fixe. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les devis en temps réel n'apparaissent pas : activez Debug log, rechargez la page de paiement et consultez le champ Log sur la page de l'extension. Il indique la raison : pas de CEP d'origine, pas de taux de change BRL, un CEP client incomplet, une limite de poids ou de montant, ou les messages des services ignorés.

Le journal indique que le jeton d'API a été refusé (HTTP 401 ou 403) : copiez à nouveau le jeton depuis le panneau Frenet et collez-le dans API token.

Le journal indique que Frenet n'a renvoyé aucun service : activez au moins un transporteur dans le panneau Frenet.

Ma boutique vend en euros ou en dollars : Frenet répond en BRL. Saisissez le BRL exchange rate (la valeur de 1 BRL dans votre devise par défaut).

Une taxe est ajoutée au prix Frenet : les prix Frenet sont les prix finaux du transporteur. Réglez Tax class sur No tax.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela efface les devis Frenet en cache.

La page indique « Warning: You do not have permission to modify VibeFox Frenet! » : le groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez à ce groupe l'autorisation de modification pour extension/shipping/vfd_frenet (OpenCart 3) ou extension/vfd_frenet/shipping/vfd_frenet (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de demande de devis Frenet peut être remplacée par le réglage vfd_frn_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 Frenet. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Frenet, Sort order, Tax class et Geo zone. Les devis en cache sont toujours supprimés. L'événement OpenCart de l'extension est aussi supprimé (sur OpenCart 4, également les événements qui enregistrent les données Frenet des nouvelles commandes), de sorte que le bloc Frenet n'est plus affiché sur la page de commande. Les données Frenet enregistrées avec les commandes sont conservées et réaffichées après une réinstallation. Si Remove data on uninstall est activé, les réglages Frenet et le journal de débogage sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur méthode d'expédition 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 Frenet dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de poubelle) pour supprimer le paquet téléchargé.

Frenet est une marque déposée de son propriétaire respectif. Cette extension n'est pas affiliée à Frenet et n'est pas approuvée par Frenet.