VibeFox bpost Cubee for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec 3.0.5.0) ou 4.0.2 et ultérieur (testé avec 4.1.0.3).

PHP : 8.0 ou ultérieur.

Compte bpost Shipping Platform (pour le sélecteur de point relais uniquement) : l'extension recherche les points relais 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. Vous avez besoin de 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 ; adressez-vous 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, la méthode fonctionne toujours avec des prix fixes, mais le client n'est pas invité à choisir un point relais.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_bpost_cubee-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_bpost_cubee.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_bpost_cubee-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 aussi copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox bpost Cubee et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page de configuration.

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

5. Saisissez vos prix, par exemple BE=4.95 et *=9.95, et, pour le sélecteur de point relais, les clés API bpost (voir Configuration). Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_bpost_cubee.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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é de lui.

3. Allez dans Extensions > Extensions et choisissez le type Shipping. Repérez VibeFox bpost Cubee, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions.

Après l'installation, la méthode reste désactivée tant que vous ne l'activez pas et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le jeton API mémorisé et les listes de points relais en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Certaines erreurs bloquent l'enregistrement, et rien n'est alors enregistré : un Name de plus de 64 caractères, un Sort Order qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue. Les autres problèmes sont signalés sous forme d'avertissements et le reste est enregistré : un poids ou un montant qui n'est pas un nombre ou qui est négatif n'est pas enregistré et la valeur précédente est conservée ; si Min weight (kg) est supérieur à Max weight (kg), les poids ne sont pas enregistrés ; les lignes de Country prices qui n'ont pas pu être lues sont listées et ignorées ; une valeur de Size prices dans laquelle aucune taille n'a été reconnue est signalée.

En haut de la page, un avertissement signale ce qui masque silencieusement la méthode ou le sélecteur : le sélecteur de point relais est activé mais les clés API sont incomplètes, il n'existe aucun prix pour la Belgique (BE) ni de prix par défaut (*=PRIX), la dernière connexion à l'API bpost a échoué, ou la boutique n'a pas de classe de poids avec l'unité « kg » (System > Localisation > Weight Classes). Dans ce dernier cas, les poids des produits sont lus d'après le nom de leur unité (kg, g, lb ou oz).

Général

Enable/Disable : active ou désactive la livraison en consigne bpost au moment du paiement. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client au moment du paiement. Par défaut : bpost parcel locker. Si vous le laissez vide, la valeur par défaut est utilisée. 64 caractères maximum.

Tax Class : la taxe de cette classe s'ajoute à vos prix. --- None --- (par défaut) signifie que les prix sont définitifs.

Sort Order : la position de la méthode dans la liste des modes de livraison.

API bpost (recherche de points relais) (nécessaire uniquement pour le sélecteur de point relais)

Account ID (public key) : la clé publique de votre compte bpost Shipping Platform, disponible 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 relais 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 relais

Pickup points : affiche le sélecteur de point relais et de consigne au moment du paiement. Activé par défaut. Le sélecteur apparaît, et un point relais est obligatoire, uniquement lorsque Account ID, Passphrase et App ID sont tous renseignés.

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 relais, 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 prix de livraison via 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'existe aucune ligne *) ne se voient pas proposer la méthode.

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 est déterminée par le poids du panier : S jusqu'à 2 kg, M jusqu'à 5 kg, L jusqu'à 10 kg, XL au-delà.

Calculation : Per order (par défaut) 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 la devise par défaut de votre boutique, puis affichés dans la devise du client.

Conditions

Min weight (kg) : le poids minimum du panier pour que la méthode apparaisse. Les poids des produits sont convertis en kg. 0 signifie aucune limite (par défaut).

Max weight (kg) : la méthode est masquée au-dessus de ce poids de panier. Par défaut : 30, car les consignes bpost acceptent les colis jusqu'à 30 kg. 0 signifie aucune limite.

Minimum order amount : affiche la méthode uniquement lorsque le sous-total du panier atteint ce montant. Le sous-total compte les produits à expédier, après coupons, hors taxes. Laissez le champ vide pour toujours afficher la méthode.

Livraison gratuite

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

