VibeFox Packeta for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé en 3.0.5.0) ou 4.0.2 et ultérieur (testé en 4.1.0.3), avec le paiement par défaut du thème par défaut.

PHP : 8.0 ou ultérieur.

Clé API Packeta : vous la trouvez dans l'espace client de Packeta (client.packeta.com), sous Client support. Elle comporte 16 lettres et chiffres. Le widget en a besoin pour s'ouvrir au moment du paiement ; la méthode n'est donc affichée aux clients qu'après la saisie de la clé API.

Pays : la République tchèque, la Slovaquie, la Hongrie ou la Roumanie doivent être des pays activés dans votre boutique. Ils figurent dans les données standard d'OpenCart. La Hongrie n'a pas de régions dans OpenCart, donc le champ région de l'adresse reste vide ; cela n'a pas d'importance.

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_packeta-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_packeta.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_packeta-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 copier le contenu du dossier upload de ce package dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Packeta et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page de configuration.

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. Saisissez votre API key Packeta et vos prix : au moins une ligne Country prices (par exemple * Default) ou un Fallback cost. Activez Enable/Disable et cliquez sur Save. La page indique si Packeta a accepté la clé.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_packeta.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 Packeta, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence, la clé API et les prix 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/Disable et enregistré. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages Packeta conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Packeta > Edit. Les sections sont listées à gauche. Un seul bouton Save, en bas, enregistre toute la page sans la recharger. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

La méthode n'est proposée que pour les pays du propre réseau de points relais de Packeta : CZ, SK, HU et RO. Au-dessus des réglages, la page affiche le résultat de la vérification de la clé API et des avertissements sur les problèmes : absence de clé API, absence de prix, pays sélectionnés hors du réseau Packeta ou unité de poids de la boutique que l'extension ne reconnaît pas. Les avertissements sont mis à jour après chaque enregistrement.

Tous les prix et limites acceptent la virgule ou le point comme séparateur décimal (4,99 ou 4.99). Un nombre invalide ou négatif est refusé avec un message, et la valeur précédente de ce champ est conservée ; les autres champs sont enregistrés.

Général

Enable/Disable : active ou désactive Packeta au moment du paiement. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client. Par défaut : Packeta pickup point. Obligatoire, 64 caractères maximum.

API key : votre clé API Packeta, disponible dans client.packeta.com > Client support. Vous pouvez aussi coller le mot de passe API de 32 caractères : seuls ses 16 premiers caractères, qui constituent la clé API, sont enregistrés. La clé API est publique : elle est envoyée au navigateur du client pour ouvrir le widget. Lorsque vous enregistrez une nouvelle clé, elle est vérifiée auprès du flux transporteurs de Packeta, et la page affiche Packeta API key verified ou indique que Packeta l'a rejetée. Si la vérification ne peut pas être effectuée, la clé est enregistrée et vérifiée à nouveau lors de votre prochain enregistrement.

Widget language : la langue du widget des points relais. Store / visitor language (par défaut) suit la langue de la page. Vous pouvez aussi la fixer en tchèque, slovaque, hongrois, roumain, anglais, allemand, polonais ou ukrainien.

Pickup point types : les points Packeta proposés par le widget.

Tax status : la classe de taxe d'OpenCart appliquée au prix de la livraison, ou None (no tax on shipping) (par défaut).

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

Prix

Packeta ne propose pas d'API publique de tarifs. Les prix proviennent de ce tableau et sont saisis dans la devise par défaut de votre boutique, hors taxes. Les clients qui paient dans une autre devise voient le prix converti.

Calculation type : Per order (par défaut) facture le prix une seule fois. Per item (price x quantity) le multiplie par la quantité de produits nécessitant une livraison.

Country prices : un prix par pays de destination et par poids de colis. Cliquez sur Add country pour ajouter une ligne et sur le bouton × pour en supprimer une. 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 de poids laissée à 0 utilise la colonne Price. La ligne * Default sert aux pays qui n'ont pas leur propre ligne. Une nouvelle ligne démarre en * Default avec tous les prix à 0, ce qui signifie livraison gratuite. Choisissez le pays et saisissez les prix avant d'enregistrer, ou supprimez la ligne. Si le même pays (ou * Default) figure dans deux lignes, seule la première est conservée à l'enregistrement. Si une valeur du tableau n'est pas un nombre égal ou supérieur à 0, le tableau n'est pas enregistré et la page indique les valeurs erronées.

