VibeFox The Courier Guy for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Clé d'API ShipLogic (pour les tarifs en temps réel et les lockers) : The Courier Guy fonctionne sur la plateforme ShipLogic. Créez une clé d'API dans votre portail coursier The Courier Guy, sous Settings > API Keys (compte professionnel). Sans cette clé, seule la grille tarifaire est utilisée et l'option locker n'est pas proposée.

Expédition vers l'Afrique du Sud : les tarifs en temps réel et les lockers ne concernent que les adresses sud-africaines. L'Afrique du Sud doit être un pays activé de la boutique (System > Localisation > Countries), et le tarif de livraison en temps réel nécessite les provinces sud-africaines (zones), qu'OpenCart 3 contient déjà.

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_the_courier_guy-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_the_courier_guy.ocmod.zip. N'installez que 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_the_courier_guy-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas besoin de rafraîchir Extensions > Modifications. Au lieu de l'installateur, vous pouvez copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

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

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

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

5. Activez Courier to the door et/ou TCG locker, puis saisissez la API key ShipLogic. Pour les tarifs en temps réel, renseignez l'adresse d'expédition (rue, ville, province, code postal) et, si la devise de votre boutique n'est pas le ZAR, le ZAR conversion rate.

6. Renseignez la grille tarifaire et/ou un coût de repli, puis cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_the_courier_guy.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é de celui-ci.

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

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

Après l'installation, les deux options restent désactivées tant que vous n'en activez pas une et n'enregistrez pas. L'extension est active tant qu'au moins l'une des deux options est activée. Si vous réinstallez l'extension après une désinstallation, les réglages conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide les tarifs et lockers en cache ainsi que la dernière erreur ShipLogic. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Si un nom d'option, la classe de taxe, l'ordre de tri ou la zone géographique n'est pas valide, rien n'est enregistré et la page indique la raison, par exemple Enter a valid option name (1-64 characters, without < > ; = # { }). Un nombre non valide (par exemple négatif) n'est pas enregistré : la page signale le champ et conserve l'ancienne valeur, le reste est enregistré. Tant qu'au moins une option est activée, des avertissements en haut de la page indiquent si l'Afrique du Sud n'est pas un pays activé, si la clé d'API manque, si le taux de conversion ZAR ou l'adresse d'expédition manque, s'il n'y a ni grille tarifaire ni coût de repli, si l'Afrique du Sud n'a aucune zone (province), ou si la dernière requête ShipLogic a échoué (avec sa date et son erreur). Un avertissement apparaît aussi si la boutique n'a pas d'unité de poids en kg ni d'unité de longueur en cm.

Général

Chaque type de livraison est une option distincte au paiement.

Courier to the door : propose la livraison par coursier The Courier Guy à l'adresse du client. Par défaut : désactivé.

Courier option name : le nom de l'option coursier au paiement. Par défaut : The Courier Guy. Obligatoire, 64 caractères maximum, sans < > ; = # { }.

TCG locker : le client choisit un locker au paiement. Elle n'est proposée que pour les adresses sud-africaines et uniquement avec la clé d'API ShipLogic. Par défaut : désactivé.

Locker option name : le nom de l'option locker au paiement. Par défaut : The Courier Guy locker. Mêmes règles que le nom du coursier.

Tax status : la classe de taxe des deux options. Avec une classe de taxe, les tarifs en temps réel sont pris hors TVA et OpenCart ajoute la taxe de la classe. None (live rates including VAT) (par défaut) : les tarifs en temps réel sont pris TVA incluse.

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

API ShipLogic

API key : votre clé d'API ShipLogic provenant du portail The Courier Guy. Elle n'est jamais affichée aux clients ni écrite dans le journal. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur seulement pour la modifier. Cochez Remove the saved API key et enregistrez pour la supprimer.

Account ID : facultatif. L'identifiant numérique du compte ShipLogic, uniquement si votre clé donne accès à plusieurs comptes. Une valeur qui n'est pas un nombre n'est pas enregistrée.

