VibeFox The Courier Guy for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

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 la livraison en locker ne peut pas être 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. Votre boutique doit livrer en Afrique du Sud (WooCommerce > Settings > General > Shipping location(s)).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi transférer le dossier vfd_the_courier_guy dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox The Courier Guy, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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.

6. Renseignez la grille tarifaire et/ou un coût de repli.

7. Ajoutez VibeFox The Courier Guy à une zone d'expédition pour l'Afrique du Sud dans WooCommerce > Settings > Shipping > Shipping zones, choisissez le Delivery type (courier ou TCG locker) et, si vous le souhaitez, un titre. Ajoutez la méthode une seconde fois pour l'autre type de livraison.

Configuration

Les réglages principaux se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Ils s'appliquent à toutes les zones d'expédition. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone comporte deux champs :

Title (zone) : le nom de ce tarif au paiement, dans cette zone. Laissez-le vide pour utiliser le Method name général.

Delivery type (zone) : Courier to the door (par défaut) ou TCG locker (customer chooses a locker). Ajoutez la méthode deux fois pour proposer les deux. Les lockers nécessitent la clé API ShipLogic et ne sont disponibles qu'en Afrique du Sud.

Chaque fois que vous enregistrez les réglages, les tarifs et les lockers en cache sont effacés. Les avertissements affichés au-dessus des réglages vous signalent lorsque la boutique n'expédie pas en Afrique du Sud, que la clé API manque, que le taux de conversion ZAR ou l'adresse de l'expéditeur manque, qu'il n'y a ni grille tarifaire ni coût de repli, ou que la dernière requête ShipLogic a échoué (avec sa date et son erreur).

Général

Enable/Disable : désactive la méthode partout, y compris dans les zones d'expédition.

Method name : le nom affiché au paiement. Pour la livraison en locker, « locker » est ajouté, par exemple « The Courier Guy locker ». Une zone peut le remplacer par son propre titre. Par défaut : The Courier Guy.

Tax status : Taxable : les tarifs en temps réel sont pris hors TVA et WooCommerce ajoute sa propre taxe. None : les tarifs en temps réel sont pris TVA comprise.

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

API key : votre clé API ShipLogic provenant du portail The Courier Guy.

Account ID : facultatif. L'identifiant numérique du compte ShipLogic, seulement si votre clé donne accès à plusieurs comptes.

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 de votre boutique n'est pas le ZAR, indiquez la valeur de 1 ZAR dans la devise de votre boutique, par exemple 0.05. Sans cette valeur, 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 le champ vide. Le taux n'est pas mis à jour automatiquement.

Adresse de l'expéditeur (pour les tarifs en temps réel) (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 de la boutique : utilisés 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 (au-delà de 5 kg). Cliquez sur + Add row pour ajouter une ligne (une nouvelle ligne commence par l'Afrique du Sud) et sur la croix pour la supprimer. 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.

Fallback cost : utilisé lorsqu'il n'existe ni tarif en temps réel ni prix dans la grille. Laissez-le vide pour masquer la méthode dans ce cas.

Conditions

Min weight (kg) : masque la méthode en dessous de ce poids de panier. 0 signifie aucune limite.

Max weight (kg) : masque la méthode au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite.

Minimum order amount : n'affiche la méthode qu'à partir de ce sous-total de panier. Laissez-le vide pour l'afficher en permanence.

Free shipping from : le sous-total du panier à partir duquel cette méthode est gratuite. La livraison gratuite n'est proposée que lorsque la méthode a un prix pour la destination : un tarif en temps réel, un prix de la grille ou le Fallback cost. Si la grille ou le Fallback cost ont un prix, aucune requête n'est envoyée à ShipLogic pour le tarif. Laissez-le vide pour ne jamais proposer la livraison gratuite.

Excluded shipping classes : masque la méthode si le panier contient des produits appartenant à ces classes d'expédition WooCommerce.

Disponibilité sans zones d'expédition

Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, même là où aucune zone ne la contient.

