VibeFox Balikobot for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Compte Balikobot (pour les tarifs en temps réel et les points relais) : vous avez besoin d'un compte Balikobot avec accès à l'API. L'utilisateur et la clé de l'API se trouvent dans l'espace client de 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 relais 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

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_balikobot-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_balikobot.ocmod.zip. Installez uniquement 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_balikobot-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 copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

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

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page de réglages.

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

5. 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 retrait en point relais, activez Pickup point selection. 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_balikobot.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é.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Balikobot, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

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

À l'installation, l'extension crée une table pour les points relais des paiements et des commandes. La méthode reste désactivée tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Balikobot 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 Balikobot > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Après l'enregistrement, vous voyez Settings saved. Cached rates and pickup points were cleared. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Certaines erreurs bloquent l'enregistrement, et rien n'est enregistré : un Name vide ou trop long, 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 par des avertissements, et le reste des réglages est enregistré : une valeur qui n'est pas un nombre (ou qui est négative) n'est pas enregistrée et l'avertissement indique le champ ; les lignes invalides de Country prices sont supprimées et listées.

Les avertissements sur les réglages qui masqueraient la méthode, les tarifs en temps réel ou les points relais s'affichent en haut de la page : tarifs en temps réel ou points relais 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 secours, et boutique sans classe de poids avec l'unité kg (les poids des produits sont alors 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 Balikobot au paiement. Par défaut : désactivé.

Name : le nom de la méthode de livraison affiché aux clients. Par défaut : Balikobot. Obligatoire, 64 caractères maximum.

Sort Order : la position de la méthode dans la liste des méthodes de livraison. Un nombre entier.

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

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

API key : votre clé API Balikobot, depuis 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. Ne saisissez une nouvelle valeur que pour la modifier.

Carrier : le transporteur Balikobot utilisé pour les tarifs et les points relais : Č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 dans la devise par défaut de votre boutique)

Price source : la manière dont le prix est calculé.

Country prices : une liste de pays et de prix. Cliquez sur Add row pour ajouter une ligne et sur le bouton de suppression pour en supprimer une. Choisissez * All other countries pour tous les pays sans ligne propre. Décimales avec un point ou une virgule. Utilisé en mode fixe et comme secours de l'API. Un pays sans prix (et sans ligne *) ne reçoit aucun tarif fixe, donc la méthode lui est masquée.

