VibeFox Balikobot 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 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 de l'API et la clé de l'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 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 Balikobot plus tard dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez l'utilisateur et la clé de l'API, choisissez le transporteur et le type de service, la source du prix et les prix par pays (voir Configuration). Pour les services avec points de retrait, activez Pickup point selection. Cliquez sur Save.

À l'installation, le module crée le transporteur Balikobot avec le texte de délai de livraison Delivery by Balikobot. Le transporteur est affecté aux zones de Tchéquie, de Slovaquie et de Hongrie ainsi qu'à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Balikobot > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Après l'enregistrement, vous voyez Settings saved. Cached rates and pickup points were cleared. Des avertissements concernant les réglages qui masqueraient le transporteur, les tarifs en temps réel ou les points de retrait s'affichent en haut de la page : tarifs en temps réel ou points de retrait sans utilisateur ou clé de l'API, devise de la boutique autre que CZK sans Exchange rate, Country prices vide avec des prix fixes ou le mode de repli, unité de poids de la boutique que le module ne connaît pas (les poids sont alors lus en kg ; utilisez kg, g, lb ou oz) et transporteur supprimé. Une valeur qui n'est pas un nombre n'est pas enregistrée, et un avertissement indique le nom du champ.

General

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

Name : le nom du mode d'expédition affiché aux clients (le nom du transporteur). Par défaut : Balikobot. Obligatoire, 64 caractères maximum.

Tax status : None, ou Taxable avec l'une de vos règles de taxe. Avec une règle de taxe, sa taxe est ajoutée au prix de l'expédition. Le choix est enregistré sur le transporteur. Les prix Balikobot sont généralement hors TVA. Par défaut : None.

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. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Clear the API user to remove the saved key. Saisissez une nouvelle valeur uniquement pour la modifier.

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 à 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 par défaut de votre boutique)

Price source : mode de calcul du prix.

Country prices : un tableau de codes pays à 2 lettres (par exemple CZ, SK) et de prix. Cliquez sur Add row pour ajouter un pays et sur l'icône de corbeille pour en supprimer un. Utilisez * comme code pays pour tous les autres pays. Décimales avec un point ou une virgule. Utilisé en mode fixe et comme repli de l'API. Un pays sans prix (et sans ligne *) n'a pas de tarif fixe. Les lignes non valides sont supprimées à l'enregistrement, et un avertissement les liste.

Fixed price per : Order facture le prix une seule fois. Item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne concerne que les prix fixes. Un tarif Balikobot en temps réel s'applique toujours à l'ensemble du colis.

Exchange rate : la valeur de 1 unité de la devise du prix Balikobot (généralement CZK) dans la devise par défaut 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 paie jamais un prix erroné.

Conditions

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

Max weight (kg) : masque le transporteur lorsque le panier est plus lourd. Par défaut : 100. 0 signifie aucune limite. Un champ vide correspond à 100 kg. Si Min weight (kg) est supérieur au maximum, un avertissement s'affiche et les poids précédents sont conservés.

Minimum order amount : n'affiche le transporteur qu'à partir de ce sous-total du panier (après remises, hors taxes). Laissez le champ vide pour l'afficher en permanence.

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

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

Disponibilité sans zones d'expédition

En général, le transporteur est proposé dans ses zones, dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur dans les pays indiqués ci-dessous, même s'il n'est pas lié à leur zone. Le module lie le transporteur à toutes les zones, y compris celles que vous créerez plus tard. Lorsque vous désactivez cette option, les zones ajoutées de cette façon sont supprimées. Vos propres zones restent en place.

Countries : les pays de destination pour ce mode. Laissez le champ 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 points de retrait, par exemple Česká pošta NP ou NB, ou Zásilkovna. Nécessite l'utilisateur et la clé de l'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 : enregistre les requêtes API et les calculs de tarifs dans logs/vfd_blkb_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours consignées. Les identifiants et les adresses des clients ne sont jamais consignés. Désactivez le journal lorsque vous avez terminé.

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

Remove data on uninstall : lorsque l'option est activée, la désinstallation du module supprime ses réglages et le transporteur. Désinstaller sans cette option ne supprime jamais de données. Les points de retrait enregistrés dans les commandes sont conservés.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix Balikobot. 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 d'abord les pays (avec Ignore shipping zones), le poids du panier et le Minimum order amount. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Balikobot.