Delivery type without zones : courier ou TCG locker pour ce mode. Utilisé uniquement avec Ignore shipping zones.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous expédiez. Les lockers ne sont proposés qu'en Afrique du Sud.

Avancé

Debug log : écrit les messages de débogage dans WooCommerce > Status > Logs, source vfd-the-courier-guy. 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.

Remove data on uninstall : si cette option est activée, la suppression de l'extension efface les réglages et les tarifs par zone de cette méthode. La désactivation de l'extension n'efface jamais les réglages. Les lockers et le suivi enregistrés sur les commandes sont conservés.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, montant minimum de commande et classes d'expédition exclues. Si la livraison gratuite s'applique et que la destination a un prix, la méthode est affichée avec un prix de 0.

Courier to the door : l'extension demande à ShipLogic le service le moins cher, de l'adresse de votre expéditeur jusqu'à l'adresse du client. La rue, la ville, la province et le code postal du client doivent d'abord être renseignés. Jusque-là, le prix de la grille est affiché.

TCG locker : le tarif en temps réel est le service le moins cher, du domicile jusqu'au locker le plus proche de la ville du client. Il n'est pas recalculé pour le locker que le client choisit.

La commande entière est calculé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. Le montant en rands est converti dans la devise de votre boutique. Le niveau de service, par exemple ECO, est enregistré sur la ligne d'expédition.

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 du Fallback cost. Si aucun ne s'applique, la méthode est masquée.

La méthode fonctionne au paiement classique et dans les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension 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 : on les choisit 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 instance de zone (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 un tarif TCG locker au paiement classique ou au paiement en blocs, un sélecteur de locker apparaît sous ce tarif. 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 la commande puisse être passée.

Le locker est à nouveau vérifié côté serveur, par rapport à la liste de ShipLogic. Son nom et son fournisseur proviennent de ShipLogic, jamais du navigateur. Le choix est conservé lors des actualisations du paiement et réinitialisé lorsque l'adresse change.

Si ShipLogic est injoignable, le sélecteur indique que les lockers ne peuvent pas être chargés, et la commande peut être passée sans locker. La commande est alors signalée : « Not chosen — ShipLogic was unavailable at checkout. Agree the locker with the customer. » (Non choisi : ShipLogic était indisponible au paiement. Convenez du locker avec le client.)

Commandes

Le locker choisi (nom, identifiant et fournisseur) est enregistré sur la commande. Il est affiché sur l'écran de commande de l'administration, sur les pages « Merci » et « Mon compte » et dans les e-mails de commande (HTML et texte brut). L'e-mail destiné à l'administrateur affiche aussi l'identifiant du locker.

Sur l'écran de commande de l'administration, les commandes de cette méthode comportent un champ The Courier Guy tracking reference. Saisissez la référence de votre portail The Courier Guy et cliquez sur Save. La référence est affichée au client sur la page de commande et dans les e-mails envoyés ensuite.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, The Courier Guy n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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 en arrière-plan.

Dépannage

The Courier Guy n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, le Minimum order amount et les Excluded shipping classes. Vérifiez que la grille ou le Fallback cost ont un prix. Les tarifs de locker n'apparaissent que pour les adresses sud-africaines.

Les clients ne voient aucune liste de lockers : les lockers nécessitent la clé API, une méthode de zone avec Delivery type « TCG locker » 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, la rue, la ville, la province et le code postal du client doivent être renseignés. Pour les lockers, ShipLogic doit trouver un locker près de la ville du client. Activez Debug log et ouvrez WooCommerce > Status > Logs, source vfd-the-courier-guy.

ShipLogic est indisponible : 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.

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs et les lockers en cache.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve les réglages et efface seulement les tarifs et les lockers en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de la licence de cette extension, les tarifs et les lockers en cache ainsi que la dernière erreur sont toujours supprimés. Les réglages et les tarifs par zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les lockers et les références de suivi enregistrés sur les commandes ne sont jamais supprimés, et les commandes existantes conservent leurs lignes d'expédition.

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