VibeFox bpost Cubee 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.

Compte bpost Shipping Platform (uniquement pour le sélecteur de point de retrait) : le module 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 du transporteur de votre contrat (68 = bpost). Sans clés complètes, le transporteur fonctionne toujours avec des prix fixes, mais les clients ne sont pas invités à choisir un point de retrait.

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 VibeFox bpost Cubee plus tard 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. Saisissez vos prix et, pour le sélecteur de point de retrait, les clés API bpost (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur bpost parcel locker avec le texte de délai de livraison Pickup point or parcel locker. Le transporteur est lié à la zone de Belgique et à tous les groupes de clients, sans règle de taxe. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison et le logo dans Shipping > Carriers. N'y définissez pas de prix : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox bpost Cubee > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi le jeton API stocké et les listes de points de retrait en cache.

La page affiche des avertissements lorsque quelque chose masque silencieusement le transporteur 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 (BE) ni de prix par défaut, la dernière connexion à l'API bpost a échoué, l'unité de poids de la boutique n'est pas connue du module (à définir dans International > Localization, Local units), ou le transporteur bpost est introuvable. Lors de l'enregistrement, les lignes de Country prices qui n'ont pas pu être lues sont listées dans un avertissement, ainsi qu'une valeur de Size prices dans laquelle aucune taille n'a été reconnue. Un poids ou un montant qui n'est pas un nombre ou qui est négatif n'est pas enregistré : un avertissement indique le champ et la valeur précédente est conservée. Si Min weight (kg) est supérieur à Max weight (kg), les poids ne sont pas non plus enregistrés.

Général

Enable/Disable : active ou désactive l'expédition avec bpost parcel locker. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name : le nom du mode de livraison affiché au client au paiement (le nom du transporteur). Par défaut : bpost parcel locker. Si vous le laissez vide, la valeur par défaut est utilisée. 64 caractères maximum ; un nom plus long est refusé et rien n'est enregistré.

Tax status : None signifie que les prix sont définitifs. Taxable avec une règle de taxe ajoute la taxe de cette règle à vos prix. Le choix est enregistré sur le transporteur.

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. Vider ce champ supprime aussi la Passphrase enregistrée.

Passphrase (private key) : la clé privée utilisée pour signer chaque requête (HMAC-SHA256). Elle n'est jamais envoyée à bpost 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.

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 point de retrait et de consigne au paiement. Activé par défaut. Le sélecteur n'apparaît, et un point de retrait n'est obligatoire, 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 par défaut de votre boutique, hors taxes ; bpost ne renvoie pas de tarifs d'expédition par cette API)

Price by : la manière dont le prix est choisi.

Country prices : une ligne par pays au format CC=PRIX, par exemple BE=4.95. La ligne *=PRIX définit 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. Les pays sans prix (lorsqu'il n'y a pas de ligne *) ne se voient pas proposer le transporteur.

Size prices : utilisé lorsque Price by est la taille du colis, au format S=3.50, M=4.50, L=6.00, XL=8.00. La taille dépend du poids du panier : S jusqu'à 2 kg, M jusqu'à 5 kg, L jusqu'à 10 kg, XL au-delà.

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.

Les prix sont arrondis aux décimales de votre devise par défaut, puis affichés dans la devise du panier du client.

Conditions

Min weight (kg) : le poids minimum du panier pour que le transporteur apparaisse. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie sans limite.

Max weight (kg) : le transporteur 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'afficher le transporteur que lorsque le sous-total du panier atteint ce montant. Le sous-total compte les produits nécessitant une expédition, après remises, hors taxes. Laissez le champ vide pour toujours afficher le transporteur.

Livraison gratuite

Free shipping : active la livraison gratuite à partir du montant indiqué ci-dessous.

Free shipping from : le sous-total du panier (produits nécessitant une expédition, après remises, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé. Le pays doit toujours avoir un prix, sinon le transporteur n'est pas proposé.

Disponibilité sans zones de livraison

Normalement, le transporteur est proposé dans ses zones de livraison dans Shipping > Carriers. À l'installation, il s'agit de la zone de Belgique.

Ignore shipping zones : proposer le transporteur dans les pays indiqués ci-dessous sans l'ajouter à une zone. Le transporteur est alors lié à toutes les zones actives, y compris aux zones que vous créerez plus tard. Lorsque vous désactivez à nouveau l'option, le transporteur retrouve ses zones précédentes.

Countries : les pays de destination pour ce mode. Par défaut : Belgique. Laissez le champ vide pour utiliser tous les pays vers lesquels vous expédiez. 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 logs/vfd_bpst_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, même lorsque cette option est désactivée. Les clés et les jetons ne sont jamais journalisés.

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'elle est activée, la désinstallation du module supprime ses réglages et le transporteur. Les points de retrait enregistrés dans les commandes sont toujours conservés.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix bpost. Seuls les produits nécessitant une expédition comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie les conditions : les pays de Ignore shipping zones (si l'option est activée), le poids du panier et le montant minimum de commande. Il prend ensuite le prix dans la liste par pays ou par taille de colis, le multiplie par le nombre d'articles en mode par article, et le met à zéro lorsque la livraison gratuite s'applique. Aucune requête n'est envoyée à bpost pour le prix.

Sous le transporteur bpost, le client voit un champ Postal code or city, un bouton Search et une liste de points de retrait. Lorsque le client choisit le transporteur et n'a pas encore fait de recherche, le code postal de l'adresse de livraison 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 est demandée en néerlandais lorsque la langue de la boutique est le néerlandais, et en français dans les autres cas.

Le client doit choisir un point de retrait. Sans cela, Continue à l'étape de livraison affiche Please select a bpost pickup point., et le bouton Place order est bloqué sur la page avec le même message. Seul un point de la liste bpost pour la recherche est accepté. Sinon, le client voit The selected bpost pickup point is not in the list of your search. Please choose another one. La recherche et le choix sont enregistrés avec le panier, de sorte qu'un rechargement de la page ne les fait pas disparaître. Une nouvelle recherche efface le choix précédent.

Pour lister les points de retrait, le module n'envoie à bpost que le code postal ou la ville recherchés, le pays et l'identifiant du transporteur, signés avec vos clés. 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 le module réessaie après 5 minutes. Le délai d'attente de l'API est de 15 secondes.

Si vous modifiez le 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 n'utilise que des prix fixes. Il 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

Lorsque la commande est passée, le point de retrait choisi (nom et adresse) et son identifiant sont enregistrés avec la commande. Sur la page de commande du back office, le bloc bpost pickup point affiche le point et son identifiant, ou No pickup point was selected for this order. Cliquez sur Change, recherchez un code postal ou une ville, choisissez un autre point dans la liste et cliquez sur Save. La commande est mise à jour immédiatement et la page affiche Pickup point updated. La modification est écrite dans le journal de débogage lorsque Debug log est activé. Le lien Change n'est disponible que lorsque les clés API sont renseignées. Enregistrer un nouveau point nécessite l'autorisation de modifier les commandes ; sinon, la page affiche Permission denied. L'accès aux pages Modules n'est pas nécessaire.

Si PrestaShop divise un panier en plusieurs commandes, le point de retrait reste associé à la première commande. Les autres commandes n'ont pas de point de retrait, et le journal de débogage affiche une erreur qui nomme la première commande ; définissez le point de ces colis manuellement dans bpost.

Les clients voient le point de retrait sous la forme bpost pickup point: sur la page de confirmation de commande et dans le détail des commandes de leur compte. Il est aussi ajouté au nom du transporteur dans l'e-mail de confirmation de commande. Le nouvel e-mail de commande envoyé à la boutique (si vous utilisez le module d'alertes e-mail) contient également l'identifiant du point.

