VibeFox PostNL for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x, thème Classic ou Hummingbird (ou un thème basé sur l'un d'eux).

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

Clé d'API PostNL (uniquement pour les points de retrait) : les points de retrait sont chargés depuis la PostNL Checkout API. Les clients professionnels de PostNL trouvent la clé d'API dans Mijn PostNL, sous My account > API beheren. Le sandbox PostNL nécessite une clé sandbox distincte. Le transporteur de livraison à domicile n'a pas besoin de clé.

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 PostNL dans la liste des modules et cliquez sur Configure.

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

4. Renseignez les tarifs. Pour les points de retrait, saisissez aussi la API key PostNL et le Ship from (postcode) (voir Configuration). Cliquez sur Save.

À l'installation, le module crée deux transporteurs : PostNL pickup point avec le texte de délai Delivery to a PostNL pickup point, et PostNL avec PostNL delivery to the home address. Les deux sont liés aux zones des Pays-Bas et de Belgique et à tous les groupes de clients. Vous pouvez ajouter des zones et modifier les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de tarifs à cet endroit : le tarif provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PostNL > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Dans WooCommerce, une méthode est ajoutée deux fois à une zone, une fois par type de livraison. Dans PrestaShop, chaque type de livraison est un transporteur à part entière, avec son propre nom, son statut et ses zones.

Au-dessus des réglages, la page affiche des avertissements : clé d'API ou code postal d'expédition manquant pour les points de retrait, sandbox activé, aucun tarif défini, la dernière requête PostNL échouée avec sa date et son erreur, une unité de poids de la boutique que le module ne reconnaît pas, et un transporteur supprimé.

Général

PostNL pickup point : active ou désactive le transporteur de point de retrait. Le client doit choisir un point PostNL lors du paiement. Il n'est proposé que pour les adresses des Pays-Bas et de Belgique, et uniquement avec une clé d'API. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Pickup point carrier name : le nom que voient les clients lors du paiement. Par défaut : PostNL pickup point. Obligatoire.

PostNL home address : active ou désactive le transporteur de livraison à domicile. Aucun point n'est choisi. Il fonctionne pour chaque pays avec un tarif. Même interrupteur que le statut du transporteur.

Home delivery carrier name : le nom que voient les clients lors du paiement. Par défaut : PostNL. Obligatoire.

Tax status : la règle de taxe des deux transporteurs. Une règle Taxable ajoute la taxe de livraison de cette règle aux tarifs. None signifie que les tarifs sont définitifs.

API PostNL (points de retrait) (inutile pour la livraison à domicile)

API key : votre clé d'API PostNL, disponible dans Mijn PostNL (My account > API beheren). Elle est envoyée à PostNL dans l'en-tête « apikey » et n'est jamais affichée aux clients ni é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 et cliquez sur Save pour supprimer la clé enregistrée. Le transporteur de point de retrait n'est alors plus proposé.

Sandbox : utilise le sandbox PostNL (api-sandbox.postnl.nl) avec une clé d'API sandbox. Les clients voient alors des points de retrait de test. Laissez-le désactivé sur une boutique en production.

Ship from (country) : le pays depuis lequel vous remettez vos colis à PostNL, Netherlands ou Belgium. Par défaut : Netherlands. PostNL utilise l'adresse de l'expéditeur pour la date d'enlèvement.

Ship from (postcode) : le code postal de l'expéditeur, par exemple 1234AB aux Pays-Bas ou 1000 en Belgique. Laissez vide pour utiliser le code postal de la boutique défini dans Shop Parameters > Contact > Stores lorsque la boutique est dans le même pays. Un code postal invalide est enregistré vide avec un avertissement. Lorsque vous modifiez la clé d'API, le réglage sandbox ou l'adresse d'expédition, les listes de points de retrait en cache et la dernière erreur d'API sont effacées.

Tarifs (dans la devise par défaut de la boutique, hors taxes)

Les tarifs s'appliquent aux deux transporteurs. PostNL ne propose pas d'API publique de tarifs : le module ne demande donc aucun tarif en temps réel. Pour un client qui paie dans une autre devise, PrestaShop convertit le tarif avec le taux de change de votre boutique.

Price per country : une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * All other countries pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne contient un Price et des classes de poids facultatives selon le poids du panier : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 5 kg. Un tarif de classe de poids remplace Price ; laissez-le vide pour utiliser Price. Un Price de 0 signifie livraison gratuite. « 6.95 », « 6,95 » et les montants avec séparateur de milliers comme « 1.234,50 » ou « 1,234.50 » sont acceptés. Les lignes vides et les codes pays non valides sont supprimés à l'enregistrement. Si un pays apparaît deux fois, la première ligne est conservée. Les tarifs invalides sont ignorés avec un avertissement.