Fixed price per: Order (par défaut) facture le prix une seule fois. Item (price x 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 est toujours pour le colis complet.

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 que le client ne paie jamais un prix erroné.

Conditions

Min weight (kg) : masque la méthode lorsque le panier est plus léger. 0 signifie aucune limite (par défaut). Les poids des produits sont convertis à partir de leur classe de poids OpenCart.

Max weight (kg) : masque la méthode lorsque le panier est plus lourd. Par défaut : 100. 0 signifie aucune limite. Un champ vide équivaut à 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 la méthode qu'à partir de ce sous-total du panier (après coupons, hors taxes). Laissez le champ vide pour l'afficher toujours.

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

Free shipping from : le sous-total du panier (après coupons, hors taxes) à partir duquel la livraison est gratuite. Aucune requête n'est alors envoyée à l'API. Utilisé uniquement lorsque Free shipping est activé.

Tax Class : la taxe de cette classe est ajoutée au prix de la livraison. Les prix Balikobot sont généralement hors TVA. Par défaut : --- None ---.

Disponibilité

En général, la méthode est proposée dans la zone géographique sélectionnée ici (All Zones signifie partout). Ignore geo zone la propose plutôt dans les pays de la liste.

Geo Zone : propose la méthode uniquement pour les adresses de cette zone géographique. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore geo zone : propose la méthode dans les pays ci-dessous, quelle que soit la zone géographique.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays. Utilisé uniquement avec Ignore geo zone.

Points relais

Pickup point selection : le client doit choisir un point relais. Utilisez-le pour les services avec 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 relais, par exemple 100% ou 400px. Par défaut : 100%.

Avancé

Debug log : enregistre les requêtes à l'API et les calculs de tarifs dans storage/logs/vfd_blkb_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées. Les identifiants et les adresses des clients ne sont jamais enregistrés. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est renommé vfd_blkb_debug.old.log.php et un nouveau journal est créé.

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

Remove data on uninstall : lorsque cette option est activée, la désinstallation de l'extension supprime les réglages, le journal et les points relais des paiements sans commande. Lorsqu'elle est désactivée (par défaut), les réglages sont conservés. Les points relais enregistrés dans les commandes sont toujours conservés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé de l'API n'est pas exportée.

Import : collez le 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 clé de l'API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le prix Balikobot. Si une Geo Zone est définie (et que Ignore geo zone est désactivé) et que l'adresse se trouve en dehors, Balikobot n'est pas proposé. Avec Ignore geo zone, c'est la liste Countries qui décide. 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 ensuite le poids du panier et le Minimum order amount. Le montant de la commande est le prix des produits à expédier, après la remise du coupon et avant taxes. 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, l'extension 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 lorsque l'adresse de livraison a 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 la boutique, arrondi à ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax Class sélectionnée.

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 échouée est mise en cache pendant 5 minutes, et le délai d'attente de l'API est de 12 secondes, afin 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 secours. Les détails sont envoyés au journal de débogage.

L'extension ne crée pas d'envois dans Balikobot, n'imprime pas d'étiquettes et ne réserve pas d'enlèvements : commandez l'envoi dans l'espace client Balikobot. Elle ne suit pas les colis et ne modifie pas les statuts des commandes. Un seul transporteur et un seul type de service sont utilisés pour toutes les destinations. Les points relais s'affichent sous forme de liste déroulante, sans carte.

Sur OpenCart 4, le client clique sur Choose dans le bloc de la méthode de livraison de la page de paiement, puis choisit Balikobot dans la fenêtre Shipping method options. La méthode fonctionne de la même façon que sur OpenCart 3 ; la liste des points relais est décrite dans Points relais.

Points relais

Lorsque Pickup point selection est activé, une liste de points relais apparaît sous la méthode Balikobot à l'étape Delivery Method du paiement OpenCart. 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 n'a pas de ville, le client voit Enter your city to see the pickup points. Pendant le chargement de la liste, il voit Loading pickup points.... La liste est mise en cache pendant 12 heures maximum.

Le choix est enregistré dès que le client sélectionne un point. Il est obligatoire : Continue à l'étape de livraison est refusé 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 Balikobot est injoignable à ce moment-là, un point déjà choisi est accepté. Si aucun point n'est trouvé, le client est invité à vérifier la ville et le code postal ou à choisir une autre méthode de livraison. Si les points ne peuvent pas être chargés, le client est invité à réessayer plus tard ou à choisir une autre méthode de livraison.

Sur OpenCart 4, le client clique sur Choose dans le bloc de la méthode de livraison de la page de paiement. La fenêtre Shipping method options affiche la liste des points relais sous la méthode Balikobot, avec les mêmes textes et vérifications. La liste est chargée à chaque ouverture de la fenêtre, car l'adresse peut changer sur la même page de paiement, et provient du cache lorsque c'est possible. Si le client clique sur Continue dans la fenêtre sans point valide, le message s'affiche en haut de la page de paiement et la fenêtre reste ouverte. OpenCart 4 conserve une seule commande pour le paiement et la met à jour à chaque confirmation ; le point relais de la commande est mis à jour avec elle.

Le point choisi est ajouté à la méthode de livraison de la commande sous la forme - Pickup point: suivi de son nom et de son adresse. Le client le voit sur les pages de commande de son compte et dans les e-mails de commande, et il est imprimé sur la facture.

Sur la page de commande de l'administration (Sales > Orders, View), le panneau Balikobot pickup point affiche le point, son identifiant Balikobot et le transporteur, dont vous avez besoin lors de la création de l'envoi dans Balikobot. Cliquez sur Change, choisissez un autre point proche de l'adresse de la commande et cliquez sur Save. Le texte de la méthode de livraison de la commande est aussi mis à jour, et vous voyez Pickup point updated. Modifier le point ne nécessite que l'autorisation de modification des commandes, et non l'accès aux réglages de l'extension. Si une commande n'a pas de point, le panneau affiche No pickup point was selected for this order. Le panneau fonctionne aussi lorsque Balikobot est désactivé : les commandes existantes conservent les données de leur point relais, et vous pouvez toujours modifier le point.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox provenant de vibefox.net. Le bloc de licence License — VibeFox Balikobot est le premier bloc de Extensions > Extensions > Shipping > VibeFox Balikobot > Edit, 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) et 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: opencart-shipping-balikobot 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 statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique indiquée dans 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, Balikobot n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, signalée par (unlicensed — visible to admins only), afin que vous puissiez 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, donc sans clé active la méthode est masquée pour tout le monde. Après avoir ouvert une fois la page Edit, 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. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou 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 le statut de 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 de l'extension. Vérifiez Geo Zone (ou Ignore geo zone et Countries), les limites de poids et le Minimum order amount. En mode fixe, vérifiez que le pays ou * All other countries a un prix. Vérifiez que les produits ont Requires Shipping sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et regardez le champ Log sur la page de l'extension. Il indique la raison : identifiants API manquants, pas encore de code postal, erreur Balikobot pour le transporteur et le service (par exemple « authorization failed: check the API user and API key »), ou prix dans une autre devise sans Exchange rate. Avec Live Balikobot rate, fixed price if the API fails, les clients obtiennent quand 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 par défaut 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 votre devise par défaut, définissez Exchange rate.

La TVA est-elle incluse ? Les prix Balikobot sont généralement hors TVA. Avec une Tax Class sélectionnée, OpenCart ajoute la taxe sur la livraison.

Aucun point relais 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 a une ville et un code postal. Consultez le journal pour voir l'erreur Balikobot.

Les tarifs ou les points relais semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs et les points relais mis en cache.

La page affiche « Warning: You do not have permission to modify VibeFox Balikobot! » : votre groupe d'utilisateurs administrateurs n'a peut-être que le droit de consultation des réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_balikobot (OpenCart 3) ou extension/vfd_balikobot/shipping/vfd_balikobot (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Balikobot peut être remplacée par le réglage vfd_blkb_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 Balikobot. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort Order, Tax Class et Geo Zone. Les tarifs et les points relais mis en cache sont toujours supprimés, et le panneau des points relais ainsi que la liste du paiement cessent de fonctionner. Si Remove data on uninstall est activé, les réglages, le journal et les points relais des paiements sans commande sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lorsque vous réinstallez l'extension. Les données des points relais enregistrées dans les commandes ne sont jamais supprimées, et le texte de la méthode de livraison des commandes existantes conserve le point relais.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Balikobot dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet téléversé.

Balikobot est une marque appartenant à son titulaire respectif. Cette extension n'est ni affiliée à Balikobot ni approuvée par Balikobot.