Free shipping from : le sous-total du panier (produits à expédier, après coupons, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé. Le pays doit tout de même avoir un prix, sinon la méthode n'est pas proposée.

Disponibilité

En règle générale, la méthode est proposée dans la zone géographique sélectionnée ci-dessous. Avec Ignore geo zone, elle est proposée dans les pays de la liste à la place.

Geo Zone : propose la méthode uniquement pour les adresses de cette zone géographique. All Zones (par défaut) signifie partout. Les zones géographiques sont gérées dans System > Localisation > Geo Zones.

Ignore geo zone : propose la méthode dans les pays de la liste, quelle que soit la zone géographique.

Countries : les pays de destination pour ce mode. Par défaut : Belgium. Laissez le champ vide pour autoriser tous les pays. Utilisé uniquement lorsque Ignore geo zone est activé.

Avancé

Debug log : écrit les requêtes API et les calculs de prix dans storage/logs/vfd_bpst_debug.log.php. Ce fichier ne peut pas être lu depuis le web. Les erreurs de l'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'il est activé, la désinstallation de l'extension supprime les réglages, le journal et les choix de points relais des paiements non finalisés. Les points relais enregistrés dans les commandes sont toujours conservés. Par défaut : désactivé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La passphrase 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 passphrase enregistrée est conservée.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix bpost. Si une Geo Zone est définie (et que Ignore geo zone est désactivé) et que l'adresse se trouve en dehors, la méthode n'est pas proposée. Seuls les produits dont Requires Shipping est sur Yes comptent : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie les conditions : les pays de Ignore geo zone (si ce réglage est activé), le poids du panier et le montant minimum de commande. 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 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 l'option bpost, le client voit un champ Postal code or city, un bouton Search et une liste de points relais. Lorsque le client choisit bpost et que la liste n'est pas encore chargée, le code postal de l'adresse de livraison (ou la dernière recherche du client) 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 sinon.

Le client doit choisir un point relais. Sans point, Continue à l'étape du mode de livraison affiche Please select a bpost pickup point. Seul un point figurant dans la liste de 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 pour le paiement, de sorte qu'un rechargement de la page ne les perd pas. Une nouvelle recherche efface le choix précédent.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit bpost dans la fenêtre Shipping method options. La recherche et la liste des points relais apparaissent dans cette fenêtre, sous l'option bpost. Continue dans la fenêtre sans point relais affiche Please select a bpost pickup point. Le reste fonctionne comme sur OpenCart 3.

Pour lister les points relais, l'extension n'envoie à bpost que le code postal ou la ville recherché, 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 au maximum, sans dépasser la durée de vie du cache d'OpenCart (1 heure par défaut). 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.

L'extension n'utilise que 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 relais 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 relais figure sur la page de commande de l'administration.

Points relais

Lorsque la commande est passée, le point relais choisi est ajouté au mode de livraison de la commande sous la forme bpost pickup point: avec le nom et l'adresse du point, par exemple « bpost parcel locker - bpost pickup point: … ». Le client le voit donc sur la confirmation de commande, dans l'historique des commandes de son compte, dans les e-mails de commande et sur la facture. Le point complet, avec son identifiant, est aussi enregistré dans une table distincte de l'extension. Sur OpenCart 4, la page de paiement conserve une seule commande : lorsque le client confirme de nouveau la commande, par exemple après avoir choisi un autre point relais, le point de la commande est mis à jour.

Dans l'administration, la page de commande sous Sales > Orders affiche le panneau bpost pickup point avec 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 et le texte de son mode de livraison sont mis à jour immédiatement et la page affiche Pickup point updated. Si le point ne figure pas dans la liste de bpost pour la recherche, la page affiche Pickup point not found in the bpost list of this search. La modification est écrite dans le journal de débogage lorsque Debug log est activé. Change n'est disponible que lorsque les clés API sont renseignées et que l'utilisateur administrateur est autorisé à modifier les commandes ; l'accès aux réglages de l'extension n'est pas nécessaire.

Pour proposer ensemble la livraison en consigne et la livraison à domicile, utilisez un autre mode de livraison pour la livraison à domicile. Le sélecteur de point relais n'apparaît que sous l'option bpost.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox bpost Cubee est le premier bloc de Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier de nouveau l'état, 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-bpost-cubee et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les 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é un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier état 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 son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, bpost n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), ce qui vous permet de 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 ; sans clé active, le mode est donc masqué pour tout le monde. Une fois la page Edit ouverte, 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. L'état est vérifié automatiquement à nouveau à l'ouverture du Dashboard de l'administration ou de 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 l'état de la licence.

Dépannage

bpost n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez la Geo Zone, ou que Ignore geo zone 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 vérifiez les limites de poids et le Minimum order amount. Vérifiez que les produits ont Requires Shipping sur Yes. La page de configuration affiche un avertissement lorsque la Belgique n'a pas de prix.

Aucun sélecteur de point relais au moment du 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 configuration 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 s'affiche en haut de la page de configuration et dans le journal de débogage (champ Log de la page de l'extension). L'extension réessaie automatiquement après 5 minutes. Enregistrer les réglages relance immédiatement la tentative.

Aucun point relais 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=PRIX sont ignorées ; l'avertissement affiché après l'enregistrement les liste.

Les prix incluent-ils la taxe ? Avec Tax Class sur --- None ---, les prix sont définitifs. Avec une classe de taxe, OpenCart ajoute cette taxe à vos prix.

La page indique « Warning: You do not have permission to modify VibeFox bpost Cubee! » : votre groupe d'utilisateurs administrateurs ne peut probablement que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_bpost_cubee (OpenCart 3) ou extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) dans System > Users > User Groups.

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox bpost Cubee. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort Order, Tax Class et Geo Zone. Le jeton API enregistré et les listes de points relais en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages, le journal et les points relais des paiements non finalisés sont aussi 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 points relais enregistrés dans les commandes font partie de l'historique des commandes et ne sont jamais supprimés. Les commandes existantes conservent leur mode de livraison et leur coût.

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 bpost Cubee dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet téléversé.

bpost est une marque commerciale de son propriétaire respectif. Cette extension n'est pas affiliée à bpost et n'est pas approuvée par bpost.