VibeFox The Courier Guy 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.

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

Livraison en 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 actif de la boutique (International > Locations > Countries).

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 plus tard VibeFox The Courier Guy dans la liste des modules et cliquez sur Configure.

3. Collez 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 la API key ShipLogic. Pour les tarifs en temps réel, renseignez l'adresse de l'expéditeur (rue, ville, province, code postal) et, si la devise de votre boutique n'est pas le ZAR, le ZAR conversion rate.

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

6. Pour les tarifs de livraison en temps réel, cliquez sur Add South African provinces dans la section Advanced si la page indique que les adresses sud-africaines n'ont pas de province.

À l'installation, le module crée deux transporteurs : The Courier Guy (texte du délai de livraison The Courier Guy courier delivery to your door) et The Courier Guy locker (Delivery to a TCG locker of your choice). Les deux sont actifs, liés à la zone Afrique du Sud et à 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. N'y définissez pas de prix : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox The Courier Guy > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide les tarifs et lockers en cache ainsi que la dernière erreur ShipLogic. Les avertissements en haut de la page vous indiquent si l'Afrique du Sud n'est pas un pays actif, si la clé API, le taux de conversion ZAR ou l'adresse de l'expéditeur manque, s'il n'y a ni grille tarifaire ni coût de repli, si les adresses sud-africaines n'ont pas de province, si l'unité de poids ou de dimensions de la boutique n'est pas connue du module, ou si la dernière requête ShipLogic a échoué (avec sa date et son erreur). Une valeur numérique non valide (par exemple négative) n'est pas enregistrée : la page indique le champ et conserve la valeur précédente.

Général

Courier to the door : active ou désactive le transporteur de livraison à domicile. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Courier carrier name : le nom du transporteur de livraison à domicile à l'étape de paiement. Valeur par défaut : The Courier Guy. Obligatoire.

TCG locker : active ou désactive le transporteur locker. Le client choisit un locker au paiement. Il n'est proposé que pour les adresses sud-africaines, et seulement avec la clé API ShipLogic.

Locker carrier name : le nom du transporteur locker à l'étape de paiement. Valeur par défaut : The Courier Guy locker. Obligatoire.

Tax status : la règle de taxe des deux transporteurs. Taxable: <tax rule> : les tarifs en temps réel sont pris hors TVA et PrestaShop ajoute la taxe de livraison de la règle sélectionnée. None : les tarifs en temps réel sont pris TVA incluse.

API ShipLogic (tarifs en temps réel et lockers)

API key : votre clé API ShipLogic provenant du portail The Courier Guy. Elle n'est jamais affichée aux clients ni écrite dans le journal. Après enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement 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)

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. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés et la grille tarifaire s'applique. Si la devise de votre boutique est le ZAR, laissez ce champ vide. Le taux n'est pas mis à jour automatiquement.

Adresse de l'expéditeur (pour les tarifs en temps réel) (lieu où The Courier Guy récupère les colis, en Afrique du Sud ; 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 de l'expéditeur.

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

Sender province : choisissez la province sud-africaine dans la liste.

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

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 l'icône de corbeille pour en supprimer 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 le tableau. Laissez-le vide pour masquer les transporteurs dans ce cas.

Conditions (les deux transporteurs)

Min weight (kg) : masque les transporteurs si le poids du panier est inférieur à cette valeur. 0 signifie aucune limite.

Max weight (kg) : masque les transporteurs si le poids du panier est supérieur à cette valeur. 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 transporteurs qu'à partir de ce sous-total de panier (produits nécessitant une livraison, hors taxes, après remises). Laissez vide pour les afficher en permanence.

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 transporteurs sont affichés à 0 et aucune requête n'est envoyée à ShipLogic pour le tarif.

Disponibilité sans zones d'expédition

Normalement, les transporteurs sont proposés dans les zones d'expédition auxquelles ils sont liés dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur du type de livraison ci-dessous pour les pays ci-dessous, même si ses zones ne les contiennent pas. Le transporteur est lié à chaque zone active, y compris aux zones créées plus tard. Lorsque vous désactivez à nouveau l'option, il retrouve les zones qu'il avait auparavant.

Delivery type without zones : Courier to the door ou TCG locker (customer chooses a locker). Utilisé uniquement avec Ignore shipping zones.

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

Avancé

South African provinces : PrestaShop n'a pas de provinces sud-africaines, mais le tarif de livraison en temps réel a besoin de la province de l'adresse. Add South African provinces ajoute les 9 provinces (EC, FS, GP, KZN, LP, MP, NC, NW, WC) comme états de l'Afrique du Sud et affiche le champ d'état dans les adresses sud-africaines. Les provinces existantes ne sont pas ajoutées à nouveau. Jusqu'à cette opération, le transporteur reçoit le prix de la grille tarifaire.

Debug log : écrit des messages de débogage dans logs/vfd_tcgr_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 journalisées, même si cette option est désactivée. La clé API et les données clients ne sont jamais journalisées.

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

Remove data on uninstall : si cette option est activée, la désinstallation du module supprime ses réglages et ses transporteurs. Si elle est désactivée, la désinstallation se contente de désactiver les transporteurs. Les lockers enregistrés sur les commandes sont toujours conservés.

Fonctionnement au paiement

À l'étape d'expédition, PrestaShop demande au module le prix de chaque transporteur. Seuls les produits physiques comptent : les produits virtuels n'ajoutent ni poids ni montant à la commande. Le module vérifie d'abord les conditions : poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0.

Courier to the door : le module demande à ShipLogic le service le moins cher de votre adresse d'expéditeur à l'adresse du client. L'adresse doit comporter une rue, une ville, une province et un code postal. Jusque-là, 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. Le transporteur locker n'apparaît que pour les adresses sud-africaines et seulement avec la clé API.

