VibeFox PostNord for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

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é, les transporteurs fonctionnent toujours, mais les clients ne peuvent pas choisir de point de service.

Contrat PostNord : pour expédier des colis, il vous faut 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

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléchargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox PostNord dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Collez la API key PostNord, choisissez votre Agreement country, renseignez les Country prices (voir Configuration) et cliquez sur Save.

À l'installation, le module crée deux transporteurs. PostNord livre dans un point de service, avec le texte de délai de livraison Delivery to a PostNord service point. Il est activé. PostNord Home delivery livre à l'adresse, avec le texte PostNord home delivery. Il est désactivé tant que vous n'activez pas Home delivery. Les deux transporteurs sont affectés aux zones de la Suède, du Danemark, de la Norvège et de la Finlande, ainsi qu'à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le texte du délai de livraison, le logo et les limites de taille dans Shipping > Carriers. N'y définissez pas de tarifs : le tarif provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PostNord > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi les listes de points de service en cache.

Au-dessus des réglages, la page signale l'absence de clé API, l'absence de tarif, la suppression d'un transporteur PostNord ou une unité de poids de la boutique inconnue du module. Dans ce cas, les poids des produits sont pris en kg. Utilisez kg, g, lb ou oz dans International > Localization (Local units).

Général

Enable/Disable : active ou désactive le transporteur à point de service. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name : le nom du transporteur à point de service au moment du paiement, par exemple « PostNord MyPack Collect ». Par défaut : PostNord. Obligatoire.

Home delivery : propose aussi la livraison à domicile PostNord. C'est le second transporteur, sans point de service. Désactivé par défaut.

Home delivery name : le nom du transporteur de livraison à domicile au moment du paiement, par exemple « PostNord MyPack Home ». Par défaut : PostNord Home delivery. Obligatoire.

Tax status : None signifie que les tarifs ci-dessous sont définitifs. Taxable: suivi d'une règle de taxe signifie que PrestaShop ajoute la taxe de livraison de cette règle aux tarifs. Cela s'applique aux deux transporteurs.

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. Ne saisissez une nouvelle valeur que 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). Uniquement pour les clés délivrées 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 transporteurs. PostNord ne propose pas d'API publique de tarifs : vous définissez donc 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 tarif de secours.

Calculation type : Per order 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 l'icône de corbeille pour en supprimer une. Chaque ligne comporte un 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 démarre 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 à 0. Une cellule qui n'est pas un nombre est enregistrée à 0, avec un message.

Fallback cost : utilisé lorsque le tableau par pays n'a ni ligne pour la destination ni ligne *. Laissez le champ vide pour masquer les transporteurs pour ces pays.

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

Disponibilité

Min weight (kg) : masque les transporteurs lorsque le panier pèse moins. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie aucune limite.

Max weight (kg) : masque les transporteurs lorsque le panier pèse plus. 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. Un Min weight (kg) supérieur à Max weight (kg) est refusé avec une erreur, et rien n'est enregistré.

Minimum subtotal : n'affiche les transporteurs que si le sous-total du panier (produits soumis à livraison, après remises, hors taxes) atteint au moins ce montant. Laissez le champ vide pour les afficher toujours.

Ignore shipping zones : lorsque l'option est activée, PostNord est proposé pour les pays ci-dessous, même si les zones de ses transporteurs ne les incluent pas. Les transporteurs sont liés à toutes les zones actives, et une zone créée plus tard est liée immédiatement. Quand vous la désactivez à nouveau, les transporteurs retrouvent les zones qu'ils avaient auparavant. Lorsqu'elle est désactivée, les transporteurs ne sont proposés que dans leurs propres zones.

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

Les montants et les poids acceptent la virgule ou le point. Une valeur qui n'est pas un nombre égal ou supérieur à 0 n'est pas enregistrée, et un message s'affiche.

Avancé

