VibeFox Instabee 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.

Identifiants API Budbee (uniquement pour le choix de la boîte colis) : une clé API et un secret API. Instabee les délivre aux marchands ayant un contrat de livraison. Demandez-les à votre interlocuteur Instabee ou utilisez le portail marchand d'Instabee. La documentation de l'API se trouve sur developer.budbee.com. Sans identifiants, le transporteur fonctionne toujours avec des tarifs fixes, mais les clients ne peuvent pas choisir de boîte colis.

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éversement terminé, cliquez sur Configure, ou retrouvez VibeFox Instabee 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. Renseignez la section Prices et, pour le sélecteur de boîtes colis, votre API key et votre API secret Budbee (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur Instabee parcel box avec le texte de délai de livraison Delivery to an Instabee parcel box. Le transporteur est associé à tous les groupes de clients et aux zones de Suède, de Finlande, du Danemark, des Pays-Bas et de Belgique. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison et le logo dans Shipping > Carriers. Ne définissez pas de prix à cet endroit : le prix vient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Instabee > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière.

Des avertissements au-dessus des réglages vous indiquent lorsqu'un seul des identifiants API est saisi, lorsqu'il n'y a aucun identifiant API, lorsqu'il n'y a ni tarif par pays ni coût de repli, lorsque la dernière requête à l'API Budbee a échoué (avec la date, l'heure et la raison), lorsque le transporteur Instabee est introuvable et lorsque l'unité de poids de la boutique n'est pas reconnue (réglez kg, g, lb ou oz dans International > Localization, Local units). À chaque enregistrement des réglages, les listes de boîtes colis en cache et la dernière erreur API sont effacées. Si le nom de la méthode ou le statut de taxe n'est pas valide, ou si Min weight (kg) est supérieur à Max weight (kg), rien n'est enregistré et une erreur s'affiche.

General

Enable/Disable : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method name : le nom du transporteur affiché au client lors du paiement. Par défaut : Instabee parcel box. Obligatoire, 64 caractères maximum.

Tax status : None signifie que les prix ci-dessous sont définitifs. Taxable avec une règle de taxe signifie que PrestaShop ajoute la taxe d'expédition de cette règle aux prix ci-dessous.

Sélecteur de boîtes colis (API Budbee)

Avec des identifiants API, le client choisit une boîte colis proche de son code postal lors du paiement, et la boîte est enregistrée sur la commande. Les deux champs sont nécessaires. Le sélecteur reste désactivé tant que les deux ne sont pas renseignés.

API key : votre clé API Budbee (le nom d'utilisateur HTTP Basic).

API secret : votre secret API Budbee (le mot de passe HTTP Basic). Il n'est jamais écrit dans le journal.

Après l'enregistrement, les deux champs restent vides et affichent Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Pour supprimer les identifiants enregistrés, cochez Remove the saved API key and secret puis enregistrez. Lorsque rien n'est enregistré, la page affiche No credentials saved.

Test environment : utilise l'API de test de Budbee (api.staging.budbee.com). Activez-le uniquement avec des identifiants de test fournis par Instabee. Les boutiques en production le laissent désactivé (api.budbee.com). Par défaut : désactivé.

Tarifs (le titre de la section affiche la devise par défaut de votre boutique)

Tous les tarifs sont exprimés dans la devise par défaut de la boutique, hors taxes. Une virgule décimale et un point décimal sont tous deux acceptés (49,90 = 49.90). Le prix est affiché au client dans la devise du panier.

Calculation type : la manière dont le prix est appliqué.

Country prices : un tableau avec les colonnes Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * Any other country pour une ligne qui s'applique à tous les pays sans ligne propre. Une tranche vide ou égale à 0 utilise la colonne Price. Un Price de 0 signifie livraison gratuite. Si la ligne du pays n'a pas de prix pour le poids du panier, la ligne * est utilisée, puis le Fallback cost. Un prix qui n'est pas un nombre est effacé, et un avertissement le signale. Les poids sont convertis de l'unité de poids de votre boutique en kg.

Fallback cost : utilisé lorsque ni la ligne du pays de destination ni la ligne * ne donnent de prix. Laissez-le vide pour masquer le transporteur pour ces pays.

Conditions

Min weight (kg) : masque le transporteur en dessous de ce poids de panier. Par défaut : 0 (pas de limite).

Max weight (kg) : masque le transporteur au-dessus de ce poids de panier. Les boîtes colis acceptent jusqu'à environ 20 kg. Par défaut : 20. 0 signifie pas de limite. Ce champ ne peut pas être inférieur à Min weight (kg).

Minimum order amount : affiche le transporteur uniquement lorsque le sous-total du panier (produits nécessitant une expédition, après remises, hors taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

Free shipping from : le sous-total du panier (après remises, hors taxes) à partir duquel le transporteur est gratuit. Laissez vide pour ne jamais le rendre gratuit.

Si une valeur de ces champs ou du champ Fallback cost n'est pas un nombre, elle n'est pas enregistrée, la valeur précédente est conservée, et un avertissement indique le champ concerné.

Disponibilité sans zones d'expédition

En règle générale, le transporteur est proposé dans les zones d'expédition auxquelles il est lié dans Shipping > Carriers. Vous pouvez aussi l'activer ici pour une liste de pays.

Ignore shipping zones : propose le transporteur dans les pays ci-dessous, même lorsque ses zones ne les incluent pas. Le transporteur est lié à toutes les zones actives, y compris celles créées plus tard. Lorsque vous désactivez à nouveau l'option, le transporteur retrouve les zones qu'il avait auparavant.

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é.

Avancé

Debug log : écrit les messages de débogage dans logs/vfd_ibee_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs API sont toujours journalisées, même lorsque cette option est désactivée. Les clés API et les données clients ne sont jamais journalisées.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages et le transporteur. Lorsqu'elle est désactivée, la désinstallation désactive seulement le transporteur. Les boîtes colis enregistrées sur les commandes sont toujours conservées.

Fonctionnement lors du paiement

À l'étape d'expédition, PrestaShop demande au module le prix Instabee. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le module vérifie les conditions : poids du panier et montant minimum de commande et, avec Ignore shipping zones, les pays autorisés. Si le sous-total du panier atteint Free shipping from, le prix est de 0. Sinon, le prix est repris de la ligne Country prices du pays de destination, de la ligne * ou du Fallback cost. S'il n'y a pas de prix, le transporteur est masqué.

Lorsque le client sélectionne le transporteur Instabee et que les identifiants API sont renseignés, un bloc Parcel box apparaît sous le transporteur pour la Suède, la Finlande, le Danemark, les Pays-Bas et la Belgique. Il affiche les boîtes proches du code postal de l'adresse de livraison, triées par distance, avec le nom, l'adresse et la distance. Le client peut saisir un autre code postal et cliquer sur Search (ou appuyer sur Entrée). Tant qu'aucun code postal n'est saisi, le bloc le demande. Si aucune boîte n'est trouvée, le client est invité à essayer un autre code postal ou à choisir un autre mode de livraison. Pour les autres pays, le transporteur est proposé sans boîte.

La boîte colis est obligatoire. La boîte choisie n'est enregistrée dans le panier que si elle figure dans la liste Budbee pour ce code postal. Lorsque le client clique sur Continue à l'étape de livraison, le module vérifie de nouveau la boîte côté serveur. Sinon, le client voit Please choose an Instabee parcel box. Le nom de la boîte provient de la liste Budbee, et non du navigateur. Si le client modifie le pays de livraison ou le code postal de l'adresse, le choix précédent est annulé.

Le module n'envoie à Budbee que le pays de destination et le code postal, jamais les noms, adresses, e-mails ou données de commande. Les listes de boîtes sont mises en cache pendant 12 heures par code postal, un code postal sans boîte pendant 1 heure et une requête échouée pendant 5 minutes, afin qu'une API lente ou en panne ne ralentisse pas chaque actualisation du paiement. La page de paiement n'attend jamais Budbee : la liste est chargée en arrière-plan dès que le transporteur est sélectionné. Le délai d'expiration de l'API est de 10 secondes.

Si l'API Budbee est injoignable, le client voit Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. La commande est alors signalée, et vous choisissez la boîte lors de la réservation de l'envoi. Une boîte choisie précédemment qui ne peut pas être vérifiée à ce moment est conservée et marquée comme non vérifiée.

Le sélecteur fonctionne avec les thèmes Classic et Hummingbird. 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 ne calcule pas de tarifs en temps réel, ne réserve pas d'envois, n'imprime pas d'étiquettes, ne fournit pas de numéros ou d'e-mails de suivi, ne propose pas de créneaux de livraison Budbee Home et n'affiche pas de carte. Réservez le colis pour la boîte choisie dans vos outils marchands Instabee / Budbee.

Points de retrait

Lors de la création de la commande, la boîte est vérifiée une dernière fois et enregistrée sur la commande. Ensuite, la boutique en ligne ne peut plus la modifier. La boîte est affichée aux endroits suivants :

Page de commande dans le back-office : un bloc Instabee parcel box avec le nom de la boîte, son adresse et le Box ID. Si la boîte n'a pas pu être vérifiée lors du paiement, elle est marquée not verified (Budbee API was unavailable at checkout). Si aucune boîte n'a été choisie parce que l'API était indisponible, le bloc indique Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.

Page de confirmation de commande et détails de la commande dans le compte client : Instabee parcel box : avec le nom et l'adresse de la boîte.

E-mails de commande : la boîte est ajoutée au nom du transporteur dans l'e-mail de confirmation de commande envoyé au client. L'e-mail de nouvelle commande adressé à la boutique (depuis le module Mail alerts de PrestaShop) affiche également l'ID de la boîte. Si aucune boîte n'a été choisie parce que l'API était indisponible, seul l'e-mail adressé à la boutique le mentionne.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Instabee est le premier bloc de la page Modules > Module Manager > VibeFox Instabee > 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) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-instabee 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é un emplacement 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. Supprimer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Instabee n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office ; le transporteur est donc masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais vous ne pouvez pas le tester lors du 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 licence.

Dépannage

Instabee 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 est autorisé. Vérifiez que le pays a un prix, ou qu'il existe une ligne * ou un Fallback cost. Vérifiez les limites de poids et le Minimum order amount. Un avertissement au-dessus des réglages vous indique lorsqu'aucun prix n'est configuré. Des produits peuvent aussi être limités à certains transporteurs dans la fiche produit. Activez le Debug log pour voir la raison dans le champ Log.

Les clients ne voient pas la liste des boîtes colis : la liste n'apparaît que lorsque API key et API secret sont renseignés, pour la Suède, la Finlande, le Danemark, les Pays-Bas et la Belgique, et une fois un code postal saisi. La dernière erreur API est affichée au-dessus des réglages. Les détails se trouvent dans le champ Log de la page du module. Activez le Debug log pour plus de détails.

HTTP 401 ou 403 dans le journal : Budbee a rejeté la clé ou le secret API. Vérifiez-les et assurez-vous que Test environment correspond à vos identifiants (identifiants de test uniquement avec l'environnement de test activé).

Aucune boîte pour un code postal : Budbee ne dessert pas ce code postal. Le client peut rechercher un autre code postal ou choisir un autre mode de livraison.

Le client ne peut pas poursuivre à l'étape de livraison : une boîte colis doit être choisie dans la liste, sauf si l'API Budbee est injoignable. Une boîte qui ne figure pas dans la liste du code postal recherché n'est pas enregistrée, et le client voit This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Anciennes listes de boîtes après une modification : cliquez sur Save sur la page du module. Cela efface les listes de boîtes en cache.

La page indique que le transporteur Instabee est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. Il en va de même pour le message The settings were saved, but the carrier could not be updated. La réinitialisation conserve le statut du transporteur : un transporteur désactivé reste désactivé.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Instabee et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. Les listes de boîtes en cache sont toujours supprimées. 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 boîtes choisies dans les paniers qui n'ont jamais donné lieu à une commande. Si l'option est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur enregistré le statut qu'il avait. Les boîtes colis enregistrées sur les commandes sont toujours conservées.

Instabee et Budbee sont des marques déposées de leurs propriétaires respectifs. Ce module n'est affilié ni à Instabee ni à Budbee, et n'est pas approuvé par eux.