VibeFox PostNord 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.

Clé API PostNord (pour le sélecteur de point de service) : créez un compte gratuit sur developer.postnord.com, ajoutez une application et copiez sa clé API. Sans clé, le mode de livraison fonctionne toujours, mais les clients ne peuvent pas choisir de point de service.

Contrat PostNord : pour expédier des colis, vous avez besoin de votre contrat client PostNord habituel, par exemple MyPack Collect ou MyPack Home.

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_postnord-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_postnord.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_postnord-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 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 PostNord 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. Activez Enable/Disable (livraison en point de service) et/ou Home delivery, collez la API key PostNord, choisissez le Agreement country, renseignez les Country prices ou un Fallback cost (voir Configuration), puis cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_postnord.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 PostNord, 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, les deux options sont désactivées tant que vous n'en activez pas une et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages PostNord 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 PostNord > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi les listes de points de service mises en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison : un nom vide, plus long que 64 caractères ou contenant < > ; = # { }, un ordre de tri qui n'est pas un nombre entier, un statut de taxe ou une zone géographique invalides, ou un Min weight (kg) supérieur à Max weight (kg). Un champ numérique dont la valeur n'est pas un nombre supérieur ou égal à 0 est enregistré vide, avec un message. Une cellule du tableau des tarifs qui n'est pas un nombre supérieur ou égal à 0 est enregistrée comme 0, avec un message.

Au-dessus des réglages, la page signale l'absence de clé API, l'absence de tout tarif et l'absence de l'unité de poids « kg » dans la boutique.

Général

Les deux options de livraison sont proposées dans la zone géographique définie dans Availability, ou pour les pays de Ignore shipping zones.

Enable/Disable : active ou désactive la livraison PostNord vers un point de service ou une consigne à colis. Le client choisit le point lors du paiement. Par défaut : désactivé.

Name : le nom de l'option point de service lors du paiement, par exemple « PostNord MyPack Collect ». Par défaut : PostNord. Obligatoire, jusqu'à 64 caractères, sans < > ; = # { }.

Home delivery : proposer aussi la livraison à domicile PostNord, une deuxième option sans point de service. Par défaut : désactivé.

Home delivery name : le nom de l'option de livraison à domicile lors du paiement, par exemple « PostNord MyPack Home ». Par défaut : PostNord Home delivery. Mêmes règles que pour Name.

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

Tax status : None (the prices are final) (par défaut), ou une classe de taxe : OpenCart ajoute alors la taxe de livraison de cette classe aux tarifs. Elle s'applique aux deux options.

API PostNord (sélecteur de point de service)

API key : la clé API de votre application sur developer.postnord.com. Elle n'est envoyée à PostNord que depuis votre serveur, jamais au navigateur, et n'est jamais écrite dans le journal. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved API key : cochez la case puis cliquez sur Save pour supprimer la clé enregistrée.

Test mode : utilise l'environnement de test PostNord (atapi2.postnord.com). À réserver aux clés émises pour l'environnement de test.

Agreement country : le pays de votre contrat client PostNord : Suède, Danemark, Norvège ou Finlande. Il détermine les points de service proposés. Same as the delivery country (par défaut) utilise le pays du client.

Tarifs

Le titre de la section affiche la devise par défaut de votre boutique. Les tarifs sont exprimés dans cette devise, hors taxes, et sont identiques pour les deux options. PostNord ne proposant pas d'API publique de tarifs, vous définissez vos propres tarifs, généralement ceux de votre contrat PostNord. L'ordre est le suivant : seuil de livraison gratuite, puis tableau par pays, puis coût de secours.

Calculation type : Per order (par défaut) facture le tarif une seule fois. Per item (price x number of items) le multiplie par le nombre d'articles du panier.

Country prices : un tarif par pays de destination et par poids du panier. Cliquez sur Add country pour ajouter une ligne, et sur le bouton × pour en supprimer une. Chaque ligne comporte une colonne 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. Une colonne de poids à 0 utilise la colonne Price, et un Price de 0 signifie livraison gratuite. Le pays * All other countries couvre tous les pays sans ligne propre. Décimales avec une virgule ou un point (9,99 ou 9.99). Une nouvelle ligne commence avec * All other countries et tous les tarifs à 0. Choisissez le pays et saisissez les tarifs avant d'enregistrer, ou supprimez la ligne. Une cellule vide est enregistrée comme 0.