Fallback cost : utilisé lorsque le tableau des pays n'a ni ligne pour la destination ni ligne * Default. Laissez le champ vide pour ne pas proposer la méthode à cet endroit.

Free shipping from : le sous-total du panier (après le coupon, hors taxes) à partir duquel la livraison Packeta est gratuite. Ce seuil est vérifié avant le tableau des prix : à partir de ce montant, la livraison est gratuite dans chaque pays Packeta où la méthode est proposée, même dans un pays sans ligne ni coût de repli. Laissez le champ vide pour ne jamais proposer la livraison gratuite.

Disponibilité

Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. Les poids des produits sont convertis à partir de leurs classes de poids OpenCart. Vide ou 0 signifie aucune limite.

Maximum weight (kg) : masque la méthode lorsque le panier pèse davantage. Par défaut : 15. Les points relais et les Z-BOX Packeta acceptent en général des colis jusqu'à 15 kg ; vérifiez votre contrat Packeta. Vide ou 0 signifie aucune limite. Un poids minimum supérieur au poids maximum est refusé à l'enregistrement, et les deux valeurs précédentes sont conservées.

Minimum cart subtotal : ne proposer la méthode que lorsque le sous-total du panier (après le coupon, hors taxes) atteint ce montant.

Geo zone : ne proposer Packeta que pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : lorsqu'il est activé, la zone géographique n'est pas vérifiée et la méthode est proposée pour les pays sélectionnés ci-dessous. Lorsqu'il est désactivé (par défaut), elle n'est proposée que dans la zone géographique indiquée ci-dessus.

Countries (ignore zones mode) : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays Packeta. Les pays hors du réseau de points relais Packeta 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 points relais dans storage/logs/vfd_pckt_debug.log.php. Ce fichier ne peut pas être lu depuis le web. Aucune donnée personnelle de client ni aucune clé API n'est journalisée. Les erreurs et les vérifications de clé API échouées sont toujours journalisées. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_pckt_debug.old.log.php et un nouveau journal est créé.

Log (last lines) : 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 les réglages et le journal. Lorsqu'il est désactivé (par défaut), les réglages sont conservés pour une réinstallation. Le point relais enregistré dans les commandes est toujours conservé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON, y compris la clé API, qui est publique.

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

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix Packeta. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Packeta n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. L'extension vérifie les conditions : pays de livraison dans le réseau Packeta, clé API, liste des pays en mode d'exclusion des zones, poids du panier et sous-total minimum du panier. Le sous-total correspond au prix des produits nécessitant une livraison, après remise du coupon et hors taxes. Les cartes cadeaux, les points de fidélité et les avoirs ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0. Sinon, le prix provient du tableau des pays, puis du coût de repli. S'il n'y a pas de prix, la méthode est masquée. Le prix est affiché au client dans sa devise, avec la taxe de la Tax status sélectionnée.

Sous l'option Packeta de l'étape du mode de livraison se trouve un bouton Choose pickup point. Il ouvre le widget officiel de Packeta dans le navigateur du client, avec le pays de destination, le poids du panier, les types de points choisis et la langue du widget. Une fois le point choisi par le client, son nom et son adresse s'affichent sous la méthode, et le bouton devient Change pickup point. Le point est enregistré pour la session de paiement et conservé lors du rechargement de la page. Un point choisi pour un autre pays n'est pas utilisé lorsque l'adresse de livraison passe à un autre pays.

Votre serveur n'interroge rien auprès de Packeta au moment du paiement. Le script du widget est chargé depuis widget.packeta.com, uniquement sur la page de paiement. S'il est bloqué (par un bloqueur de publicités ou de confidentialité, une politique de sécurité du contenu ou une panne de Packeta), le client voit le message « The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method. »

Les prix Packeta ne sont pas demandés en temps réel ; ils proviennent de votre tableau. L'extension ne crée pas d'envois Packeta, n'imprime pas d'étiquettes et ne suit pas les colis ; elle ne propose pas la livraison à domicile ni les points de partenaires transporteurs par défaut. Transmettez l'identifiant du point relais de la commande à Packeta de la manière habituelle, par exemple par import dans client.packeta.com. Le bouton de point relais fonctionne avec le paiement standard d'OpenCart du thème par défaut.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Packeta dans la fenêtre Shipping method options. Le bouton Choose pickup point et le point choisi apparaissent dans cette fenêtre, sous l'option Packeta, et le widget Packeta s'ouvre par-dessus. Les tarifs sont les mêmes que sur OpenCart 3.

