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

Compte Balikobot (pour les tarifs en temps réel et les points de retrait) : vous avez besoin d'un compte Balikobot avec accès à l'API. L'utilisateur API et la clé API se trouvent dans l'espace client Balikobot (client.balikobot.cz). Le support Balikobot (podpora@balikobot.cz) active l'API pour votre compte et vos transporteurs. Les tarifs en temps réel nécessitent un transporteur et un service pour lesquels Balikobot prend en charge « transportcosts ». Les points de retrait nécessitent un transporteur compatible avec « branchlocator » (par exemple Česká pošta, Zásilkovna, PPL, DPD, GLS). En cas de doute, interrogez le support Balikobot. Les prix fixes fonctionnent sans compte.

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 transférer le dossier vfd_balikobot dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Balikobot, ou cliquez sur Settings sous le nom du plugin 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 l'utilisateur et la clé API, choisissez le transporteur, le type de service, la source des prix et les prix par pays (voir Configuration). Pour les services avec retrait, activez Pickup point selection.

6. Ajoutez VibeFox Balikobot à une zone d'expédition (par exemple la Tchéquie) 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 Balikobot. Ils s'appliquent à toutes les zones d'expédition. Les avertissements concernant les réglages qui masqueraient la méthode, les tarifs en temps réel ou les points de retrait s'affichent en haut de la page. À chaque enregistrement des réglages, les tarifs et les points de retrait en cache sont effacés. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone): le nom de la méthode d'expédition affiché aux clients de cette zone. Laissez-le vide pour utiliser le Name global.

Général

Enable/Disable: active ou désactive l'expédition Balikobot dans toutes les zones à la fois.

Name: le nom de la méthode d'expédition affiché aux clients. Une zone peut le remplacer par son propre Title. Par défaut : Balikobot.

Tax status: Taxable signifie que WooCommerce ajoute la taxe sur les frais d'expédition au prix ; None signifie qu'il ne l'ajoute pas. Les prix Balikobot sont généralement hors TVA.

Compte API Balikobot (nécessaire pour les tarifs en temps réel et les points de retrait)

API user: votre utilisateur API Balikobot, issu de l'espace client.

API key: votre clé API Balikobot, issue de l'espace client.

Carrier: le transporteur Balikobot utilisé pour les tarifs et les points de retrait : Česká pošta (par défaut), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) ou Magyar Posta. Il doit être activé dans votre compte Balikobot.

Service type: le code de service Balikobot du transporteur. Par défaut : NP. Pour Česká pošta : NP = colis vers un bureau de poste, NB = colis vers Balíkovna, DR = livraison à domicile. Les codes des autres transporteurs figurent dans l'espace client Balikobot et dans la documentation de l'API.

Prix (tous les prix sont exprimés dans la devise de votre boutique)

Price source: mode de calcul du prix.

Country prices: un prix fixe par pays de destination (code à 2 lettres, par exemple CZ, SK). Utilisez * pour tous les autres pays. Décimales avec un point ou une virgule. Utilisé en mode fixe et comme solution de repli si l'API échoue. Un pays sans prix (et sans ligne *) ne reçoit aucun tarif fixe.