Fallback cost : utilisé lorsque le tableau par pays n'a pas de ligne pour la destination ni de ligne *. Laissez-le vide pour masquer PostNord pour ces pays.

Free shipping from : le sous-total du panier (produits à expédier, après le coupon, hors taxes) à partir duquel PostNord est gratuit. Il est vérifié avant le tableau par pays, il s'applique donc aussi à un pays sans ligne de tarif. Laissez-le vide pour ne jamais proposer la livraison gratuite.

Disponibilité

Min weight (kg) : masque PostNord lorsque le panier pèse moins. Les poids des produits sont convertis à partir de leur classe de poids. Par défaut : 0, ce qui signifie aucune limite.

Max weight (kg) : masque PostNord lorsque le panier pèse davantage. Par défaut : 30. 0 signifie aucune limite. Vérifiez la limite de poids de votre service PostNord : les consignes acceptent moins que les points de service.

Minimum subtotal : affiche PostNord uniquement si le sous-total du panier (produits à expédier, après le coupon, hors taxes) atteint au moins ce montant. Laissez-le vide pour toujours l'afficher.

Geo zone : propose PostNord uniquement pour les adresses situées dans cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Elle n'est pas utilisée tant que Ignore shipping zones est activé.

Ignore shipping zones : lorsqu'il est activé, la zone géographique n'est pas vérifiée et PostNord est proposé pour les pays indiqués ci-dessous. Lorsqu'il est désactivé, PostNord n'est proposé que dans la zone géographique.

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

Avancé

Debug log : écrit les calculs de tarifs et les appels API dans storage/logs/vfd_ptnd_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées. La clé API n'est jamais journalisée. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, un nouveau journal est créé.

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 : lorsqu'il est activé, la désinstallation de l'extension supprime les réglages PostNord et le journal. Les listes de points de service mises en cache sont toujours supprimées. Les points de service enregistrés dans les commandes sont toujours conservés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé API n'est pas exportée.

Import : collez le 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. La clé API enregistrée est conservée.

Fonctionnement lors du paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le tarif de chaque option PostNord. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent ni poids ni sous-total. L'extension vérifie la zone géographique ou la liste de pays, le poids du panier et le sous-total minimum. Si la livraison gratuite s'applique, le tarif est de 0. Sinon, le tarif provient du tableau par pays, puis du coût de secours. S'il n'y a pas de tarif, l'option est masquée. Le tarif est calculé dans votre devise par défaut et affiché au client dans sa devise, avec la taxe du Tax status sélectionné. Le calcul du tarif ne contacte jamais PostNord.

Pour l'option point de service et une adresse de livraison en Suède, au Danemark, en Norvège ou en Finlande, votre serveur demande à l'API PostNord Business Location les 10 points de service les plus proches du code postal de livraison. Il envoie le pays et le code postal de livraison, ainsi que le pays du contrat. Le délai d'attente de l'API est de 10 secondes. Les listes sont mises en cache pendant 6 heures par code postal, et les réponses « aucun point » pendant 1 heure. Les erreurs de l'API sont mises en cache pendant 5 minutes, afin qu'une panne de PostNord ne ralentisse pas chaque mise à jour du paiement. Le cache est conservé dans la table de base de données propre à l'extension. L'étape de livraison n'attend jamais PostNord : si la liste n'est pas encore en cache, elle est chargée lorsque le client sélectionne l'option.

Pour les autres destinations, les options peuvent toujours être proposées avec vos tarifs, sans sélecteur. L'option de livraison à domicile n'affiche jamais de sélecteur.

L'extension ne demande pas de tarifs PostNord en temps réel et ne crée pas d'étiquettes d'expédition, ne réserve pas d'envois (EDI), ne fournit pas de numéros de suivi et n'envoie pas d'e-mails de suivi. Il n'existe pas de vue cartographique. Pour les envois, utilisez PostNord Portal, Skicka Direkt Business ou un outil d'étiquetage ; ces outils ont besoin de l'identifiant du point de service enregistré.

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

Points relais

Lorsque l'adresse de livraison se trouve en Suède, au Danemark, en Norvège ou en Finlande, une liste PostNord service point apparaît sous l'option point de service, avec les points les plus proches, regroupés par ville, chacun avec son adresse et sa distance. Avant la saisie d'un code postal, le client voit « Saisissez votre code postal pour choisir un point de service PostNord. » Le choix est enregistré immédiatement pour le paiement.

