VibeFox LP Express 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), avec le thème par défaut et le paiement standard d'OpenCart.

PHP : 8.0 ou ultérieur.

LP Express : aucun compte d'API n'est nécessaire. LP Express ne dispose d'aucune API publique de tarifs, et l'extension n'utilise pas l'API d'Unisend : vous saisissez donc vos propres tarifs (contractuels). Créez les colis dans votre compte Unisend (« Mano siuntos »).

Liste des terminaux de colis : l'extension utilise la liste ouverte des terminaux LP Express (https://www.lpexpress.lt/index.php?cl=terminals&fnc=getTerminals). Aucune clé n'est nécessaire. Si cette liste en ligne est indisponible, l'extension utilise la dernière copie téléchargée s'il en existe une, sinon votre propre liste. Préparez-vous à saisir votre propre liste (voir Configuration).

Lituanie : le pays doit être activé dans System > Localisation > Countries.

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_lp_express-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_lp_express.ocmod.zip. N'installez que le paquet de 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_lp_express-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 du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox LP Express 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 le champ License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Remplissez le tableau des tarifs (au moins une ligne ; la première nouvelle ligne est la Lituanie) ou un coût de secours. Consultez la ligne d'état concernant les terminaux de colis en haut de la page, et ajoutez votre propre liste de terminaux si la liste en ligne n'est pas disponible. 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_lp_express.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é.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox LP Express, 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.

À l'installation, l'extension crée deux petites tables (les terminaux choisis et la liste de terminaux en cache) et enregistre ses événements OpenCart pour la page de paiement et la page de commande. Le mode de livraison reste désactivé tant que vous n'activez pas Enable/Disable 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 LP Express > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre la page entière sans la recharger. Chaque enregistrement recharge également la liste des terminaux. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

En haut de la page, des avis signalent les problèmes et l'état des terminaux. Un avertissement apparaît lorsqu'aucun tarif n'est défini ou qu'aucun terminal de colis n'est disponible, car le mode de livraison n'est alors pas affiché au moment du paiement ; il apparaît aussi lorsque la boutique ne dispose pas d'une classe de poids avec l'unité kg, car les poids des produits sont alors lus d'après le nom de leur unité (kg, g, lb, oz) et toute autre unité est traitée comme des kg. Une ligne d'information indique combien de terminaux de colis, dans combien de villes, sont disponibles et depuis quelle source : la liste en ligne, une copie enregistrée de la liste en ligne (avec sa date) ou votre propre liste.

À l'enregistrement, un titre de méthode vide ou contenant l'un des caractères < > ; = # { } est refusé avec Enter a valid method title., et un titre de plus de 64 caractères est refusé également. Un ordre de tri qui n'est pas un nombre entier est refusé de la même façon. Dans ces cas, rien n'est enregistré. Un montant ou un poids qui n'est pas un nombre (ou qui est négatif) est signalé, et sa valeur précédente est conservée. Un Minimum weight (kg) supérieur à Maximum weight (kg) (30 kg lorsque le maximum est vide) est également signalé, car la méthode ne serait jamais affichée ; les deux poids conservent alors leurs valeurs précédentes. Les tarifs du tableau qui ne sont pas des nombres sont signalés et laissés vides. Les autres valeurs sont enregistrées.

Général

