VibeFox GLS ParcelShop 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), avec le thème par défaut et son paiement en une seule page.

PHP : 8.0 ou ultérieur.

GLS : l'extension n'utilise ni ne nécessite de compte GLS ni de clé d'API. La carte des ParcelShop est publique. Vous avez besoin d'un contrat avec GLS pour expédier les colis vers les ParcelShop choisis.

Politique de sécurité du contenu : si votre boutique envoie une politique de sécurité du contenu, autorisez map.gls-croatia.com, depuis lequel le script de la carte GLS est chargé.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_gls_parcelshop-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_gls_parcelshop.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_gls_parcelshop-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 GLS ParcelShop 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 License key, dans le bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir License key).

5. Définissez vos tarifs : au moins une ligne de Country prices (par exemple * Default) ou un Fallback cost (voir Configuration). Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_gls_parcelshop.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é de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox GLS ParcelShop, 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, le mode de livraison reste désactivé jusqu'à ce que vous activiez Enable/Disable et enregistriez. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages 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 GLS ParcelShop > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. 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 de nouveau après chaque enregistrement, signalent les problèmes de configuration : aucun prix n'est défini, certains ou tous les Countries (ignore zones mode) sélectionnés ne sont pas couverts par la carte GLS, ou l'unité de poids de la boutique n'est pas reconnue par l'extension et aucune classe de poids en kg n'existe (ajoutez-en une dans System > Localisation > Weight Classes). Une valeur invalide ou négative est refusée avec un message qui nomme le champ, par exemple Fallback cost: "abc" is not a valid number of 0 or more - the previous value was kept. Les autres champs sont tout de même enregistrés. Un Name, un ordre de tri, une classe de taxe ou une zone géographique invalide est refusé de la même manière.

Général

La section liste les pays couverts par la carte GLS : Autriche, Belgique, Bulgarie, Croatie, République tchèque, Danemark, Finlande, France, Allemagne, Grèce, Hongrie, Italie, Luxembourg, Pays-Bas, Pologne, Portugal, Roumanie, Serbie, Slovaquie, Slovénie et Espagne. Le mode de livraison n'est pas proposé pour les autres pays de destination.

Enable/Disable : affiche ou masque GLS ParcelShop au moment du paiement. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client. Par défaut : GLS ParcelShop. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

Tax status : None (shipping is not taxed), ou la classe de taxe à appliquer lorsque la livraison est taxable.

Sort order : la position parmi les modes de livraison au moment du paiement. Un nombre entier.

Tarifs

Les tarifs se saisissent dans la devise par défaut de votre boutique, hors taxes. Les décimales peuvent utiliser une virgule ou un point (4,99 ou 4.99). Le prix est affiché au client dans sa devise.

Calculation type : la manière dont le prix est appliqué.

Country prices : un tableau avec une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne. Chaque ligne comporte un Country, un Price et cinq colonnes de poids : XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg et XL plus de 5 kg. La colonne correspondant au poids du panier est utilisée. Une colonne de poids laissée à 0 utilise la colonne Price. La ligne * Default sert pour les pays qui n'ont pas leur propre ligne. Une ligne dont tous les prix sont à 0 donne une livraison gratuite : choisissez donc le pays et renseignez les prix avant d'enregistrer. Si une valeur du tableau n'est pas un nombre valide de 0 ou plus, le tableau entier n'est pas enregistré et le message indique les valeurs incorrectes.

Fallback cost : le prix utilisé lorsque le tableau n'a pas de ligne pour le pays de destination ni de ligne * Default. Laissez ce champ vide pour masquer le mode de livraison pour ces pays.

Free shipping from : le sous-total du panier (après remises, hors taxes) à partir duquel la livraison GLS ParcelShop est gratuite. Laissez ce champ vide si la livraison n'est jamais gratuite.

Disponibilité

Minimum weight (kg) : masque le mode de livraison lorsque le panier pèse moins. Le poids est converti à partir des classes de poids des produits. Vide ou 0 signifie aucune limite.

Maximum weight (kg) : masque le mode de livraison lorsque le panier pèse plus. Par défaut : 20. Les ParcelShop GLS acceptent en général les colis jusqu'à 20 kg, vérifiez donc votre contrat GLS. Vide ou 0 signifie aucune limite. Si le minimum est supérieur au maximum, les deux poids sont refusés avec un message et les valeurs précédentes sont conservées.

Minimum cart subtotal : ne propose le mode de livraison que lorsque le sous-total du panier (après remises, hors taxes) atteint ce montant. Laissez ce champ vide pour aucun minimum.

