VibeFox PostNL 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).

PHP : 8.0 ou ultérieur.

Clé API PostNL (pour les points relais uniquement) : les points relais sont chargés depuis l'API Checkout de PostNL. Les clients professionnels de PostNL trouvent la clé API dans Mijn PostNL, sous My account > API beheren. Le bac à sable de PostNL nécessite une clé de bac à sable distincte. L'option 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

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_postnl-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_postnl.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_postnl-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 PostNL 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 Clé de licence).

5. Activez PostNL pickup point et/ou PostNL home address et renseignez les prix. Pour les points relais, saisissez aussi la API key PostNL et le Ship from (postcode) (voir Configuration). Cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_postnl.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 PostNL, 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 restent désactivées jusqu'à ce que vous en activiez une et enregistriez. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages PostNL conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox PostNL > 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.

Si une valeur est erronée, rien n'est enregistré et la page indique la raison : un nom d'option vide, de plus de 64 caractères, ou contenant < > ; = # { } ; un ordre d'affichage qui n'est pas un nombre entier ; un poids minimum supérieur au poids maximum ; ou une classe de taxe ou une zone géographique invalide. Les problèmes mineurs sont enregistrés avec une remarque : un nombre invalide ou négatif laisse son champ vide, un code postal d'expédition invalide est enregistré vide, et un prix invalide dans le tableau est ignoré.

Au-dessus des réglages, la page affiche des avertissements : clé API ou code postal d'expédition manquant pour les points relais, bac à sable activé, aucun prix défini, la dernière requête PostNL échouée avec sa date et son erreur, ou une boutique sans classe de poids « kg ».

Général

Chaque type de livraison est une option distincte au moment du paiement. Les réglages de cette page s'appliquent aux deux.

PostNL pickup point : active ou désactive l'option de point relais. Le client doit choisir un point PostNL au moment du paiement. Elle n'est proposée que pour les adresses des Pays-Bas et de Belgique, et uniquement avec une clé API. Par défaut : désactivé.

Pickup point option name : le nom affiché au client au moment du paiement. Par défaut : PostNL pickup point. Obligatoire, 64 caractères maximum, sans < > ; = # { }.

PostNL home address : active ou désactive l'option de livraison à domicile. Aucun point n'est choisi. Elle fonctionne pour chaque pays disposant d'un prix. Par défaut : désactivé.

Home delivery option name : le nom affiché au client au moment du paiement. Par défaut : PostNL. Mêmes règles que pour le nom du point relais.

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

Tax class : la classe de taxe des deux options. Avec une classe de taxe, OpenCart ajoute sa taxe aux prix. No tax signifie que les prix sont définitifs.

API PostNL (points relais) (non nécessaire pour la livraison à domicile)

API key : votre clé API PostNL depuis 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. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved API key : cochez la case et cliquez sur Save pour supprimer la clé enregistrée. L'option de point relais n'est alors plus proposée.

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

Ship from (country) : le pays dans lequel vous remettez vos colis à PostNL : Pays-Bas ou Belgique. PostNL utilise l'adresse de l'expéditeur pour la date d'enlèvement. À l'installation, il est réglé sur le pays de votre boutique si c'est les Pays-Bas ou la Belgique, sinon sur les Pays-Bas.

Ship from (postcode) : le code postal de l'expéditeur, par exemple 1234AB aux Pays-Bas ou 1000 en Belgique. Obligatoire pour les points relais : OpenCart n'a pas de code postal de boutique, il n'est donc pas repris de l'adresse de la boutique. Un code postal invalide est enregistré vide avec un avertissement.

Lorsque vous modifiez la clé API, le réglage du bac à sable ou l'adresse d'expédition, les listes de points relais en cache et la dernière erreur de l'API sont effacées.

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

Les prix s'appliquent aux deux options. PostNL ne propose pas d'API publique de tarifs : l'extension ne demande donc aucun tarif en temps réel. Pour un client qui paie dans une autre devise, OpenCart convertit le prix 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 le bouton × pour en supprimer une. Choisissez * All other countries pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne comporte 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. Le prix d'une classe de poids remplace Price ; laissez-le vide pour utiliser Price. Un Price de 0 signifie livraison gratuite. « 6.95 » et « 6,95 » sont acceptés. Les lignes sans prix sont supprimées à l'enregistrement. Si un pays apparaît deux fois, la première ligne est conservée. Les prix invalides sont ignorés avec un avertissement.

Calculation : Per order facture le prix 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 options à cet endroit.

Conditions

Free shipping from : le sous-total du panier (produits nécessitant une livraison, hors taxes, après le coupon) à partir duquel la livraison est gratuite. Elle ne s'applique que là où un prix est trouvé. Laissez vide pour ne jamais proposer la livraison gratuite.

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

Minimum weight (kg) : masque les options lorsque le panier pèse moins. Les poids des produits sont convertis à partir de leur classe de poids. Laissez vide pour aucune limite.

Maximum weight (kg) : masque les options pour les paniers plus lourds. Les colis PostNL vont jusqu'à 30 kg au Benelux. 0 signifie aucune limite. Si vous le laissez vide, 30 kg s'appliquent, ou aucune limite lorsque Ignore shipping zones est activé.

Tous les montants et poids acceptent la virgule décimale.

Disponibilité

Geo zone : ne proposer PostNL que pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. La zone géographique 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 PostNL est proposé pour les pays sélectionnés ci-dessous (tous les pays si la liste est vide). Lorsqu'il est désactivé, seule la zone géographique compte.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé. L'option de point relais n'est toujours proposée que pour les Pays-Bas et la Belgique.

Avancé