Tarifs en temps réel (pour les adresses sud-africaines ; si aucun tarif en temps réel n'est disponible, la grille tarifaire est utilisée)

Le tarif en temps réel est le service ShipLogic le moins cher de votre adresse d'expédition jusqu'à l'adresse du client (coursier) ou jusqu'au locker le plus proche de la ville du client (locker). Il nécessite la clé d'API, l'adresse d'expédition et, pour les boutiques qui ne sont pas en rands, un taux de conversion.

Price source : l'origine du prix.

ZAR conversion rate : ShipLogic cote en rands sud-africains (ZAR). Si la devise par défaut de votre boutique n'est pas le ZAR, indiquez la valeur de 1 ZAR dans votre devise, par exemple 0.05. Elle doit être supérieure à 0. Sans elle, les tarifs en temps réel ne sont pas utilisés et c'est la grille tarifaire qui s'applique. Si la devise de votre boutique est le ZAR, laissez ce champ vide. Le taux n'est pas mis à jour automatiquement.

Adresse d'expédition (où The Courier Guy récupère les colis, en Afrique du Sud)

L'adresse de la boutique dans OpenCart est un texte libre : l'adresse d'expédition se saisit donc ici. La rue, la ville, la province et le code postal sont nécessaires pour les tarifs en temps réel.

Sender company : le nom de votre entreprise.

Sender street address : par exemple 12 My Road.

Sender suburb : le quartier de l'adresse d'expédition.

Sender city : la ville de l'adresse d'expédition.

Sender province : choisissez l'une des 9 provinces sud-africaines dans la liste.

Sender postal code : le code postal de l'adresse d'expédition.

Grille tarifaire (vos propres prix dans la devise par défaut de la boutique, hors taxes : utilisée avec Price table only, hors Afrique du Sud et chaque fois qu'aucun tarif en temps réel n'est disponible ; une virgule ou un point décimal est accepté)

Calculation type : s'applique uniquement à la grille tarifaire. Un tarif en temps réel concerne toujours la commande entière.

Prices by weight : un tableau de pays avec une colonne Price et les tranches de poids XS (jusqu'à 1 kg), S (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (plus de 5 kg). Cliquez sur Add row pour ajouter une ligne (une nouvelle ligne commence par l'Afrique du Sud) et sur le bouton de suppression pour en retirer une. Une tranche vide ou égale à 0 utilise la colonne Price. Un prix de 0 signifie livraison gratuite. La ligne * Any country s'applique aux pays sans ligne propre et à une ligne de pays sans aucun prix. Un prix qui n'est pas un nombre est effacé, et la page le signale.

Fallback cost : utilisé lorsqu'il n'existe ni tarif en temps réel ni prix dans la grille. Laissez ce champ vide pour masquer les options dans ce cas.

Conditions (les deux options)

Min weight (kg) : masque les options en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Max weight (kg) : masque les options au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite, vide signifie 30 kg. Si Min weight (kg) est supérieur à Max weight (kg), la page affiche un avertissement et les deux limites conservent leurs valeurs précédentes.

Minimum order amount : n'affiche les options qu'à partir de ce sous-total de panier (produits nécessitant une livraison, hors taxes, après remises). Laissez vide pour toujours les afficher.

Free shipping from : le sous-total du panier à partir duquel la livraison est gratuite. Laissez vide pour ne jamais proposer la livraison gratuite. Lorsque le sous-total l'atteint, les options s'affichent avec un prix de 0 et aucune requête n'est envoyée à ShipLogic pour le tarif.

Disponibilité

Geo zone : propose les options uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie toutes les adresses. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : pour le type de livraison ci-dessous, la zone géographique n'est pas vérifiée. L'option est proposée dans les pays indiqués ci-dessous.

Delivery type without zones : Courier to the door (par défaut) ou TCG locker (customer chooses a locker). Utilisé uniquement avec Ignore shipping zones. L'autre type reste soumis à Geo zone.

Countries : les pays de destination pour ce mode. Utilisé uniquement avec Ignore shipping zones. Laissez vide pour autoriser tous les pays. Les lockers ne sont proposés qu'en Afrique du Sud.

Avancé

Debug log : écrit les messages de débogage dans storage/logs/vfd_tcgr_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. La clé d'API et les données clients ne sont jamais journalisées. Lorsque le fichier atteint 5 Mo, 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 : lorsqu'elle est activée, la désinstallation de l'extension supprime les réglages, le journal et les choix de locker des paiements sans commande. Les tarifs et lockers en cache sont toujours supprimés. Les lockers et les références de suivi enregistrés sur les commandes sont toujours conservés.

Import / Export

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

Import : collez le JSON précédemment exporté 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é d'API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix de chaque option. L'option doit satisfaire la Geo zone (ou, avec Ignore shipping zones, la liste des pays). Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite les conditions : poids du panier et montant minimum de la commande. Le montant de la commande est le prix des produits nécessitant une livraison, avant taxes et après la remise du coupon. Si la livraison gratuite s'applique, le prix est de 0.

Courier to the door : l'extension demande à ShipLogic le service le moins cher de votre adresse d'expédition jusqu'à l'adresse du client. L'adresse doit comporter une rue, une ville, une province et un code postal. En attendant, la grille tarifaire est utilisée.

TCG locker : le tarif en temps réel est le service le moins cher de porte à locker jusqu'au locker le plus proche de la ville du client. Il n'est pas recalculé pour le locker choisi par le client. L'option locker n'apparaît que pour les adresses sud-africaines et uniquement avec la clé d'API.

La commande entière est cotée comme un seul colis : le poids total, la plus grande longueur et la plus grande largeur, et les hauteurs empilées. Les produits sans dimensions comptent comme des cubes de 10 cm. Les poids et dimensions sont convertis à partir des classes de poids et de longueur des produits. Le montant en rands est converti dans votre devise par défaut, arrondi à ses décimales, puis affiché au client dans sa devise avec la taxe de la classe de taxe sélectionnée.

Les requêtes vers ShipLogic expirent au bout de 12 secondes. Les tarifs sont mis en cache pendant 1 heure, les lockers pendant 6 heures et les échecs pendant 10 minutes, afin qu'une API lente ne ralentisse pas chaque actualisation du paiement. S'il n'y a pas de tarif en temps réel, le prix provient de la grille, puis de Fallback cost. Si aucune de ces sources ne s'applique, l'option est masquée. Les erreurs d'API ne sont jamais affichées au client.

L'extension n'enregistre aucun envoi, ne crée ni lettres de transport ni étiquettes, et ne met pas à jour le suivi automatiquement. Il n'existe pas de carte des lockers : ils se choisissent dans une liste. Les tarifs en temps réel et les lockers ne concernent que l'Afrique du Sud. Les autres pays utilisent la grille tarifaire. Un seul tarif par option (le niveau de service le moins cher) est affiché, sans choix de niveaux de service, d'assurance ou d'options supplémentaires au paiement.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison au paiement et choisit l'option coursier ou locker dans la fenêtre Shipping method options. La méthode fonctionne de la même façon que sous OpenCart 3.

Points de retrait

Lorsque le client choisit l'option locker à l'étape du mode de livraison, un sélecteur de lockers apparaît dessous : un champ de recherche (par défaut la ville de l'adresse de livraison) et une liste de lockers avec leur nom, leur adresse et leurs horaires. Le client peut saisir une autre ville, un quartier ou un code postal et cliquer sur Search. Un locker doit être choisi avant de continuer ; sinon l'étape affiche Please choose a The Courier Guy locker.

Le locker est vérifié sur le serveur par rapport à la liste de ShipLogic lorsque le client continue, puis de nouveau lors de la validation de la commande. Son nom et son fournisseur proviennent de ShipLogic, jamais du navigateur. Le choix dépend du pays et de la ville ou du code postal de l'adresse : si l'adresse de livraison change, le client doit choisir à nouveau.

Si ShipLogic est injoignable, le sélecteur affiche Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. La commande peut alors être passée sans locker. Elle est signalée sur la page de commande de l'administration : Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Sous OpenCart 4, le sélecteur de lockers apparaît dans la fenêtre Shipping method options, sous l'option locker, et il est rechargé à chaque ouverture de la fenêtre, car l'adresse peut changer au paiement en une page. Le bouton Continue de la fenêtre ne passe pas à l'étape suivante sans locker choisi dans la liste, avec le même message, et un ShipLogic indisponible ne bloque pas non plus la commande. OpenCart 4 conserve une commande pour le paiement et la met à jour à chaque fois que le client confirme à nouveau, et le locker de la commande est mis à jour avec elle.

Commandes

Le locker choisi est ajouté au mode de livraison de la commande, par exemple « The Courier Guy locker : nom — adresse ». Ce texte apparaît dans Sales > Orders, sur la page de commande du client, sur la facture et dans les e-mails de commande.

La page de commande dans Sales > Orders comporte un panneau The Courier Guy au-dessus de l'historique, pour chaque commande expédiée avec The Courier Guy. Pour une commande avec locker, il affiche le nom, l'identifiant et le fournisseur du locker, avec not verified (ShipLogic was unavailable at checkout) si le locker n'a pas pu être vérifié, ou le message Not chosen si ShipLogic était indisponible. Le panneau s'affiche même lorsque l'extension est désactivée.

The Courier Guy tracking reference : enregistrez le colis dans votre portail The Courier Guy, saisissez sa référence dans ce champ du panneau et cliquez sur Save. Videz le champ et enregistrez pour la supprimer. Les utilisateurs administrateurs sans l'autorisation de modifier les commandes voient la référence en lecture seule. Le client voit la référence sur la page de commande de son compte (clients inscrits) et dans les e-mails d'état de la commande lorsque vous le prévenez. L'e-mail de nouvelle commande ne contient pas de référence, car elle est saisie plus tard.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox The Courier Guy est le premier bloc de Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit, au-dessus des réglages. Collez 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-the-courier-guy 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 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, aucune des deux options The Courier Guy (livraison par coursier à domicile ou TCG locker) n'est affichée aux clients au paiement, et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours les options dans la boutique, marquées (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 les options sont masquées 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 à l'ouverture du Dashboard de l'administration ou de 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

The Courier Guy does not appear at checkout : vérifiez que la licence est active et que l'option est activée (Courier to the door ou TCG locker). Vérifiez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et Minimum order amount. Vérifiez que la grille ou Fallback cost comporte un prix. Vérifiez que les produits ont Requires Shipping réglé sur Yes. L'option locker n'apparaît que pour les adresses sud-africaines et avec la clé d'API.

Customers see no locker list : les lockers nécessitent la clé d'API, TCG locker activé et une adresse de livraison sud-africaine. La page des réglages affiche la dernière erreur ShipLogic, le cas échéant, par exemple une clé refusée.

The price is always the table price : consultez les avertissements de la page des réglages. Un tarif en temps réel nécessite la clé d'API, l'adresse d'expédition complète et, pour les boutiques qui ne sont pas en rands, le taux de conversion ZAR. Pour la livraison par coursier, l'adresse du client doit comporter une rue, une ville, une province (zone) et un code postal. Pour les lockers, ShipLogic doit trouver un locker près de la ville du client. Activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension.

ShipLogic is down : le prix de la grille ou le prix de repli est affiché. Les commandes avec locker peuvent être passées sans locker et sont signalées sur la commande.

Rates look outdated after a change : cliquez sur Save sur la page de l'extension. Cela vide les tarifs et lockers en cache.

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!" : 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_the_courier_guy (OpenCart 3) ou extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy (OpenCart 4) dans System > Users > User Groups.

For developers : l'adresse de l'API ShipLogic peut être remplacée par le réglage vfd_tcgr_api_url (pour les tests) ; il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox The Courier Guy. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours l'état de l'extension, Sort order, Tax status et Geo zone. Les tarifs et lockers en cache ainsi que la dernière erreur ShipLogic sont toujours supprimés. Si Remove data on uninstall est activée, les réglages, le journal et les choix de locker des paiements sans commande sont aussi supprimés. Si elle est désactivée, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les lockers et les références de suivi enregistrés sur les commandes ne sont jamais supprimés, et les commandes existantes conservent leur mode de livraison et leur coût.

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

The Courier Guy et ShipLogic sont des marques déposées de leurs propriétaires respectifs. Cette extension n'est ni affiliée à The Courier Guy ou ShipLogic, ni approuvée par eux.