Calculation : Per order facture le tarif une seule fois. Per item (price x quantity) le multiplie par le nombre d'articles à expédier.

Price for other countries : utilisé lorsque le tableau ne contient ni le pays ni une ligne *. Laissez-le vide pour masquer les transporteurs dans ces pays.

Conditions

Free shipping from : le sous-total du panier (produits à expédier, hors taxes, après remises) à partir duquel la livraison est gratuite. Ne s'applique que là où un tarif est trouvé. Laissez vide pour ne jamais proposer la livraison gratuite.

Minimum subtotal : n'affiche les transporteurs que si le sous-total du panier atteint au moins ce montant. Laissez vide pour toujours les afficher.

Minimum weight (kg) : masque les transporteurs lorsque le panier pèse moins. Les poids des produits sont convertis à partir de l'unité de poids de votre boutique. Laissez vide pour aucune limite.

Maximum weight (kg) : masque les transporteurs pour les paniers plus lourds. Par défaut : 30 (les colis PostNL vont jusqu'à 30 kg au Benelux). 0 signifie aucune limite. Si vous laissez le champ vide, 30 kg s'appliquent dans les zones des transporteurs, et aucune limite ne s'applique seulement aux pays atteints via Ignore zones. Un poids minimum supérieur au poids maximum est refusé avec une erreur, car les transporteurs ne seraient jamais affichés.

Tous les montants et poids acceptent la virgule décimale, y compris avec un séparateur de milliers. Un nombre invalide ou négatif est ignoré avec un avertissement, et le champ est enregistré vide.

Disponibilité sans zones de livraison

Normalement, les transporteurs sont proposés dans les zones de livraison auxquelles ils sont liés dans Shipping > Carriers.

Ignore zones : proposez aussi PostNL dans les pays ci-dessous, que ses zones ne contiennent pas. Les transporteurs sont alors liés à toutes les zones actives, y compris celles que vous créerez plus tard. Lorsque vous désactivez à nouveau l'option, les transporteurs retrouvent les zones qu'ils avaient auparavant.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore zones est activé. Dans ces pays, les deux transporteurs peuvent être proposés ; le transporteur de point de retrait, lui, ne l'est que pour les Pays-Bas et la Belgique.

Avancé

Debug log : écrit des messages de débogage dans logs/vfd_ptnl_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours journalisées. Aucune clé d'API ni donnée client n'est écrite. Désactivez le journal une fois terminé.

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

Remove data on uninstall : si activé, la désinstallation du module supprime les réglages et les transporteurs PostNL. Si désactivé, la désinstallation se contente de désactiver les transporteurs. Les points de retrait enregistrés sur les commandes sont toujours conservés.

Fonctionnement lors du paiement

À l'étape de livraison, PrestaShop demande au module le tarif de chaque transporteur PostNL. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Le module vérifie les conditions : poids du panier et sous-total minimum. Il prend ensuite le tarif dans le tableau pour le pays et la classe de poids, ou le tarif pour les autres pays. S'il n'y a pas de tarif, le transporteur est masqué. Si le sous-total du panier atteint Free shipping from, le tarif est de 0.

Le transporteur de point de retrait n'est proposé que pour les adresses des Pays-Bas et de Belgique, et uniquement avec une clé d'API. Lorsque l'adresse de livraison a un code postal valide, le module interroge la PostNL Checkout API pour obtenir les trois points de retrait les plus proches. Il envoie le code postal, la rue, le numéro, la ville et le pays du client, ainsi que votre adresse d'expédition. Rien n'est envoyé pour le transporteur de livraison à domicile. Si PostNL est injoignable ou n'a aucun point pour l'adresse, le transporteur de point de retrait est masqué et celui de livraison à domicile reste disponible. Le délai d'attente de l'API est de 12 secondes.

Les listes de points sont mises en cache pendant 6 heures par code postal, et les réponses « aucun point » pendant 1 heure. Les requêtes échouées sont mises en cache pendant 10 minutes, afin qu'une panne ne ralentisse pas chaque actualisation du paiement. La dernière erreur s'affiche sur la page du module.

Si vous modifiez un transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne demande aucun tarif PostNL en temps réel et ne crée ni étiquettes d'expédition, ni codes-barres, ni track and trace, ni retours, ni préalertes. Il ne propose pas d'options de livraison le soir ou le matin, ni de jour de livraison précis. Créez l'envoi dans Mijn PostNL ou dans un autre outil PostNL à l'aide du point de retrait enregistré.

Points de retrait

Lorsque le client sélectionne le transporteur de point de retrait, une liste PostNL pickup point apparaît en dessous avec les trois points les plus proches : nom de l'entreprise, adresse et distance. La page n'attend jamais PostNL : si la liste n'est pas encore en cache, elle est chargée dès que le transporteur est sélectionné. Avant la saisie d'un code postal complet, le client voit « Saisissez votre code postal (par exemple 1234 AB) pour voir les points de retrait PostNL. » (4 chiffres pour la Belgique). Le point choisi est enregistré dans le panier et conservé lorsque le paiement est actualisé.

Le point est obligatoire. Sans point, le client ne peut pas continuer et voit « Veuillez choisir un point de retrait PostNL. » Lorsque le client clique sur Continue, le serveur vérifie le point par rapport à la liste de PostNL pour l'adresse de livraison. S'il n'y figure pas, le client voit « Le point de retrait PostNL choisi n'est pas disponible pour cette adresse. Veuillez le choisir à nouveau. » Si PostNL est injoignable, le client voit « Les points de retrait PostNL ne peuvent pas être chargés pour le moment. Veuillez réessayer dans quelques minutes ou choisir un autre mode de livraison. » Un point choisi pour une autre adresse n'est jamais utilisé pour la commande. Le nom et l'adresse enregistrés avec la commande proviennent de PostNL, et non du navigateur.

Page de commande de l'administration : un bloc PostNL pickup point avec le nom et l'adresse, le Location code et le Partner ID.

Page de confirmation et pages de détail de commande : PostNL pickup point avec le nom et l'adresse.

E-mails de commande : le nom et l'adresse du point sont ajoutés au nom du transporteur dans l'e-mail de confirmation de commande. L'e-mail de nouvelle commande de la boutique (module Mail alerts) affiche aussi le code de localisation.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PostNL est le premier bloc de Modules > Module Manager > VibeFox PostNL > 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) 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 figurent la ligne Product: presta-shipping-postnl et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation 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-le dans votre compte vibefox.net.

Sans clé active, les transporteurs PostNL 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 vous ne pouvez pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sous 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 l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail dans le back-office : 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 du module supprime toujours la clé de licence et le statut de la licence. La réinitialisation de ce module ne supprime aucune donnée : la clé et le statut sont donc conservés.

Dépannage

PostNL n'apparaît pas au paiement : vérifiez que la licence est active et que l'interrupteur du transporteur est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore zones est activé et que le pays est autorisé). Vérifiez qu'un tarif est défini pour le pays, les limites de poids et Minimum subtotal. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le transporteur de point de retrait n'apparaît pas : il n'est affiché que pour les adresses néerlandaises et belges, uniquement avec une clé d'API, un code postal d'expédition et un tarif, et uniquement lorsque PostNL renvoie des points pour le code postal du client. Vérifiez les avertissements en haut de la page du module et le champ Log. Les erreurs sont toujours journalisées ; activez Debug log pour les détails.

"PostNL pickup points cannot be loaded right now" : PostNL est injoignable, a rejeté la clé d'API ou le code postal d'expédition est manquant. La page du module affiche la dernière erreur. Une clé sandbox ne fonctionne qu'avec Sandbox activé, et une clé de production uniquement avec celui-ci désactivé.

Les clients voient des points de retrait de test : désactivez Sandbox.

Les poids des produits semblent incorrects : si la page du module avertit que l'unité de poids de la boutique n'est pas reconnue, définissez une unité standard (kg, g, lb ou oz) dans International > Localization sous Local units. Jusque-là, les poids des produits sont lus en kg.

La page indique qu'un transporteur PostNL est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. La réinitialisation conserve vos réglages et le statut des transporteurs.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PostNL et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les listes de points de retrait en cache et la dernière erreur d'API sont toujours supprimées. Si Remove data on uninstall est activé, les transporteurs sont supprimés (les commandes conservent leur historique), ainsi que les réglages et le journal. 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 le statut qu'ils avaient. Les commandes existantes conservent leurs lignes de livraison et le point de retrait enregistré.

PostNL est une marque commerciale de son propriétaire respectif. Ce module n'est pas affilié à PostNL et n'est pas approuvé par PostNL.