Debug log : écrit des messages de débogage dans storage/logs/vfd_ptnl_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_ptnl_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API et les commandes sans point relais valide sont toujours journalisées. Aucune clé API ni donnée client n'est écrite. 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 PostNL et le journal. Les listes de points en cache sont toujours supprimées. Les points relais 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 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. La clé API enregistrée est conservée.

Fonctionnement au moment du paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix de chaque option PostNL. Si Ignore shipping zones est activé, PostNL n'est proposé que pour un pays autorisé, quelle que soit la zone géographique. Sinon, si une Geo zone est définie, l'adresse doit s'y trouver. 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 le poids du panier et le sous-total minimum. Elle prend ensuite le prix dans le tableau pour le pays et la classe de poids, ou le prix pour les autres pays. S'il n'y a pas de prix, l'option est masquée. Si le sous-total du panier atteint Free shipping from, le prix est de 0. Le prix est affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

L'option de point relais n'est proposée que pour les adresses des Pays-Bas et de Belgique, et uniquement avec une clé API. Lorsque l'adresse de livraison comporte un code postal complet, l'extension demande à l'API Checkout de PostNL les trois points relais les plus proches. Elle envoie le code postal, la rue et le numéro, la ville et le pays du client, ainsi que votre adresse d'expédition. Rien n'est envoyé pour l'option de livraison à domicile. Si PostNL est injoignable ou ne dispose d'aucun point pour l'adresse, l'option de point relais est masquée et la 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 adresse, 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. Le cache est conservé dans la table de base de données propre à l'extension. La dernière erreur est affichée sur la page de l'extension jusqu'à la requête suivante réussie.

L'extension ne demande pas de tarifs PostNL en temps réel et ne crée ni étiquettes d'expédition, ni codes-barres, ni suivi, ni retours, ni pré-alertes. Elle ne propose aucune option de livraison en soirée, le matin ou à un jour précis. Créez l'envoi dans Mijn PostNL ou dans un autre outil PostNL en utilisant le point relais 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 PostNL 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 aux Pays-Bas ou en Belgique, une liste PostNL pickup point apparaît sous l'option de point relais avec les trois points les plus proches : nom de l'entreprise, adresse et distance, le plus proche en premier. La page n'attend jamais PostNL : si la liste n'est pas encore en cache, elle est chargée dès que l'option est sélectionnée. Avant la saisie d'un code postal complet, le client voit « Enter your postcode (for example 1234 AB) to see PostNL pickup points. » (4 chiffres pour la Belgique). Le point choisi est enregistré immédiatement pour le paiement.

Le point est obligatoire. Lorsque le client clique sur Continue à l'étape du mode de livraison, le serveur vérifie le point par rapport à la liste de PostNL pour l'adresse de livraison. Sans point, le client voit « Please choose a PostNL pickup point. » Si le point ne figure pas dans la liste, le client voit « The chosen PostNL pickup point is not available for this address. Please choose it again. » Si PostNL est injoignable, le client voit « PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. » 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.

Pages de commande, e-mails et facture : le point est ajouté au mode de livraison de la commande, par exemple « PostNL pickup point : nom, adresse » (le nom de l'option de point relais, puis le point) (jusqu'à 128 caractères, sur OpenCart 4 jusqu'à 255). Il apparaît partout où OpenCart affiche le mode de livraison : l'historique des commandes du client, les e-mails de commande, la facture et Sales > Orders.

Page de commande de l'administration : dans Sales > Orders, la page de commande affiche au-dessus de l'historique un encadré PostNL pickup point avec le point, le Location code et le Partner ID. Il n'apparaît que pour les commandes ayant un point enregistré, même après la désactivation de l'extension.

Sur OpenCart 4, la liste des points apparaît dans la fenêtre Shipping method options, sous l'option PostNL pickup point, 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 valide, 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.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PostNL est le premier bloc de Extensions > Extensions > Shipping > VibeFox PostNL > 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) 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: opencart-shipping-postnl 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 sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, les options de livraison PostNL ne sont pas affichées aux clients au moment 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

PostNL n'apparaît pas au paiement : vérifiez que la licence est active et que PostNL pickup point ou PostNL home address est activé. Vérifiez la Geo zone (ou que Ignore shipping zones est activé et que le pays est autorisé), qu'un prix est défini pour le pays, les limites de poids et le Minimum subtotal. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

L'option de point relais n'apparaît pas : elle n'est affichée que pour les adresses néerlandaises et belges, uniquement avec une clé API, un code postal d'expédition et un prix, et seulement lorsque PostNL renvoie des points pour le code postal du client. Vérifiez les avertissements en haut de la page de l'extension et le champ Log. Les erreurs sont toujours journalisées ; activez le Debug log pour obtenir les détails.

« PostNL pickup points cannot be loaded right now » : PostNL était injoignable, a rejeté la clé API, ou le code postal d'expédition est manquant. La page de l'extension affiche la dernière erreur. Une clé de bac à sable ne fonctionne que si Sandbox est activé, et une clé réelle seulement s'il est désactivé.

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

Les poids des produits semblent faux : si la page de l'extension signale que la boutique n'a pas de classe 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 PostNL! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_postnl (OpenCart 3) ou extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API PostNL peut être remplacée avec le réglage vfd_ptnl_api_url (pour les tests) ; il n'a pas de champ sur la page de configuration.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox PostNL. 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, Sort order, Tax class et Geo zone. Les listes de points en cache et la dernière erreur de l'API sont toujours supprimées. Si Remove data on uninstall est activé, les réglages PostNL, le journal de débogage et les points des processus de paiement 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 relais 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 PostNL dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

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