Points relais

Le point relais est obligatoire. Si le client clique sur Continue à l'étape du mode de livraison sans en choisir un, l'étape n'est pas validée et le client voit le message « Please choose a Packeta pickup point. ». Si le point choisi se trouve dans un autre pays que l'adresse de livraison, le client voit « The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again. ». L'extension ne vérifie pas l'identifiant du point auprès de Packeta ; elle contrôle seulement qu'un point a été choisi et que son pays correspond.

Le point est associé à la commande lors de sa création :

Mode de livraison de la commande : le nom et l'adresse du point sont ajoutés au nom de la méthode, par exemple Packeta pickup point: <point> (jusqu'à 128 caractères). Le client le voit dans l'historique de la commande et dans l'e-mail de commande, et il est imprimé sur la facture. La page de confirmation de commande d'OpenCart n'affiche pas le mode de livraison.

Page de commande de l'administration : ouvrez la commande dans Sales > Orders. Un encadré Packeta pickup point affiche le nom et l'adresse, le Pickup point ID et le pays. Si une commande Packeta n'a pas de point, l'encadré indique « No pickup point was selected for this order. »

Sur OpenCart 4, le bouton Continue de la fenêtre Shipping method options ne permet pas de continuer sans point, avec les mêmes messages. OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau : le point de la commande est mis à jour avec elle. L'encadré Packeta pickup point de la page de commande de l'administration s'affiche au-dessus de la section History.

Le point est stocké dans la table propre de l'extension, vfd_pckt_point (session de paiement, commande, identifiant du point, nom et adresse, pays).

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Packeta est le premier bloc de Extensions > Extensions > Shipping > VibeFox Packeta > Edit, au-dessus des réglages. Saisissez la clé dans License key puis cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-packeta et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les 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 figurant dans la configuration d'OpenCart. Supprimer la clé de la boutique ne libère pas sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, la méthode de livraison Packeta n'est pas affichée 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

Packeta n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la API key est saisie et que le pays de livraison est CZ, SK, HU ou RO. Vérifiez qu'un prix est défini pour le pays (ligne du pays, ligne * Default ou Fallback cost), les limites de poids et de sous-total, ainsi que Geo zone (ou Ignore shipping zones et ses pays). Vérifiez que les produits ont Requires Shipping réglé sur Yes. La page de configuration affiche en haut les problèmes de configuration. Activez Debug log pour voir la raison dans Log (last lines).

Packeta a rejeté la clé API : recopiez la clé API depuis client.packeta.com > Client support et enregistrez. Tant que ce n'est pas fait, le widget ne peut pas s'ouvrir au paiement.

Le widget ne s'ouvre pas : le script Packeta est bloqué par un bloqueur de publicités ou de confidentialité, une politique de sécurité du contenu ou une panne de Packeta. Autorisez widget.packeta.com dans votre politique de sécurité du contenu.

La livraison est gratuite par erreur : vérifiez dans Country prices les lignes avec un Price de 0, en particulier une ligne * Default ajoutée avec Add country et restée vide, et vérifiez Free shipping from.

Les limites de poids ou les colonnes de poids semblent erronées : si la page signale l'unité de poids de la boutique, utilisez des classes de poids avec l'unité kg, g, lb ou oz et définissez la classe de poids par défaut dans System > Settings, onglet Local. Les autres unités sont lues comme des kilogrammes.

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

Pour les développeurs : d'autres extensions peuvent ajouter des pays, transmettre des options comme les identifiants de transporteur au widget, modifier l'URL du script du widget ou sa langue grâce aux événements OpenCart vfd_packeta/countries, vfd_packeta/widget_options, vfd_packeta/widget_url et vfd_packeta/widget_language (déclencheurs avec le préfixe catalog/, par exemple catalog/vfd_packeta/widget_options).

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Packeta. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax status et Geo zone. La vérification enregistrée de la clé API est toujours supprimée, et le bouton de point relais ainsi que l'encadré de commande ne sont plus affichés. Si Remove data on uninstall est activé, les réglages, le journal et les points relais des paiements qui ne sont jamais devenus des commandes sont 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 toujours le point relais enregistré et le point 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 Packeta dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

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