La commande entière est calculée comme un seul colis : le poids total, la plus grande longueur et largeur, et les hauteurs empilées. Les produits sans dimensions comptent comme des cubes de 10 cm. Les poids et dimensions sont convertis depuis les unités de votre boutique. Le montant en rands est converti dans votre devise par défaut, puis affiché dans la devise du panier du client.

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'existe pas de tarif en temps réel, le prix provient de la grille, puis du Fallback cost. Si aucun ne s'applique, le transporteur est masqué. Les erreurs de l'API ne sont jamais affichées au client.

Les transporteurs fonctionnent avec les thèmes Classic et Hummingbird. Si vous modifiez un transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne réserve pas d'envois, ne crée pas de lettres de transport ni d'étiquettes, et ne met pas à jour le suivi automatiquement. Il n'existe pas de carte des lockers : les lockers se choisissent dans une liste. Les tarifs en temps réel et les lockers ne concernent que l'Afrique du Sud. Les autres pays reçoivent la grille tarifaire. Un seul tarif par transporteur (le niveau de service le moins cher) est affiché, sans choix de niveaux de service, d'assurance ni d'options au paiement.

Points de retrait

Lorsque le client choisit le transporteur locker, un sélecteur de lockers apparaît sous celui-ci. Il liste les lockers renvoyés par ShipLogic pour la ville de l'adresse de livraison, du plus proche au plus éloigné. Le client peut saisir une autre ville, un quartier ou un code postal et cliquer sur Search. Un locker doit être choisi avant que le client puisse continuer : sinon, l'étape d'expédition affiche Please choose a The Courier Guy locker.

Le locker est à nouveau vérifié côté serveur, dans la liste de ShipLogic, y compris au moment de la validation de la commande. Son nom et son fournisseur proviennent de ShipLogic, jamais du navigateur. Le choix est conservé pour le panier et réinitialisé lorsque l'adresse de livraison change.

Si ShipLogic est injoignable, le sélecteur indique que les lockers ne peuvent pas être chargés et que la boutique contactera le client au sujet du 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.

Commandes

Le locker choisi (nom, identifiant et fournisseur) est enregistré avec la commande. Il s'affiche dans le bloc The Courier Guy de la page de commande de l'administration, sur la page de confirmation de commande, dans le détail de commande du client et dans l'e-mail de confirmation de commande. L'e-mail « nouvelle commande » de la boutique (module Mail alerts) affiche également l'identifiant du locker, ou indique qu'aucun locker n'a été choisi parce que ShipLogic était indisponible.

Référence de suivi The Courier Guy : réservez le colis dans votre portail The Courier Guy et saisissez la référence comme numéro de suivi de l'envoi dans le bloc Shipping de la commande (Edit). Le bloc The Courier Guy l'affiche. Le client la voit dans le détail de sa commande et reçoit l'e-mail « en transit » de PrestaShop.

Clé de licence

Le module 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 la page Modules > Module Manager > VibeFox The Courier Guy > Configure, 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), 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, se trouvent la ligne Product: presta-shipping-the-courier-guy 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 : le domaine 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, aucun des deux transporteurs The Courier Guy (courier to the door ou TCG locker) n'est affiché aux clients au moment du paiement, et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : les transporteurs sont donc masqués 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, sur 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é automatiquement pendant votre travail 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 du module supprime toujours la clé de licence et le statut de licence. Le Reset de ce module ne supprime pas de données : la clé et le statut sont donc conservés.

Dépannage

The Courier Guy n'apparaît pas au paiement : vérifiez que la licence est active et que le transporteur est activé (Courier to the door ou TCG locker). Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids et le Minimum order amount. Vérifiez que la grille ou le Fallback cost a un prix. Le transporteur locker n'apparaît que pour les adresses sud-africaines et avec la clé API. De plus, les produits peuvent être limités à certains transporteurs sur la page produit.

Les clients ne voient aucune liste de lockers : les lockers nécessitent la clé API, le transporteur 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.

Le prix est toujours celui de la grille : consultez les avertissements de la page des réglages. Un tarif en temps réel nécessite la clé API, l'adresse complète de l'expéditeur et, pour les boutiques qui ne sont pas en rands, le taux de conversion ZAR. Pour la livraison à domicile, l'adresse du client doit comporter une rue, une ville, une province et un code postal : ajoutez les provinces sud-africaines dans la section Advanced. Pour les lockers, ShipLogic doit trouver un locker près de la ville du client. Activez le Debug log, rechargez le paiement et consultez le champ Log sur la page du module.

ShipLogic est en panne : le prix de la grille ou le coût de repli s'affiche. Les commandes avec locker peuvent être passées sans locker et sont signalées sur la commande.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide les tarifs et les lockers en cache.

La page indique qu'un transporteur The Courier Guy est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. La réinitialisation conserve vos réglages et l'état d'activation des transporteurs existants.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox The Courier Guy et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. Les tarifs et lockers en cache ainsi que la dernière erreur ShipLogic sont toujours supprimés. Si Remove data on uninstall est activé, les transporteurs sont supprimés (les commandes conservent leur historique), et les réglages, le journal ainsi que les lockers des paniers sans commande sont supprimés. Si l'option est désactivée, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module rend aux transporteurs le statut qu'ils avaient. Les lockers enregistrés sur les commandes ne sont jamais supprimés.

The Courier Guy et ShipLogic sont des marques de leurs propriétaires respectifs. Ce module n'est ni affilié ni approuvé par The Courier Guy ou ShipLogic.