VibeFox PostNL for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
Clé d'API PostNL (uniquement pour les points de retrait) : les points de retrait sont chargés depuis l'API Checkout de PostNL. 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. Les méthodes de livraison à domicile n'ont pas besoin de clé.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.
Installation
1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_postnl dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox PostNL, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Renseignez les tarifs. Pour les points de retrait, saisissez aussi l'API key PostNL et le Ship from (postcode) (voir Configuration).
6. Ajoutez VibeFox PostNL à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, par exemple Pays-Bas et Belgique. Dans la zone, définissez le Title et le Delivery to. Ajoutez la méthode une deuxième fois pour l'autre type de livraison.
Configuration
Tous les réglages, sauf le titre et le type de livraison, se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox PostNL. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone comporte deux champs :
Title (zone) : le nom que voit le client pour cette méthode de zone. Laissez vide pour utiliser le Name global.
Delivery to (zone) : As in the global settings (par défaut), PostNL pickup point (customer chooses a point) ou Home address. Ajoutez la méthode deux fois à une zone pour proposer les deux.
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, et la dernière requête PostNL en échec avec sa date et son erreur.
Général
Enable/Disable : active ou désactive la livraison PostNL dans toutes les zones à la fois.
Name : le nom de la méthode de livraison affiché au paiement. Un Title défini dans la zone le remplace. Par défaut : PostNL.
Delivery to : le type de livraison par défaut pour les méthodes de zone qui utilisent As in the global settings, et pour le mode Ignore zones.
Tax status : Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas.
API PostNL (points de retrait) (non nécessaire pour la livraison à domicile)
API key : votre clé d'API PostNL, à récupérer dans Mijn PostNL (My account > API beheren). Elle est envoyée à PostNL dans l'en-tête « apikey », stockée dans la base de données WordPress et jamais affichée aux clients ni écrite dans le journal.
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. Gardez-le désactivé sur une boutique en production.
Ship from (country) : le pays depuis lequel vous remettez vos colis à PostNL, Pays-Bas ou Belgique. Par défaut, c'est le pays de votre boutique. 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 WooCommerce > Settings > General lorsque la boutique est dans le même pays. Un code postal non valide est refusé avec un message. 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 sont vidées.
Tarifs (dans la devise de la boutique)
PostNL ne propose pas d'API publique de tarifs : l'extension ne demande donc aucun tarif en temps réel et ne convertit jamais les montants.
Price per country : une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * All other countries pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne a un Price et, en option, des classes de poids 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 » et « 6,95 » sont tous deux 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 non valides sont ignorés avec un message.
Calculation : Per order facture le tarif une seule fois. Per item (price x quantity) le multiplie par le nombre d'articles expédiables du panier.
Price for other countries : utilisé lorsque le tableau ne contient ni le pays ni une ligne *. Laissez vide pour masquer la méthode dans ce cas.
Conditions
Free shipping from : le sous-total du panier à 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 : affiche la méthode seulement lorsque le sous-total du panier atteint au moins ce montant. Laissez vide pour toujours l'afficher.
Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. Les poids des produits sont convertis depuis l'unité de votre boutique. Laissez vide pour aucune limite.
Maximum weight (kg) : masque la méthode pour les paniers plus lourds. Par défaut : 30 (les colis PostNL vont jusqu'à 30 kg au Benelux). Laissez vide pour aucune limite.
Hide for shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes de livraison WooCommerce.
Tous les montants et poids acceptent la virgule décimale, y compris avec un séparateur de milliers (1.234,50 ou 1,234.50). Un nombre non valide est ignoré avec un message.
Disponibilité sans zones de livraison
Ignore zones : propose aussi PostNL aux pays indiqués ci-dessous lorsqu'aucune zone ne l'ajoute. Les zones qui contiennent la méthode continuent de fonctionner normalement. Ce mode utilise le Name et le Delivery to globaux.
Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels la boutique livre. Ce champ n'est utilisé que lorsque Ignore zones est activé.
Avancé
Debug log : écrit des messages de débogage dans WooCommerce > Status > Logs (source « vfd-postnl »). Les erreurs de l'API sont toujours journalisées. Aucune clé d'API ni donnée client n'est écrite. Désactivez le journal une fois que vous avez terminé.
Remove data on uninstall : si activé, la suppression de l'extension efface les réglages PostNL et les méthodes de zone. La désactivation de l'extension ne supprime jamais les réglages. Les points de retrait enregistrés dans les commandes sont toujours conservés.
Fonctionnement au paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie les conditions : poids du panier, sous-total minimum et classes de livraison. Elle prend ensuite le tarif du tableau pour le pays et la classe de poids, ou le tarif pour les autres pays. S'il n'y a pas de tarif, la méthode est masquée. Si le sous-total du panier atteint Free shipping from, le tarif est de 0.
Une méthode avec point de retrait n'est proposée que pour les adresses des Pays-Bas et de Belgique, et seulement avec une clé d'API. Dès que le client a saisi un code postal valide, l'extension demande à l'API Checkout de PostNL les points de retrait les plus proches. Elle 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 les méthodes de livraison à domicile. Si PostNL est injoignable ou ne renvoie aucun point pour l'adresse, la méthode avec point de retrait est masquée et vos autres méthodes restent disponibles. 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 en échec sont mises en cache pendant 10 minutes, afin qu'une panne ne ralentisse pas chaque mise à jour du paiement. La dernière erreur s'affiche sur l'écran des réglages.
La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension 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. Elle ne propose aucune option de livraison le soir ou le matin, ni de jour de livraison. Créez l'envoi dans Mijn PostNL ou dans un autre outil PostNL en utilisant le point de retrait enregistré.
Points de retrait
Lorsque le client sélectionne une méthode avec 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. Avant la saisie d'un code postal, le client voit le message « Saisissez votre code postal (par exemple 1234 AB) pour afficher les points de retrait PostNL. » (4 chiffres pour la Belgique). Le choix est conservé lorsque le paiement se met à jour.
Le point est obligatoire. Sans point, le paiement s'arrête avec le message « Veuillez choisir un point de retrait PostNL. » Le serveur vérifie le point par rapport à la liste de PostNL pour l'adresse de livraison. S'il ne figure pas dans la liste, le paiement s'arrête avec le message « Le point de retrait PostNL choisi n'est pas disponible pour cette adresse. Veuillez le choisir à nouveau. » Le nom et l'adresse enregistrés avec la commande proviennent de PostNL, et non du navigateur.
Écran de commande de l'administration : PostNL pickup point avec le nom, l'adresse et le Location code, sous l'adresse de livraison.
Page de confirmation et affichage de la commande dans Mon compte : PostNL pickup point avec le nom et l'adresse.
E-mails de commande : le nom et l'adresse du point dans les e-mails HTML et texte brut.
Dans la base de données, le point est enregistré dans les métadonnées de commande _vfd_ptnl_servicepoint_id (code de localisation PostNL), _vfd_ptnl_servicepoint_name (nom et adresse) et _vfd_ptnl_servicepoint (identifiant partenaire, entreprise, rue, numéro, code postal, ville, pays).
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox PostNL. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.
Sans clé active, PostNL n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.
Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
PostNL n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays 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, Minimum subtotal et Hide for shipping classes.
La méthode avec point de retrait n'apparaît pas : elle n'est affichée que pour les adresses néerlandaises et belges, seulement avec une clé d'API, un code postal d'expédition et un tarif, et seulement lorsque PostNL renvoie des points pour le code postal du client. Vérifiez les avertissements en haut de l'écran des réglages ainsi que WooCommerce > Status > Logs, source « vfd-postnl ». Les erreurs sont toujours journalisées ; activez Debug log pour plus de détails.
« Les points de retrait PostNL ne peuvent pas être chargés pour le moment » : PostNL n'a pas pu être joint, a rejeté la clé d'API, ou le code postal d'expédition est manquant. L'écran des réglages affiche la dernière erreur. Une clé sandbox ne fonctionne qu'avec Sandbox activé, et une clé de production uniquement lorsqu'il est désactivé.
Les clients voient des points de retrait de test : désactivez Sandbox.
Filtres pour les développeurs : vfd_ptnl_number_of_locations (par défaut 3), vfd_ptnl_checkout_request (corps de la requête) et vfd_ptnl_api_url.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation de l'extension conserve tous les réglages et supprime seulement les listes de points de retrait en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés, ainsi que les listes de points en cache et la dernière erreur de l'API. Les réglages et les méthodes de zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes de livraison et le point de retrait enregistré.
PostNL est une marque de son titulaire respectif. Cette extension n'est ni affiliée à PostNL, ni approuvée par PostNL.