En mode fixe, le prix est pris dans Country prices. Dans les modes en temps réel, le module 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é que si l'adresse de livraison comporte un code postal. Un prix dans une autre devise est converti avec Exchange rate, ou rejeté si aucun taux n'est défini. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.

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 : le transporteur est masqué, ou le prix fixe est utilisé en mode de repli. Les détails sont envoyés au journal de débogage.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne crée pas d'envois dans Balikobot, n'imprime pas d'étiquettes et ne commande pas d'enlèvements : commandez l'envoi dans l'espace client Balikobot. Il ne suit pas les colis et ne met pas à jour les statuts des commandes. 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 le transporteur Balikobot à l'étape de livraison. La liste est chargée depuis le « branchlocator » de Balikobot pour le pays, la ville et le code postal de l'adresse de livraison. Tant que l'adresse ne comporte pas de ville, le client voit Enter your city to see the pickup points. La liste est mise en cache pendant 12 heures.

Le choix est enregistré dans le panier dès que le client sélectionne un point. Il est obligatoire : Continue à l'étape de livraison et Place order sont bloqués avec Please select a pickup point. Le serveur vérifie également que le point choisi appartient à l'adresse de livraison. Sinon, le client voit The selected pickup point is not available for your shipping address. Please choose a pickup point again. Si aucun point n'est trouvé, le client est invité à vérifier la ville et le code postal ou à choisir un autre mode d'expédition. Si les points ne peuvent pas être chargés, le client est invité à réessayer plus tard ou à choisir un autre mode d'expédition.

Le point de retrait choisi est enregistré dans la commande. Sur la page de commande du back office, il apparaît dans le bloc Balikobot pickup point, avec l'identifiant de l'agence Balikobot et le transporteur, dont vous avez besoin lors de la création de l'envoi dans Balikobot. Cliquez sur Change pour choisir un autre point proche de l'adresse de la commande, puis cliquez sur Save. Modifier le point nécessite uniquement le droit de modifier les commandes, pas l'accès aux pages Modules. Si une commande n'a pas de point, le bloc affiche No pickup point was selected for this order.

Le client voit le point sous la forme Pickup point : sur la page de confirmation de commande et dans le détail de la commande. Dans l'e-mail de confirmation de commande et dans l'e-mail de nouvelle commande pour la boutique (module Mail alerts), il est ajouté après le nom du transporteur. Les commandes existantes conservent leurs données de point de retrait.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Balikobot est le premier bloc de Modules > Module Manager > VibeFox Balikobot > 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-balikobot 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. Retirer 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 Balikobot n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La vitrine PrestaShop ignore 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 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant que vous travaillez 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

Balikobot n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Lisez les avertissements en haut de la page du module. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones et vérifiez Countries. Contrôlez les limites de poids et le Minimum order amount. En mode fixe, vérifiez que le pays ou * a un prix. Des produits peuvent aussi être limités à certains transporteurs sur la page du produit.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Il indique la cause : identifiants de l'API manquants, pas encore de code postal, erreur Balikobot pour le transporteur et le service (par exemple authorization failed, vérifiez l'utilisateur et la clé de l'API), ou prix dans une autre devise sans Exchange rate. Avec Live Balikobot rate, fixed price if the API fails, les clients continuent de voir le prix fixe pendant que vous corrigez le problème.

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

La TVA est-elle incluse : les prix Balikobot sont généralement hors TVA. Lorsque Tax status est défini sur une règle de taxe, PrestaShop ajoute la taxe sur l'expédition.

Aucun point de retrait dans la liste : vérifiez que l'utilisateur et la clé de l'API sont renseignés, que le transporteur prend en charge « branchlocator » et que l'adresse de livraison comporte 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 : cliquez sur Save sur la page du module. Cela vide les tarifs et les points de retrait en cache.

La page indique que le transporteur Balikobot 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 : le module dispose de ses propres hooks pour modifier l'adresse de l'API (actionVfdBlkbApiUrl), le paquet « transportcosts » (actionVfdBlkbTransportcostsPackage) et le nombre de points de retrait (actionVfdBlkbPickupMaxResults, par défaut 30).

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Balikobot et choisissez Uninstall. La clé de licence, le statut de la licence, les tarifs et les 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 sans commande. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module (ou le réinitialiser) redonne au transporteur conservé son statut d'avant la désinstallation : activé reste activé, désactivé reste désactivé. Les données de point de retrait enregistrées dans les commandes ne sont jamais supprimées.

Balikobot est une marque de son propriétaire respectif. Ce module n'est ni affilié à Balikobot ni approuvé par Balikobot.