VibeFox Instabee for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 7.0 ou ultérieur, installé et activé. Le plugin refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
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 à votre contact Instabee ou utilisez le portail marchand Instabee. La documentation de l'API est disponible sur developer.budbee.com. Sans identifiants, la méthode 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_instabee dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Instabee, ou cliquez sur Settings sous le nom du plugin sur la page des extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Remplissez la section Tarifs et, pour le sélecteur de boîte colis, votre API key et votre API secret Budbee (voir Configuration).
6. Ajoutez VibeFox Instabee aux zones d'expédition de vos pays de livraison (par exemple la Suède) 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 Instabee. Ils s'appliquent à toutes les zones d'expédition. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :
Title : le nom de ce tarif au paiement dans cette zone. Laissez-le vide pour utiliser le Method name général.
Les avertissements affichés au-dessus des réglages vous indiquent lorsqu'un seul des identifiants API est saisi, lorsqu'il n'y en a aucun, lorsqu'il n'y a ni tarif par pays ni coût de repli, et lorsque la dernière requête à l'API Budbee a échoué (avec la date, l'heure et la raison). À chaque enregistrement des réglages, les listes de boîtes en cache et la dernière erreur API sont effacées.
Général
Enable/Disable : active ou désactive la méthode partout, y compris dans les zones d'expédition. Par défaut : activé.
Method name : le nom de la méthode d'expédition affiché dans le panier et au paiement. Une zone peut le remplacer par son propre Title. Par défaut : Instabee parcel box.
Tax status : Taxable ajoute la taxe WooCommerce au coût d'expédition, None ne l'ajoute pas.
Sélecteur de boîte colis (API Budbee)
Avec des identifiants API, le client choisit au paiement une boîte colis proche de son code postal, 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).
Test environment : utilise l'API de test 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 de votre boutique)
Tous les tarifs sont exprimés dans la devise de la boutique. La virgule et le point décimaux sont tous deux acceptés (49,90 = 49.90). Une valeur qui n'est pas un nombre n'est pas enregistrée, et un message d'erreur indique le champ concerné.
Calculation type : la manière dont le tarif est appliqué.
Country prices : un tableau avec les colonnes Country, Price, XS (jusqu'à 1 kg), S (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (au-delà de 5 kg). Cliquez sur + Add country pour ajouter une ligne et sur la croix 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 tarif pour le poids du panier, la ligne * est utilisée, puis le Fallback cost. 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 tarif. Laissez-le vide pour masquer la méthode pour ces pays.
Conditions
Min weight (kg) : masque la méthode lorsque le panier pèse moins. Par défaut : 0 (pas de limite).
Max weight (kg) : masque la méthode lorsque le panier pèse plus. Les boîtes colis acceptent jusqu'à environ 20 kg. Par défaut : 20. 0 signifie pas de limite.
Minimum order amount : affiche la méthode uniquement lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.
Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la méthode est gratuite. Laissez vide pour ne jamais la rendre gratuite.
Excluded shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.
Disponibilité sans zones d'expédition
Normalement, vous ajoutez VibeFox Instabee à une zone d'expédition. Vous pouvez aussi l'activer ici pour une liste de pays.
Ignore shipping zones : propose la méthode dans les pays indiqués ci-dessous, même lorsqu'aucune zone d'expédition ne la contient.
Countries : les pays de destination pour ce mode. Laissez 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 : écrit les messages de débogage dans WooCommerce > Status > Logs (source vfd-instabee). Les erreurs API sont toujours enregistrées, même lorsque cette option est désactivée. Les clés API et les données clients ne sont jamais enregistrées.
Remove data on uninstall : lorsque l'option est activée, la suppression du plugin efface les réglages et les tarifs par zone de cette méthode. Désactiver le plugin ne supprime jamais les réglages. Les boîtes colis enregistrées sur les commandes sont conservées.
Fonctionnement au paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif au plugin. Le plugin vérifie les conditions : poids du panier, montant minimum de commande et classes d'expédition exclues. Si le sous-total du panier atteint Free shipping from, le tarif est gratuit. 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, la méthode est masquée.
Lorsque le client sélectionne le tarif Instabee et que les identifiants API sont renseignés, un sélecteur Parcel box apparaît sous le tarif pour la Suède, la Finlande, le Danemark, les Pays-Bas et la Belgique. Il liste 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. Tant qu'aucun code postal n'est saisi, le sélecteur en demande un. Si aucune boîte n'est trouvée, le client est invité à essayer un autre code postal ou à choisir une autre méthode d'expédition.
La boîte colis est obligatoire. Lors de la validation de la commande, le plugin vérifie côté serveur que la boîte choisie figure dans la liste Budbee pour ce code postal. Sinon, le client voit Please choose an Instabee parcel box. Le nom de la boîte est repris de la liste Budbee, et non du navigateur.
Le plugin 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 défaillante ne ralentisse pas chaque actualisation du paiement. Le délai d'attente de l'API est de 10 secondes.
Si l'API Budbee est injoignable, le client est informé que la commande peut être passée sans choisir de boîte. 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-là est conservée et marquée comme non vérifiée.
Le sélecteur fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Le plugin est compatible avec le stockage de commandes haute performance (HPOS) de WooCommerce.
Le plugin 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 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
La boîte colis choisie est enregistrée sur la commande et affichée aux endroits suivants :
Écran de commande de l'administration : sous l'adresse de livraison, sous la forme 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 au 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, l'écran l'indique et vous rappelle de choisir la boîte lors de la réservation de l'envoi.
Page de remerciement et page de commande de Mon compte : le nom et l'adresse de la boîte.
E-mails de commande : en HTML et en texte brut. Les e-mails envoyés à la boutique affichent aussi l'identifiant de la boîte. Si aucune boîte n'a été choisie parce que l'API était indisponible, seuls les e-mails envoyés à la boutique le mentionnent.
Clé de licence
Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Instabee. 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 l'emplacement dans votre compte vibefox.net.
Sans clé active, Instabee n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin avant d'acheter une clé. Un rappel apparaît sur la page des extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.
Lorsqu'une licence expire, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement en arrière-plan.
Dépannage
Instabee n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, et que la méthode est ajoutée à 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 tarif, ou qu'il existe une ligne * ou un Fallback cost. Contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. Un avertissement au-dessus des réglages indique lorsqu'aucun tarif n'est configuré.
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 qu'un code postal est saisi. La dernière erreur API est affichée au-dessus des réglages. Les détails figurent dans WooCommerce > Status > Logs (source vfd-instabee). Activez 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 vérifiez 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 une autre méthode d'expédition.
Anciennes listes de boîtes après une modification : enregistrez la page des réglages. Cela efface les listes de boîtes en cache.
Autres pays pour la recherche de boîtes : les développeurs peuvent modifier la liste des pays avec le filtre vfd_ibee_box_countries.
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, le plugin continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation du plugin efface seulement les listes de boîtes en cache. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin, les listes de boîtes en cache et la dernière erreur API sont toujours supprimés. Les réglages, les méthodes par zone et les données de version ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les boîtes colis enregistrées sur les commandes sont toujours conservées, et les commandes existantes gardent leurs lignes d'expédition.
Instabee et Budbee sont des marques déposées de leurs propriétaires respectifs. Ce plugin n'est affilié ni à Instabee ni à Budbee, et n'est pas approuvé par eux.