Lorsque la liste est chargée, un point est obligatoire. Sans point, Continue à l'étape du mode de livraison s'arrête avec le message « Veuillez sélectionner un point de service PostNord. » Le point choisi est vérifié sur le serveur par rapport à la liste PostNord de l'adresse de livraison. Un point choisi pour un autre code postal n'est pas utilisé.

Le sélecteur ne bloque jamais une vente. Si la liste ne peut pas être chargée (pas encore de clé API, API PostNord indisponible, aucun point près du code postal), le client voit une note et peut tout de même passer commande. PostNord livre alors au point de service le plus proche de l'adresse.

Pages de commande, e-mails et facture : le point est ajouté au mode de livraison de la commande, par exemple « PostNord : nom, adresse (ID 12345) » (le nom de l'option, puis le point). Si le texte dépasse 128 caractères, l'adresse est omise (OpenCart 4 n'a pas cette limite et conserve toujours l'adresse). Il s'affiche partout où OpenCart affiche le mode de livraison : l'historique des commandes du client, les e-mails de commande, la facture et Sales > Orders. Une commande sans point conserve le nom simple du mode de livraison.

Page de commande de l'administration : dans Sales > Orders, la page de commande affiche un panneau PostNord service point au-dessus de l'historique, avec le nom, l'adresse et le Service point ID. Si aucun point n'a été choisi, il indique « non sélectionné - PostNord livre au point de service le plus proche de l'adresse de livraison ».

Sur OpenCart 4, la liste des points de service apparaît dans la fenêtre Shipping method options, sous l'option point de service, et elle est rechargée à chaque ouverture de la fenêtre, car l'adresse peut changer sur le paiement en une seule page. Le bouton Continue de la fenêtre ne permet pas de continuer sans point de la liste, avec le même message. Si le client clique pendant que la liste est encore en cours de chargement, la fenêtre attend la liste sans message, puis clique elle-même à nouveau sur Continue. Une liste indisponible ne bloque pas non plus la commande. OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau : le point de service de la commande est mis à jour avec elle.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PostNord est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox PostNord > 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), 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 se trouvent la ligne Product: opencart-shipping-postnord 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é 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 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, les options de livraison PostNord ne sont pas affichées aux clients lors du paiement et aucun tarif de livraison n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours les options dans la boutique, marquées (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 les options sont masquées 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

PostNord n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable/Disable (ou Home delivery) est activé. Vérifiez la Geo zone, ou la liste Countries lorsque Ignore shipping zones est activé. Vérifiez qu'un tarif est défini pour le pays (ligne du pays, ligne * ou Fallback cost), les limites de poids et le Minimum subtotal. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Le sélecteur indique que les points de service ne peuvent pas être chargés : vérifiez la API key et le réglage Test mode. Une clé de production ne fonctionne pas avec l'environnement de test, et inversement. Activez le Debug log, rechargez la page de paiement et consultez le champ Log sur la page de l'extension. La commande peut tout de même être passée ; PostNord livre alors au point de service le plus proche.

Points de service inattendus : vérifiez le Agreement country. Il détermine les points de service proposés.

La livraison est gratuite par erreur : vérifiez les Country prices pour les lignes dont le Price est à 0, en particulier une ligne * ajoutée avec Add country et laissée incomplète, et vérifiez le Free shipping from.

Les points de service semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les listes mises en cache.

Les poids des produits semblent incorrects : si la page de l'extension signale que la boutique n'a pas d'unité de poids « kg », vérifiez System > Localisation > Weight Classes. Les poids des produits sont convertis selon le nom d'unité de leur classe, et les unités inconnues sont lues comme des kg.

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

Pour les développeurs : l'adresse de l'API PostNord peut être remplacée par le réglage vfd_ptnd_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 PostNord. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours le statut de l'extension, le Sort order, le Tax status et la Geo zone. Les listes de points de service mises en cache sont toujours supprimées. Si Remove data on uninstall est activé, les réglages PostNord, le journal de débogage et les points de service des paiements qui ne sont jamais devenus une commande sont également 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 mode de livraison, leur coût et le point de service enregistré.

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

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