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

Identifiants de l'API Budbee (uniquement pour le choix de la boîte à colis) : une clé d'API et un secret d'API. Instabee les délivre aux marchands ayant un contrat de livraison. Adressez-vous à votre contact Instabee ou utilisez le portail marchand d'Instabee. La documentation de l'API se trouve sur developer.budbee.com. Sans identifiants, le mode 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

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_instabee-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_instabee.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_instabee-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 Instabee 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. Renseignez la section Prices et, pour le sélecteur de boîte à colis, votre API key et votre API secret Budbee (voir Configuration). 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_instabee.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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é de lui.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Instabee, 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 de réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'avez pas activé Enable/Disable et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Instabee que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Instabee > Edit. Les sections sont listées à gauche. Un bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi la liste des boîtes en cache et la dernière erreur d'API. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Des avertissements au-dessus des réglages vous indiquent lorsque un seul des identifiants d'API est saisi, lorsqu'il n'y a aucun identifiant d'API, lorsqu'il n'y a ni tarif par pays ni coût de repli, lorsque la dernière requête vers l'API Budbee a échoué (avec la date, l'heure et la raison), et lorsque la boutique n'a pas de classe de poids en kg et que l'unité de la classe de poids par défaut n'est pas reconnue (les poids sont alors traités comme des kg ; ajoutez une classe de poids kg dans System > Localisation > Weight Classes).

Si Method name est vide ou trop long, si Min weight (kg) est supérieur à Max weight (kg), si Sort order n'est pas un nombre entier, ou si la classe de taxe ou la zone géographique n'existe pas, rien n'est enregistré et une erreur s'affiche.

Général

Enable/Disable : affiche ou masque Instabee au paiement. Par défaut : off.

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

Tax class : None (the prices are final) (par défaut) signifie que les tarifs ci-dessous sont définitifs. Une classe de taxe ajoute la taxe de livraison de cette classe aux tarifs ci-dessous.

Sort order : la position d'Instabee parmi les modes de livraison au paiement. Un nombre entier.

Sélecteur de boîte à colis (API Budbee)