Fixed price per: Order facture le prix une seule fois. Item (price × quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'aux prix fixes. Un tarif Balikobot en temps réel couvre toujours le colis entier.

Exchange rate: la valeur de 1 unité de la devise du prix Balikobot (généralement CZK) dans la devise de votre boutique, par exemple 0.04. Utilisé uniquement lorsque Balikobot renvoie un prix dans une autre devise. Laissez le champ vide pour rejeter ces prix, afin qu'un client ne soit jamais facturé à un prix erroné.

Conditions

Min weight (kg): masque la méthode lorsque le panier est plus léger. 0 signifie sans limite. Les poids des produits sont convertis depuis l'unité de poids de votre boutique.

Max weight (kg): masque la méthode lorsque le panier est plus lourd. Par défaut : 100. 0 signifie sans limite.

Minimum order amount: affiche la méthode uniquement à partir de ce sous-total du panier (après remises, hors taxes). Laissez vide pour l'afficher en permanence.

Excluded shipping classes: masque la méthode si le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

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

Free shipping from: le sous-total du panier (après remises, hors taxes) à partir duquel la livraison est gratuite. Dans ce cas, aucune requête n'est envoyée à l'API.

Disponibilité sans zones d'expédition

Ignore shipping zones: propose la méthode dans les pays indiqués ci-dessous, même si elle n'est pas ajoutée à la zone correspondante.

Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.

Points de retrait

Pickup point selection: le client doit choisir un point de retrait. Utilisez cette option pour les services avec retrait, par exemple Česká pošta NP ou NB, ou Zásilkovna. Nécessite l'utilisateur et la clé API.

Selector width: la largeur CSS de la liste des points de retrait, par exemple 100% ou 400px. Par défaut : 100%.

Avancé

Debug log: consigne les requêtes API et les calculs de tarifs dans WooCommerce > Status > Logs, source « vfd-balikobot ». Les erreurs de l'API sont toujours consignées. Les identifiants et les adresses des clients ne sont jamais consignés.

Remove data on uninstall: lorsque l'option est active, la suppression du plugin efface ses réglages et ses méthodes de zone. La désactivation du plugin ne supprime jamais de données. Les points de retrait enregistrés dans les commandes sont conservés.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, le plugin vérifie le poids du panier, le Minimum order amount et les Excluded shipping classes. Si la livraison gratuite s'applique, le tarif est de 0 et aucune requête n'est envoyée à Balikobot.

En mode fixe, le prix est tiré de Country prices. Dans les modes en temps réel, le plugin envoie à Balikobot le transporteur, le type de service, le pays et le code postal de destination, ainsi que le poids du panier en kg. Un tarif en temps réel n'est demandé qu'après que le client a saisi un code postal. Un prix dans une autre devise est converti avec Exchange rate, ou rejeté si aucun taux n'est défini.

Les prix en temps réel sont mis en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle requête. Une requête en échec est mise en cache pendant 5 minutes, et le délai d'attente de l'API est de 12 secondes, pour que le paiement n'attende pas Balikobot à chaque actualisation. Les erreurs de l'API ne sont jamais affichées au client : la méthode est masquée, ou le prix fixe est utilisé en mode de repli. Les détails sont consignés dans le journal.

La méthode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

Le plugin ne crée pas d'envois dans Balikobot, n'imprime pas d'étiquettes et ne commande pas d'enlèvements : passez la commande d'envoi dans l'espace client Balikobot. Il ne suit pas les colis et ne met pas à jour les statuts de commande. Un seul transporteur et un seul type de service sont utilisés pour toutes les zones. Les points de retrait sont affichés sous forme de liste déroulante, sans carte.

Points de retrait

Lorsque Pickup point selection est activé, une liste de points de retrait apparaît sous l'option Balikobot au paiement, aussi bien sur le paiement classique que sur le bloc Paiement. La liste est chargée depuis le « branchlocator » de Balikobot pour le pays, la ville et le code postal du client. Tant que la ville et le code postal ne sont pas saisis, le client voit Enter your city and postcode to see the pickup points. La liste est mise en cache pendant 12 heures.

Le choix est obligatoire : le client voit Please select a pickup point. Le serveur vérifie également que le point choisi appartient à l'adresse de livraison. Après un changement d'adresse, le client est invité à choisir à nouveau un point de retrait. Si les points ne peuvent pas être chargés, le client est invité à réessayer plus tard ou à choisir une autre méthode d'expédition.

Le point de retrait choisi est enregistré dans la commande. Sur l'écran de commande de l'administration, il apparaît sous l'adresse de livraison, sous le libellé Balikobot pickup point, avec l'identifiant de l'agence Balikobot et le transporteur, dont vous avez besoin pour créer l'envoi dans Balikobot. Cliquez sur Change pour choisir un autre point proche de l'adresse de la commande. Le client voit le point sous le libellé Pickup point sur la page de commande et dans les e-mails de commande (HTML et texte brut). Les commandes existantes conservent leurs données de point de retrait.

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 Balikobot. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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, Balikobot 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 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. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Balikobot 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é). Lisez les avertissements en haut de la page des réglages. Vérifiez les limites de poids, Minimum order amount et Excluded shipping classes. En mode fixe, vérifiez que le pays ou * a un prix.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs (source « vfd-balikobot »). Le journal indique la raison : identifiants API manquants, code postal non encore saisi, erreur Balikobot pour le transporteur et le service, ou prix dans une autre devise sans Exchange rate. Avec Live Balikobot rate, fixed price if the API fails, les clients reçoivent tout de même le prix fixe pendant que vous corrigez le problème.

Les prix sont dans la mauvaise devise : les prix fixes sont dans la devise de votre boutique. Balikobot renvoie les prix en temps réel dans la devise de votre contrat Balikobot (généralement CZK). Si elle diffère de la devise de votre boutique, définissez Exchange rate.

La TVA est-elle incluse ? Les prix Balikobot sont généralement hors TVA. Avec Tax status réglé sur Taxable, WooCommerce ajoute la taxe sur les frais d'expédition.

Aucun point de retrait dans la liste : vérifiez que l'utilisateur et la clé API sont renseignés, que le transporteur prend en charge « branchlocator » et que le client a saisi une ville et un code postal. Consultez le journal pour l'erreur Balikobot.

Les tarifs ou les points de retrait semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs et les points de retrait en cache.

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, puis 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 état connu.

Désinstallation

La désactivation du plugin conserve tous les réglages et n'efface que les caches. 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, ainsi que les tarifs et les points de retrait en cache, 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 réinstallation ultérieure. Les données de points de retrait enregistrées dans les commandes ne sont jamais supprimées.

Balikobot est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Balikobot ni approuvée par Balikobot.