VibeFox bpost Cubee 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.
Compte bpost Shipping Platform (uniquement pour le sélecteur de point de retrait) : l'extension recherche les points de retrait via l'API bpost Shipping Platform. Connectez-vous à votre compte bpost Shipping Platform sur plugins.bpost.be et créez les clés dans Settings > Key management. Il vous faut trois valeurs : Account ID (clé publique), Passphrase (clé privée) et un App ID (X-APPID). L'App ID est délivré par bpost pour votre intégration ; demandez-le au support e-commerce de bpost (eol@bpost.be). Il vous faut aussi l'identifiant de transporteur de votre contrat (68 = bpost). Sans clés complètes, le mode fonctionne toujours comme mode de livraison à prix fixe, mais le client n'est pas invité à choisir un point de retrait.
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_bpost_cubee dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox bpost Cubee, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Saisissez vos prix et, pour le sélecteur de point de retrait, les clés API bpost (voir Configuration).
6. Ajoutez VibeFox bpost Cubee à votre zone de livraison pour la Belgique dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox bpost Cubee. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à une zone, la fenêtre de la zone ne contient qu'un seul champ :
Title (zone) : le nom de cette option au paiement pour cette zone. Laissez vide pour utiliser le Name général.
La page des réglages affiche des avertissements lorsqu'un élément masque discrètement le mode ou le sélecteur : le sélecteur de point de retrait est activé mais les clés API sont incomplètes, il n'y a pas de prix pour la Belgique, ou la dernière connexion à l'API bpost a échoué. À chaque enregistrement des réglages, le jeton API enregistré et les listes de points de retrait en cache sont effacés.
Général
Enable/Disable : active ou désactive la livraison en consigne bpost dans toutes les zones à la fois.
Name : le nom du mode de livraison affiché au client au paiement. Par défaut : bpost parcel locker.
Tax status : Taxable ajoute la taxe WooCommerce à vos prix, None signifie que les prix sont définitifs.
API bpost (recherche de points de retrait) (nécessaire uniquement pour le sélecteur de point de retrait)
Account ID (public key) : la clé publique de votre compte bpost Shipping Platform, à récupérer dans Key management sur plugins.bpost.be.
Passphrase (private key) : la clé privée qui signe chaque requête (HMAC-SHA256). Elle n'est jamais envoyée à bpost ni écrite dans le journal.
App ID (X-APPID) : l'identifiant d'application délivré par bpost pour votre intégration. Il est envoyé dans l'en-tête X-APPID.
Carrier ID : le transporteur de votre contrat bpost Shipping Platform dont les points de retrait et consignes sont listés. Par défaut : 68 (bpost). Les autres transporteurs activés dans votre contrat ont leurs propres identifiants.
Sélecteur de point de retrait
Pickup points : affiche le sélecteur de points de retrait et de consignes au paiement. Activé par défaut. Le sélecteur n'apparaît que lorsque les trois clés API sont renseignées.
Search field width : la largeur CSS du champ code postal / ville, par exemple 100% ou 300px. Par défaut : 100%.
Pickup point list width : la largeur CSS de la liste des points de retrait, par exemple 100% ou 400px. Par défaut : 100%.
Tarifs (dans la devise de votre boutique ; bpost ne renvoie pas les tarifs de livraison via cette API)
Price by : comment le prix est choisi.
Country prices : une ligne par pays au format CC=PRICE, par exemple BE=4.95. La ligne *=PRICE fixe le prix de tous les autres pays, par exemple *=9.95. Le point et la virgule sont tous deux acceptés comme séparateur décimal. Les lignes invalides sont ignorées et listées dans un message d'erreur lors de l'enregistrement. Les pays sans prix (lorsqu'il n'y a pas de ligne *) ne se voient pas proposer le mode.
Size prices : utilisé lorsque Price by est réglé sur la taille du colis, au format S=3.50, M=4.50, L=6.00, XL=8.00. La taille est déterminée par le poids du panier : S jusqu'à 2 kg, M jusqu'à 5 kg, L jusqu'à 10 kg, XL au-delà de 10 kg.
Calculation : Per order facture le prix une seule fois. Per item (price x number of items) le multiplie par le nombre d'articles du panier.
Conditions
Min weight (kg) : le poids minimum du panier pour que le mode apparaisse. 0 signifie sans limite.
Max weight (kg) : le mode est masqué au-delà de ce poids de panier. Par défaut : 30, car les consignes bpost acceptent les colis jusqu'à 30 kg. 0 signifie sans limite.
Minimum order amount : n'affiche le mode que lorsque le sous-total du panier (hors taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.
Excluded shipping classes : masque le mode lorsqu'un article du panier appartient à l'une de ces classes d'expédition WooCommerce.
Les poids des produits sont convertis de l'unité de poids de votre boutique en kilogrammes.
Livraison gratuite
Free shipping : active la livraison gratuite à partir du montant ci-dessous.
Free shipping from : le sous-total du panier (hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.
Disponibilité sans zones de livraison
Ignore shipping zones : propose le mode dans les pays indiqués ci-dessous, sans l'ajouter à une zone.
Countries : les pays de destination pour ce mode. Par défaut : Belgique. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.
Avancé
Debug log : journalise les requêtes API et les calculs de prix dans WooCommerce > Status > Logs, source vfd-bpost-cubee. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. Les clés, jetons et données clients ne sont jamais journalisés.
Remove data on uninstall : si l'option est activée, la suppression de l'extension efface ses réglages et ses méthodes de zone. La désactivation de l'extension ne supprime jamais de données. 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 : pays de livraison, poids du panier, montant minimum de commande et classes d'expédition exclues. Elle prend ensuite le prix dans la liste des pays ou selon la taille du colis, le multiplie par le nombre d'articles en mode Per item, et le met à zéro lorsque la livraison gratuite s'applique.
Lorsque le client choisit le tarif bpost, un champ de recherche, un bouton Search et une liste de points de retrait apparaissent en dessous. Si le champ de recherche est vide, le code postal de l'adresse de paiement est recherché automatiquement. Le client peut saisir un autre code postal ou le nom d'une ville. Chaque point est affiché avec son nom et son adresse. Jusqu'à 50 points sont listés. La liste des points de retrait est demandée en néerlandais sur les sites en néerlandais, et en français sinon.
Le client doit choisir un point de retrait. Sans choix, le paiement classique affiche Please select a bpost pickup point., et le paiement par blocs refuse de passer la commande avec le même message. Le choix est conservé pendant la session de paiement, de sorte qu'un rafraîchissement de la page ne le fait pas disparaître.
Pour lister les points de retrait, l'extension n'envoie à bpost que le code postal ou la ville recherché, le pays et l'identifiant de transporteur, signés avec vos clés. Aucun nom, adresse e-mail ni ligne d'adresse du client n'est envoyé. Le jeton API est demandé et renouvelé automatiquement. Si bpost rejette un jeton, un nouveau est demandé une fois et la recherche est répétée. Les résultats de recherche sont mis en cache pendant 6 heures. Si bpost ne répond pas, le client voit Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method., et l'extension réessaie après 5 minutes. Le délai d'attente de l'API est de 15 secondes.
Le mode fonctionne sur le paiement classique et dans les blocs Panier et Paiement. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension utilise uniquement des prix fixes. Elle ne récupère pas de tarifs en temps réel auprès de bpost, ne crée pas d'envois, n'imprime pas d'étiquettes et ne suit pas les colis. Les points de retrait sont affichés sous forme de liste, et non sur une carte. Créez les envois dans votre compte bpost Shipping Platform ou Shipping Manager ; l'identifiant du point de retrait figure dans la commande.
Points de retrait
Le point de retrait choisi (nom et adresse) ainsi que son identifiant sont enregistrés dans la commande. Sur l'écran de commande de l'administration, il s'affiche sous l'adresse de livraison comme bpost pickup point. Cliquez sur Change, recherchez un code postal ou une ville et choisissez un autre point dans la liste. La commande est mise à jour immédiatement et une note de commande bpost pickup point changed to: … est ajoutée. Le lien Change n'est disponible que lorsque les clés API sont renseignées.
Les clients voient le point de retrait sur la page de remerciement et dans My account > Orders. Il est aussi ajouté aux e-mails de commande, en HTML comme en texte brut.
Pour proposer la consigne et la livraison à domicile ensemble, ajoutez une autre méthode d'expédition, par exemple Flat rate, à la même zone. Le sélecteur de point de retrait n'apparaît que sous le tarif bpost.
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 bpost Cubee. 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, ainsi que 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, le mode bpost n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, avec la mention (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 Extensions 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
bpost n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez que le pays a un prix ou une ligne *=PRICE, puis contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. La page des réglages affiche un avertissement lorsque la Belgique n'a pas de prix.
Pas de sélecteur de point de retrait au paiement : vérifiez que Pickup points est activé et que Account ID (public key), Passphrase (private key) et App ID (X-APPID) sont tous renseignés. La page des réglages affiche un avertissement lorsque les clés sont incomplètes.
Les clients voient « Pickup points cannot be loaded right now » : bpost n'a pas répondu ou a refusé les clés. La raison figure dans WooCommerce > Status > Logs (source vfd-bpost-cubee) et sur la page des réglages. L'extension réessaie automatiquement après 5 minutes. L'enregistrement des réglages relance immédiatement une tentative.
Aucun point de retrait trouvé pour ce code postal ou cette ville : bpost n'a renvoyé aucun point pour cette recherche. Demandez au client d'essayer un code postal voisin ou le nom d'une ville, et vérifiez le Carrier ID.
Les prix avec une virgule ne sont pas utilisés : 5,50 et 5.50 sont tous deux acceptés. Les lignes de Country prices qui ne suivent pas le format CC=PRICE sont ignorées ; le message d'erreur affiché après l'enregistrement les liste.
Les prix incluent-ils la taxe ? Avec Tax status réglé sur Taxable, WooCommerce ajoute la taxe à vos prix. Avec None, les prix sont définitifs.
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 ; elle efface seulement le jeton API et 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, le jeton API et les caches sont toujours supprimés. 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 future réinstallation. Les points de retrait enregistrés dans les commandes font partie de l'historique des commandes et ne sont jamais supprimés.
bpost est une marque commerciale de son propriétaire. Cette extension n'est ni affiliée à bpost ni approuvée par bpost.