Debug log : écrit les calculs de tarifs et les appels à l'API dans logs/vfd_ptnd_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours consignées. La clé API n'est jamais consignée. Désactivez le journal lorsque vous avez terminé.

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 du module supprime les réglages PostNord et les transporteurs. Lorsqu'elle est désactivée, la désinstallation se contente de désactiver les transporteurs. Les points de service enregistrés dans les commandes sont toujours conservés.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le tarif de chaque transporteur PostNord. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module contrôle le poids du panier et le sous-total minimal. Si la livraison gratuite s'applique, le tarif est de 0. Sinon, le tarif provient du tableau par pays, puis du tarif de secours. S'il n'y a pas de tarif, le transporteur est masqué. Le tarif est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.

Pour le transporteur à point de service et une adresse de livraison en Suède, au Danemark, en Norvège ou en Finlande, votre serveur demande à l'API Business Location de PostNord 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 de l'étape de livraison. L'étape de livraison n'attend jamais PostNord : si la liste n'est pas encore en cache, elle est chargée après que le client a sélectionné le transporteur.

Pour les autres destinations, les transporteurs peuvent quand même être proposés avec vos tarifs, sans sélecteur. Le transporteur de livraison à domicile n'affiche jamais de sélecteur.

Si vous modifiez un transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne demande pas de tarifs PostNord en direct 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'y a pas de vue carte. Pour les expéditions, utilisez PostNord Portal, Skicka Direkt Business ou un outil d'étiquetage : ces outils ont besoin de l'identifiant du point de service enregistré.

Points de retrait

Lorsque le client sélectionne le transporteur à point de service, une liste PostNord service point apparaît en dessous, avec les points les plus proches, regroupés par ville avec la distance. Avant la saisie d'un code postal, le client voit le message « Saisissez votre code postal pour choisir un point de service PostNord. » Le choix est enregistré avec le panier et reste en place lors des mises à jour de l'étape de livraison.

Lorsque la liste est chargée, un point doit être choisi. Sans choix, Continue s'arrête avec le message « Veuillez sélectionner un point de service PostNord. » Le point choisi est vérifié côté serveur par rapport à la liste PostNord pour 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 quand même passer commande. PostNord livre alors au point de service le plus proche de l'adresse.

Page de commande du back-office : un bloc PostNord service point 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 ».

Confirmation de commande et détails de commande du client : PostNord service point : avec le nom et l'adresse.

E-mails de commande : la confirmation de commande envoyée au client et l'alerte de nouvelle commande adressée à la boutique affichent le nom, l'adresse et l'identifiant du point à côté du nom du transporteur. L'alerte de la boutique affiche aussi « not selected » lorsqu'il n'y a pas de point.

Clé de licence

Le module 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 Modules > Module Manager > VibeFox PostNord > Configure, 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: presta-shipping-postnord et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (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, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. 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 transporteurs PostNord ne sont pas affichés aux clients lors du paiement, et aucun tarif de livraison n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : les transporteurs sont donc masqués pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement pendant que vous travaillez dans le back-office : une fois par jour pendant les 14 premiers jours suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation du module supprime toujours la clé de licence et le statut de la licence. Le Reset de ce module ne supprime pas les données : la clé et le statut sont donc conservés.

Dépannage

PostNord n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable (ou Home delivery) est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones. 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. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

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 le paiement et consultez le champ Log sur la page du module. 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 Agreement country. Il détermine les points de service proposés.

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

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

La page indique qu'un transporteur PostNord est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PostNord et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. La désactivation du module vide seulement les listes de points de service en cache. À la désinstallation, les listes en cache sont toujours supprimées. Si Remove data on uninstall est activé, les transporteurs sont supprimés (les commandes conservent leur historique), et les réglages ainsi que le journal sont supprimés. S'il est désactivé, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module rend aux transporteurs enregistrés le statut qu'ils avaient. Les points de service enregistrés dans les commandes sont toujours conservés.

PostNord est une marque déposée de son propriétaire respectif. Ce module n'est pas affilié à PostNord et n'est pas approuvé par PostNord.