Avec des identifiants d'API, le client choisit au paiement une boîte à colis près 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é d'API Budbee (le nom d'utilisateur HTTP Basic).

API secret : votre secret d'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. Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer les identifiants enregistrés, cochez Remove the saved API key and secret et 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-la uniquement avec des identifiants de test fournis par Instabee. Les boutiques en production la laissent désactivée (api.budbee.com). Par défaut : off.

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. La virgule et le point décimaux sont tous deux acceptés (49,90 = 49.90). Le tarif est affiché au client dans sa devise.

Calculation type : la manière dont le tarif 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 le bouton × 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. À l'enregistrement, un tarif qui n'est pas un nombre supérieur ou égal à 0 est effacé et une ligne dont le pays est inconnu est supprimée ; un avertissement les énumère. Les poids des produits sont convertis de leur classe de poids OpenCart en kg.

Fallback cost : utilisé lorsque ni la ligne du pays de destination ni la ligne * ne fournissent de tarif. Laissez-le vide pour masquer le mode dans ces pays.

Conditions

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

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

Minimum order amount : affiche le mode seulement lorsque le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint ce montant. Laissez-le vide pour l'afficher en permanence.

Free shipping from : le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel le mode est gratuit. Laissez-le vide pour qu'il ne soit jamais gratuit.

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

Disponibilité

Geo zone : proposer Instabee uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie partout. La zone géographique n'est pas vérifiée lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : lorsque l'option est activée, la Geo zone n'est pas vérifiée et le mode est proposé pour les pays ci-dessous. Lorsqu'elle est désactivée (par défaut), seule la Geo zone s'applique.

Countries : les pays de destination pour ce mode. Laissez-le vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit des messages de débogage dans storage/logs/vfd_ibee_debug.log.php (sous OpenCart 4, system/storage/logs/vfd_ibee_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs d'API et les commandes passées sans boîte alors que l'API fonctionnait sont toujours journalisées, même lorsque cette option est désactivée. Les clés d'API et les données clients ne sont jamais journalisées. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_ibee_debug.old.log.php et un nouveau journal est démarré.

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 de l'extension supprime les réglages, les listes de boîtes en cache, le journal et les boîtes des paiements non terminés. Lorsqu'elle est désactivée (par défaut), les réglages sont conservés pour une réinstallation. Les boîtes à colis enregistrées sur les commandes sont toujours conservées.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé et le secret d'API ne sont pas exportés.

Import : collez un 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é et le secret d'API enregistrés sont conservés.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif d'Instabee. Lorsque Ignore shipping zones est activé, Instabee n'est proposé que si le pays est autorisé (la zone géographique n'est pas vérifiée). Sinon, si une Geo zone est définie et que l'adresse se trouve en dehors, Instabee n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le montant de la commande correspond au prix des produits nécessitant une livraison, après remise du coupon et avant taxes. L'extension vérifie le poids du panier et le montant minimum de commande. Si le sous-total atteint Free shipping from, le tarif est de 0. Sinon, le tarif est pris dans la ligne Country prices du pays de destination, dans la ligne * ou dans le Fallback cost. S'il n'y a pas de tarif, le mode est masqué. Le tarif est calculé dans votre devise par défaut, arrondi selon ses décimales, puis affiché dans la devise du client avec la taxe de la Tax class sélectionnée.

Lorsque le client sélectionne Instabee à l'étape du mode de livraison et que les identifiants d'API sont renseignés, un bloc Parcel box apparaît sous le mode 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 (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 mode est proposé sans boîte.

Une boîte à colis est obligatoire. La boîte choisie n'est enregistrée pour le paiement que si elle figure dans la liste Budbee de ce code postal. Un code postal saisi sans cliquer sur Search n'est pas utilisé. Lorsque le client clique sur Continue à l'étape du mode de livraison, l'extension vérifie à nouveau la boîte sur le serveur. 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. Si le client modifie le pays de livraison ou le code postal de l'adresse, le choix précédent est abandonné.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Instabee dans la fenêtre Shipping method options. Le bloc Parcel box apparaît dans cette fenêtre, sous l'option Instabee, et fonctionne de la même façon. Le bouton Continue de la fenêtre ne poursuit pas sans boîte de la liste, avec les mêmes messages.

L'extension envoie à Budbee uniquement 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 en échec pendant 5 minutes, afin qu'une API lente ou défaillante 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 mode 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 lorsque vous réservez 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.

L'extension 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 de suivi ni 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. Sous OpenCart 4, la boutique conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau ; la boîte de la commande est mise à jour avec elle. Si le client fait passer cette commande à un autre mode de livraison, sa boîte est supprimée. La boîte apparaît aux endroits suivants :

Mode de livraison de la commande : la boîte est ajoutée au nom du mode, par exemple Instabee parcel box: (le nom du mode) suivi du nom et de l'adresse de la boîte. Ce texte apparaît sur les pages de commande de l'administration et du compte client, dans les e-mails de commande et sur la facture.

Page de commande de l'administration (Sales > Orders) : un panneau Instabee parcel box avec le nom de la boîte, son adresse et son 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, le panneau indique Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. Le panneau est en lecture seule et s'affiche même lorsque le mode est désactivé. Sous OpenCart 4, il s'affiche au-dessus de History.

E-mail de nouvelle commande envoyé à la boutique : le nom de la boîte avec son identifiant, ou Instabee parcel box: not chosen (Budbee API unavailable at checkout).

Clé de licence

L'extension 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 Extensions > Extensions > Shipping > VibeFox Instabee > 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 valable 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: opencart-shipping-instabee et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs 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 dans la configuration d'OpenCart. 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 mode de livraison Instabee n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sous OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode est masqué 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 la licence.

Dépannage

Instabee n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo zone ou, lorsque Ignore shipping zones est activé, que le pays est autorisé dans Countries. Vérifiez que le pays a un tarif, ou qu'il existe une ligne * ou un Fallback cost. Vérifiez les limites de poids et Minimum order amount, ainsi que la valeur Yes de Requires Shipping pour les produits. Un avertissement au-dessus des réglages indique lorsqu'aucun tarif n'est configuré. Activez 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 d'API s'affiche au-dessus des réglages. Les détails figurent dans le champ Log de la page de l'extension. Activez Debug log pour plus de détails.

HTTP 401 ou 403 dans le journal : Budbee a refusé la clé ou le secret d'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 continuer depuis l'étape du mode 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 de l'extension. Cela vide les listes de boîtes en cache.

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Instabee. 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 listes de boîtes en cache sont toujours supprimées. Si Remove data on uninstall est activé, les réglages, le journal et les boîtes choisies lors de paiements qui n'ont jamais abouti à une commande sont également supprimés. Si l'option est désactivée, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les boîtes à colis enregistrées sur les commandes sont toujours conservées, et les commandes existantes gardent leur mode de livraison et leur coût.

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

Instabee et Budbee sont des marques de leurs propriétaires respectifs. Cette extension n'est ni affiliée à Instabee ou Budbee, ni approuvée par eux.