Pour proposer la consigne et la livraison à domicile ensemble, utilisez un autre transporteur pour la livraison à domicile dans la même zone. Le sélecteur de point de retrait n'apparaît que sous le transporteur bpost.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox bpost Cubee est le premier bloc de Modules > Module Manager > VibeFox bpost Cubee > 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-bpost-cubee 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é une place 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 : celui de la boutique principale, y compris dans une configuration multiboutique. 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, le transporteur bpost n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. La partie publique de PrestaShop ne sait pas que vous êtes connecté au back-office, donc le transporteur est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans 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é à nouveau 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 ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

bpost n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable 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 shipping zones est activé et que le pays figure dans Countries. Vérifiez que le pays a un prix ou qu'il existe une ligne *=PRIX, et contrôlez les limites de poids et le Minimum order amount. Les produits peuvent aussi être limités à certains transporteurs sur la page du produit. La page de 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 de 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 est affichée sur la page de réglages et dans le journal de débogage (champ Log sur la page du module). Le module réessaie automatiquement après 5 minutes. Enregistrer les réglages relance immédiatement l'essai.

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 un nom de 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 respectent pas le format CC=PRIX sont ignorées ; l'avertissement après l'enregistrement les liste.

Les prix incluent-ils la taxe ? Avec Tax status sur None, les prix sont définitifs. Avec une règle de taxe Taxable, PrestaShop ajoute cette taxe à vos prix.

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

Pour les développeurs, les hooks actionVfdBpstApiUrl et actionVfdBpstApiLanguage modifient l'adresse de l'API bpost et la langue de la liste des points de retrait.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox bpost Cubee et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le jeton API stocké et les listes de points de retrait en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages, le journal et les points de retrait des paniers non finalisés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur le statut qu'il avait avant la désinstallation. Reset dans Modules > Module Manager fonctionne de la même façon : un transporteur désactivé reste désactivé. 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 respectif. Ce module n'est pas affilié à bpost et n'est pas approuvé par bpost.