Enable/Disable : affiche ou masque LP Express au moment du paiement (l'état de cette extension). Par défaut : off.

Method title : le nom du mode de livraison affiché aux clients dans le panier et au moment du paiement. Par défaut : LP Express parcel terminal. Obligatoire, 64 caractères maximum.

Tax class : --- None --- (par défaut) signifie que les tarifs ci-dessous sont définitifs. Avec une classe de taxe, OpenCart ajoute la taxe de livraison aux tarifs ci-dessous.

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

Tarifs (dans la devise par défaut de votre boutique, indiquée dans le titre de la section ; les décimales peuvent être écrites sous la forme 2.99 ou 2,99)

Price table : une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en retirer une. Choisissez * Any other country pour chaque pays sans ligne propre. Chaque ligne comporte un Base price et des colonnes de poids : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 5 kg. Le poids est celui du panier, ou celui d'un article avec Per item. Une colonne vide utilise le prix de base de la ligne. 0 signifie gratuit. Une ligne sans aucun prix n'est pas enregistrée.

Fallback cost : utilisé lorsque le tableau des tarifs n'a pas de ligne (ou pas de prix) pour le pays de destination. Laissez le champ vide pour masquer le mode de livraison dans ces pays.

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

Per order (tier by total cart weight): un seul prix pour le panier, avec la colonne de poids choisie selon le poids total du panier. C'est la valeur par défaut.

Per item (each item priced by its own weight x quantity): chaque produit est tarifé selon son propre poids multiplié par sa quantité, puis les prix sont additionnés.

Free shipping from : le montant du panier (produits nécessitant une livraison, après remises, hors taxes) à partir duquel LP Express est gratuit. Ce seuil s'applique avant le tableau des tarifs, il couvre donc aussi les pays sans ligne propre. Laissez le champ vide s'il n'y a pas de livraison gratuite.

Disponibilité

Minimum weight (kg) : masque le mode de livraison lorsque le panier est plus léger. Vide ou 0 signifie aucune limite.

Maximum weight (kg) : masque le mode de livraison lorsque le panier est plus lourd. Les terminaux LP Express acceptent les colis jusqu'à 30 kg. Par défaut : 30. 0 signifie aucune limite. Vide signifie 30 kg, ou aucune limite lorsque Ignore shipping zones est activé.

Minimum cart total : affiche le mode de livraison seulement à partir de ce montant de panier (produits nécessitant une livraison, après remises, hors taxes). Laissez le champ vide pour l'afficher toujours.

Geo zone : le mode de livraison n'est proposé que pour les adresses situées dans cette zone géographique. All Zones (par défaut) signifie partout. 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é.

Ignore shipping zones : propose LP Express pour les pays indiqués ci-dessous, quelle que soit la zone géographique. Dans ce mode, la zone géographique n'est pas vérifiée. Lorsqu'il est désactivé, les pays sont définis par la zone géographique. Cette option est recommandée. Par défaut : off.

Countries (without zones) : les pays de destination pour ce mode. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé. Laissez-le vide pour proposer le mode de livraison pour tous les pays.

Terminaux de colis

Terminal list : d'où proviennent les terminaux.

LP Express online list : la liste en ligne est téléchargée une fois par jour. Lorsqu'elle ne peut pas être chargée, la dernière copie téléchargée est utilisée, puis votre propre liste ci-dessous. C'est la valeur par défaut.

Only my own list : seuls les terminaux que vous saisissez ci-dessous sont proposés.

Avancé

Debug log : écrit le détail du calcul des tarifs et de la liste des terminaux dans storage/logs/vfd_lpex_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_lpex_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs, comme une liste de terminaux indisponible ou une commande sans terminal, sont toujours journalisées. Aucune donnée client n'est journalisée. Lorsque le fichier atteint 5 Mo, un nouveau journal est créé.

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

Remove data on uninstall : lorsqu'il est activé, la désinstallation de l'extension supprime les réglages, la liste de terminaux enregistrée, le journal et les terminaux des paiements non finalisés. Lorsqu'il est désactivé (par défaut), les réglages sont conservés pour une réinstallation. Le terminal enregistré dans les commandes est toujours conservé.

Importer / Exporter

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 sont vérifiées comme lors d'un enregistrement normal.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif de LP Express. Si une Geo zone est définie et que l'adresse se trouve en dehors, LP Express n'est pas proposé. Avec Ignore shipping zones, la zone géographique n'est pas vérifiée : LP Express n'est proposé que pour les pays listés (tous les pays lorsque la liste 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 montant du panier. Le montant du panier correspond au prix de ces produits après la remise du coupon et avant la taxe. Les cartes cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte.

L'extension vérifie le poids du panier et le montant minimal du panier. Si la livraison gratuite s'applique, le prix est 0. Sinon, le prix vient de la ligne du pays (ou de la ligne *) : la colonne de poids, sinon le prix de base, sinon le coût de secours. S'il n'y a pas de prix, ou si aucun terminal de colis n'est disponible, le mode de livraison est masqué, de sorte que le client ne voit jamais un paiement qui ne peut pas aboutir.

Les prix et les montants sont exprimés dans la devise par défaut de votre boutique. Le prix est arrondi à ses décimales et présenté au client dans sa propre devise, avec la taxe de la Tax class sélectionnée.

La liste en ligne des terminaux est mise en cache pendant 24 heures. Un téléchargement échoué est mémorisé pendant 15 minutes, afin que le paiement n'attende pas la liste à chaque actualisation. Le délai d'expiration du téléchargement est de 10 secondes. Seuls les terminaux actifs de la liste sont proposés. Les terminaux sans ville figurent sous Other.

En OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit LP Express dans la fenêtre Shipping method options. Les tarifs sont les mêmes que sur OpenCart 3.

L'extension ne demande aucun tarif à LP Express ou Unisend, ne crée pas d'envois, n'imprime pas d'étiquettes, n'appelle pas de transporteur et ne suit pas les colis. Créez les colis dans votre compte Unisend (« Mano siuntos »). La livraison à domicile par coursier ne fait pas partie de cette méthode.

Points de retrait

Lorsque le client sélectionne LP Express à l'étape du mode de livraison, le bloc LP Express parcel terminal apparaît en dessous avec deux listes : -- Select city -- et -- Select parcel terminal --. La liste des terminaux n'est chargée que lorsque LP Express est sélectionné. La ville de l'adresse de livraison est présélectionnée lorsqu'elle correspond à une ville de la liste. Chaque terminal est affiché avec son nom, son adresse et son code postal. Le choix est immédiatement enregistré pour le paiement, de sorte qu'il n'est pas perdu lorsque la page de paiement se rafraîchit.

Un terminal est obligatoire. Lorsque le client clique sur Continue, le serveur vérifie de nouveau le terminal par rapport à la liste. Sans terminal, la page de paiement affiche Please select an LP Express parcel terminal. Un identifiant de terminal falsifié ou périmé est refusé avec The selected LP Express parcel terminal is not available any more. Please select a parcel terminal again. Si aucun terminal ne peut être chargé, le client voit The LP Express parcel terminal list is temporarily unavailable. Please try again later or choose another shipping method.

Sur OpenCart 4, le bloc LP Express parcel terminal avec les deux listes apparaît dans la fenêtre Shipping method options, sous l'option LP Express, lorsque le client la sélectionne. Le bouton Continue de la fenêtre ne permet pas d'aller plus loin sans terminal valide, avec les mêmes messages.

L'identifiant du terminal, son nom et sa ville sont enregistrés avec la commande. L'encadré LP Express parcel terminal de la page de commande de l'administration (Sales > Orders, informations de la commande) affiche la ville, le terminal et son Terminal ID. Le mode de livraison de la commande affiche le titre de la méthode, deux-points, la ville et le terminal (par exemple LP Express parcel terminal : Kaunas, …), de sorte qu'il apparaît dans le détail de la commande du client, dans les e-mails de commande et sur la facture. Si une commande n'a pas de terminal, la page de commande de l'administration affiche No parcel terminal was chosen for this order. L'encadré est aussi affiché pour les commandes passées pendant que l'extension est désactivée. Sur OpenCart 4, il est affiché 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 terminal de la commande est mis à jour avec elle. Si le client passe cette commande à un autre mode de livraison, son terminal est supprimé.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox LP Express est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox LP Express > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau l'état, 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-lp-express 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é 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 état 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 LP Express 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 de l'administrateur, donc sans clé active le mode est masqué 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 affectées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état 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 l'état de la licence.

Dépannage

LP Express n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Contrôlez la Geo zone (ou que Ignore shipping zones est activé et que le pays est autorisé). Ouvrez la page de l'extension : un avertissement indique si aucun tarif n'est défini ou si aucun terminal de colis n'est disponible. Vérifiez aussi les limites de poids et le Minimum cart total, ainsi que les produits dont Requires Shipping est réglé sur Yes. Avec Debug log activé, le champ Log de la page de l'extension indique pourquoi le mode de livraison a été masqué.

Aucun terminal de colis : la liste en ligne n'a pas pu être chargée et il n'existe ni copie enregistrée ni liste personnelle. L'extension réessaie toutes les 15 minutes. Saisissez votre propre liste dans Own terminal list, ou choisissez Only my own list.

La liste des terminaux est obsolète : cliquez sur Save sur la page de l'extension. Cela recharge la liste des terminaux. Avec votre propre liste, mettez vous-même les lignes à jour.

Le client ne peut pas continuer : un terminal de colis doit être choisi. Si le client voit le message indiquant que la liste des terminaux est temporairement indisponible, aucun terminal n'est disponible pour le moment. Ajoutez votre propre liste.

Le sélecteur de terminaux n'apparaît pas : le sélecteur est ajouté à l'étape du mode de livraison du paiement standard d'OpenCart (sur OpenCart 4, dans la fenêtre Shipping method options) et a été testé avec le thème par défaut. Un thème fortement modifié ou une extension de paiement tierce peut ne pas l'afficher.

Dans quelle devise sont les tarifs : dans la devise par défaut de votre boutique. Les clients qui paient dans une autre devise voient le prix converti au taux de change d'OpenCart.

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

Pour les développeurs : l'adresse de la liste des terminaux peut être remplacée par le réglage vfd_lpex_feed_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 LP Express. 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 class et Geo zone. Les événements de l'extension sont toujours supprimés, et la liste de terminaux en cache est effacée. Si Remove data on uninstall est activé, les réglages, le journal, la copie enregistrée de la liste des terminaux et les terminaux des paiements non finalisés sont également supprimés. S'il est désactivé, les autres réglages et la copie enregistrée sont conservés et réutilisés lorsque vous réinstallez l'extension. Le terminal enregistré dans les commandes n'est jamais supprimé, et les commandes existantes conservent le terminal dans leur mode de livraison.

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 LP Express dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet téléversé.

LP Express est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à LP Express ni approuvée par LP Express.