Geo zone : ne propose le mode de livraison que pour les adresses de cette zone géographique. All zones signifie aucune limite. Non utilisé lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : lorsque l'option est activée, le mode de livraison est proposé pour les pays sélectionnés ci-dessous (tous les pays de la carte GLS si la liste est vide), quelle que soit la zone géographique. Lorsqu'elle est désactivée, il n'est proposé que dans la zone géographique indiquée ci-dessus. Par défaut : désactivé.

Countries (ignore zones mode) : les pays de destination pour ce mode. Laissez ce champ vide pour utiliser tous les pays de la carte GLS. Les pays non couverts par la carte GLS sont ignorés. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs et les choix de ParcelShop dans storage/logs/vfd_glps_debug.log.php (sous OpenCart 4, system/storage/logs/vfd_glps_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs sont toujours journalisées. Aucune donnée personnelle du client n'est journalisée. Désactivez le journal lorsque vous avez fini. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_glps_debug.old.log.php et un nouveau journal est démarré.

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 de l'extension supprime les réglages et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Le ParcelShop enregistré dans les commandes est toujours conservé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON.

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 invalides sont signalées et ne sont pas importées.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif GLS ParcelShop. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se situe en dehors, le mode de livraison n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le sous-total du panier. Le sous-total correspond au prix de ces produits après la remise du coupon, hors taxes. L'extension vérifie ensuite les conditions : pays de livraison couvert par la carte GLS (et sélectionné dans Countries (ignore zones mode) lorsque ce mode est activé), poids du panier et sous-total minimal du panier. Si le sous-total du panier atteint Free shipping from, la livraison est gratuite. Sinon, le prix est repris de la ligne du pays (ou de la ligne * Default) et de la colonne de poids, ou bien de Fallback cost. Si aucun prix n'est trouvé, le mode de livraison est masqué. Le prix est arrondi aux décimales de votre devise par défaut et affiché avec la taxe du Tax status sélectionné.

Lorsque le client sélectionne GLS ParcelShop, un encadré GLS ParcelShop avec un bouton Select GLS ParcelShop apparaît sous le mode de livraison. Il ouvre la carte officielle GLS ParcelShop pour le pays de livraison. Un ParcelShop situé dans un autre pays est refusé immédiatement. Une fois le ParcelShop choisi, son nom et son adresse s'affichent et le bouton devient Change ParcelShop. Le choix est conservé dans la session du client, il reste donc en place lorsque l'étape de livraison est rechargée. Si l'adresse de livraison passe dans un autre pays, le client doit choisir de nouveau un ParcelShop.

Lorsque le client clique sur Continue à l'étape du mode de livraison, l'extension vérifie qu'un ParcelShop a été choisi et qu'il se trouve dans le pays de livraison. Sinon, le client voit Please select a GLS ParcelShop. ou The selected GLS ParcelShop is not in your shipping country. Please choose a ParcelShop again. et reste à cette étape. Si le ParcelShop ne peut pas être enregistré, le client voit The ParcelShop could not be saved. Please try again. Si le script de la carte GLS ne peut pas être chargé, le client voit The GLS ParcelShop map could not be loaded. Please reload the page or choose another shipping method.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit GLS ParcelShop dans la fenêtre Shipping method options. L'encadré GLS ParcelShop avec le bouton Select GLS ParcelShop apparaît dans cette fenêtre sous le mode de livraison, et la carte GLS s'ouvre par-dessus la fenêtre. Le bouton Continue de la fenêtre ne permet pas de poursuivre sans ParcelShop valide, avec les mêmes messages. OpenCart 4 conserve une seule commande pour le paiement et la met à jour à chaque nouvelle confirmation du client ; le ParcelShop de la commande est mis à jour en même temps.

La carte GLS s'exécute dans le navigateur du client. Sur la page de paiement, l'extension charge le script de la carte GLS depuis map.gls-croatia.com, et la carte charge depuis GLS les données des ParcelShop et les tuiles de la carte. GLS reçoit les données habituelles de la requête du visiteur (adresse IP, navigateur). Rien n'est envoyé de votre serveur vers GLS. Une erreur de l'extension n'interrompt jamais le paiement pour les autres modes de livraison ; elle est écrite dans le journal.

L'extension ne récupère pas les tarifs GLS en temps réel, ne crée pas d'envois GLS, n'imprime pas d'étiquettes et ne suit pas les colis. Elle ne dispose d'aucune liste de ParcelShop sur votre serveur et ne peut donc pas vérifier l'ID du ParcelShop auprès de GLS. Transmettez l'ID du ParcelShop de la commande à GLS de la manière habituelle (MyGLS, votre logiciel GLS ou une autre extension).

Points de retrait

Lors de la passation de la commande, le ParcelShop choisi au moment du paiement est enregistré avec la commande : son ID, son nom avec l'adresse et son pays. Une fois la commande terminée, le choix est effacé, de sorte que le panier suivant commence sans ParcelShop.

Shipping method name : le ParcelShop est ajouté au nom du mode de livraison de la commande, par exemple GLS ParcelShop: name, address (le nom du mode de livraison, puis le ParcelShop) (OpenCart 3 conserve au maximum 128 caractères de ce nom, OpenCart 4 au maximum 255). Le ParcelShop apparaît ainsi dans l'e-mail de confirmation de commande envoyé au client, sur la page de commande dans l'Order History du client et dans Sales > Orders. OpenCart n'affiche pas le mode de livraison sur la page de succès de la commande.

Page de commande de l'administration : dans Sales > Orders, un panneau GLS ParcelShop affiche le nom et l'adresse du ParcelShop, avec l'ParcelShop ID et le pays. Si une commande GLS ParcelShop n'a pas de ParcelShop, le panneau affiche No ParcelShop was selected for this order. Le panneau se contente d'afficher le ParcelShop ; il ne peut pas être modifié à cet endroit.

E-mail au marchand : l'e-mail d'alerte de nouvelle commande envoyé à la boutique inclut le ParcelShop avec son ParcelShop ID dans le bloc de commentaires.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox GLS ParcelShop est le premier bloc de Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > 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-gls-parcelshop 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 pour 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 dans 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 GLS ParcelShop 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 le mode de livraison dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sous OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de livraison est masqué pour tout le monde. Une fois la page Edit ouverte une première 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 ou la page Edit de l'administration : 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 l'état de la licence.

Dépannage

GLS ParcelShop n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Contrôlez Geo zone, ou Ignore shipping zones et Countries (ignore zones mode). Vérifiez que le pays de destination fait partie des pays de la carte GLS et qu'il a un prix (une ligne de pays, la ligne * Default ou Fallback cost). Contrôlez les limites de poids et le Minimum cart subtotal, et vérifiez que les produits ont Requires Shipping réglé sur Yes. Activez Debug log et consultez le champ Log pour voir la raison.

La carte ne s'ouvre pas : le client voit « The GLS ParcelShop map could not be loaded... » lorsque le script GLS est bloqué, par exemple par un bloqueur de publicités ou de confidentialité, une politique de sécurité du contenu ou une panne de GLS. Autorisez map.gls-croatia.com dans votre politique de sécurité du contenu.

L'encadré du ParcelShop n'apparaît pas sous le mode de livraison : l'extension a été testée avec le thème par défaut d'OpenCart et son paiement. Un thème ou une extension de paiement qui remplace l'étape du mode de livraison peut ne pas afficher l'encadré.

La livraison est gratuite pour un pays par erreur : vérifiez la ligne de ce pays dans Country prices. Une ligne dont le Price et toutes les colonnes de poids sont à 0 donne une livraison gratuite.

Le tableau ou un champ n'a pas été enregistré : une valeur n'est pas un nombre valide de 0 ou plus. Le message en haut de la page indique la valeur concernée. Utilisez des chiffres avec une virgule ou un point comme séparateur décimal.

Une commande affiche No ParcelShop was selected for this order : la commande a été passée sans ParcelShop du pays de livraison. La raison est écrite dans le journal. Demandez le ParcelShop au client et transmettez-le manuellement à GLS.

La page indique « Warning: You do not have permission to modify VibeFox GLS ParcelShop! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_gls_parcelshop (OpenCart 3) ou extension/vfd_gls_parcelshop/shipping/vfd_gls_parcelshop (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse du script de la carte GLS peut être remplacée avec le réglage vfd_glps_widget_url ; il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox GLS ParcelShop. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax status et Geo zone. L'extension supprime toujours ses événements. 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 lors d'une nouvelle installation. Un ParcelShop choisi dans un panier ouvert reste dans la session du client jusqu'à expiration. Le ParcelShop enregistré dans les commandes est toujours conservé, et les commandes existantes gardent leur mode de livraison et leur coût.

Sous 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 GLS ParcelShop dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet chargé.

GLS est une marque déposée de son propriétaire. Cette extension n'est ni affiliée à GLS ni approuvée par GLS.