VibeFox Cargoson for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Compte Cargoson (pour les tarifs en direct uniquement) : les tarifs en direct utilisent l'API de tarifs de fret de Cargoson. Les requêtes de tarifs de fret nécessitent un abonnement Cargoson avec accès à l'API (formule Advanced ou supérieure au moment de la rédaction). La clé API est délivrée dans votre compte Cargoson ; si votre formule n'affiche pas les réglages API, demandez l'aide du support Cargoson. Les prix proviennent des transporteurs et des grilles tarifaires connectés à ce compte. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de compte Cargoson.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour 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 envoyer le dossier vfd_cargoson dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Cargoson, 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, puis cliquez sur Activate.

5. Choisissez le mode de calcul des frais de livraison et remplissez les sections correspondantes : les tarifs fixes et, pour les tarifs en direct, la clé API et le code postal d'enlèvement (voir Configuration).

6. Ajoutez VibeFox Cargoson à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Cargoson. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone) : le nom affiché au client pour cette zone. Laissez-le vide pour utiliser le Method title global.

À chaque enregistrement des réglages, les tarifs Cargoson en cache sont effacés. Les nombres décimaux peuvent être saisis avec un point ou une virgule.

General

Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois.

Method title : le nom de la méthode de livraison affiché dans le panier et au paiement. Par défaut : Cargoson. Une zone peut le remplacer.

Shipping cost : mode de calcul du prix.

La raison de l'absence de tarif en direct est écrite dans le journal WooCommerce. Elle n'est jamais affichée au client.

Cargoson API (requise pour les tarifs en direct uniquement)

API key : la clé API de votre compte Cargoson. Elle n'est envoyée qu'à cargoson.com et n'est jamais affichée aux clients ni écrite dans le journal.

Carrier : les prix utilisés. Le client voit un seul tarif.

Package type code : le type de colis Cargoson envoyé avec la demande de tarif. Par défaut : CLL. Les exemples de l'API Cargoson utilisent EUR (palette EUR) et FIN (palette FIN). Pour les colis, utilisez le code de colis de votre compte Cargoson. La commande est envoyée comme un seul colis avec le poids total du panier.

Price currency : la devise des prix de votre compte Cargoson, sous forme de code à 3 lettres. Par défaut : EUR. L'API renvoie des montants sans code de devise.

Currency conversion rate : nécessaire uniquement si la devise des prix diffère de la devise de votre boutique : 1 unité de la devise Cargoson = X unités de la devise de votre boutique. Laissez ce champ vide pour rejeter ces prix, afin qu'un client ne paie jamais dans la mauvaise devise.

Ship from (collection address) (utilisé pour les tarifs en direct)

Collection country : le pays depuis lequel vous expédiez. Par défaut, le pays de votre boutique.

Collection postcode : le code postal depuis lequel vous expédiez. Cargoson l'exige. S'il est vide et que le pays d'enlèvement est celui de votre boutique, le code postal de la boutique défini dans WooCommerce > Settings > General est utilisé.

La date d'enlèvement envoyée à Cargoson est aujourd'hui, ou le lundi suivant si l'on est en week-end.

Fixed prices (utilisés lorsque Shipping cost est sur Fixed prices, et en solution de repli pour les tarifs en direct)

Price per country and size : un tableau de pays avec une colonne Price et des tarifs selon le poids du panier, dans la devise de votre boutique : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg, XL au-delà de 5 kg. Un tarif de taille vide ou égal à 0 utilise la colonne Price ; une colonne Price vide signifie qu'il n'y a pas de tarif fixe pour cette taille. Cliquez sur Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * Default s'applique à tous les pays qui n'ont pas leur propre ligne. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) n'ont aucun tarif fixe, la méthode leur est donc masquée.

Fixed price applies : Per order facture le prix une seule fois. Per item (price × quantity) le multiplie par le nombre d'articles du panier. Les tarifs en direct Cargoson sont toujours appliqués par envoi.

Conditions

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

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

Minimum order amount : affiche la méthode uniquement lorsque le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez vide pour l'afficher toujours.

Excluded shipping classes : masque la méthode si le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Free shipping : active la livraison gratuite lorsque le montant de commande indiqué ci-dessous est atteint.

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.

Tax status : Taxable ajoute la TVA sur la livraison selon vos réglages de taxes WooCommerce, None ne l'ajoute pas. Les tarifs des transporteurs dans Cargoson sont généralement hors taxes (sans TVA). Choisissez None si vos prix incluent déjà la taxe.

Availability without shipping zones

Ignore shipping zones : propose Cargoson pour les pays indiqués ci-dessous, même s'il n'est pas ajouté à une zone de livraison.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Advanced

Debug log : journalise chaque calcul de tarif dans WooCommerce > Status > Logs, source vfd_cargoson. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. La clé API et le code postal du client ne sont jamais journalisés.

Remove data on uninstall : lorsqu'elle est activée, la suppression de l'extension efface tous les réglages Cargoson, les méthodes de zone et les tarifs en cache. La désactivation de l'extension ne supprime jamais rien.

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimum de commande et classes d'expédition exclues. Si la livraison gratuite s'applique, le client obtient un tarif gratuit et aucune requête n'est envoyée à Cargoson.

En mode tarifs fixes, le prix est pris dans le tableau. Dans les modes en direct, l'extension envoie à Cargoson la date d'enlèvement, le pays et le code postal d'enlèvement, le pays et le code postal de livraison, et un colis avec le code de type de colis et le poids total du panier (au minimum 0,1 kg). Les poids des produits sont convertis de l'unité de votre boutique en kilogrammes. Un tarif en direct n'est demandé qu'après que le client a saisi un code postal. Cargoson renvoie les prix de vos transporteurs ; l'extension retient le moins cher (celui du transporteur sélectionné, le cas échéant) et le convertit dans la devise de votre boutique si nécessaire.

Chaque réponse est mise 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 10 minutes, afin que le paiement n'attende pas Cargoson à chaque actualisation. Le délai d'attente de l'API est de 10 secondes. Si Cargoson renvoie une erreur, aucun prix pour l'itinéraire, ou un prix dans une autre devise sans taux de conversion, le client ne voit aucune erreur. La méthode est masquée, ou le tarif fixe est utilisé en mode de repli.

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

L'extension ne calcule que des tarifs. Elle ne crée pas d'envois ni de réservations dans Cargoson, n'imprime pas d'étiquettes et ne suit pas les colis, et les clients ne peuvent pas choisir un point relais automatique ni un point de retrait. Le panier est traité comme un seul colis au poids total ; les dimensions du colis ne sont pas envoyées. Seul le prix le moins cher est affiché, et non une liste de transporteurs.

Commandes

Lorsqu'un tarif en direct est utilisé, la ligne de livraison de la commande enregistre le Carrier, le Service et le Cargoson service ID proposés. Ils s'affichent sur l'écran de modification de la commande, afin que vous sachiez quoi réserver dans Cargoson. Réservez l'envoi dans Cargoson ou avec ses propres intégrations.

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 Cargoson. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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 pour un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Cargoson n'est pas affiché aux clients au moment du paiement. Les gestionnaires connectés de la boutique le voient toujours, avec la mention (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 l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Cargoson 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, Minimum order amount et Excluded shipping classes. En mode tarifs fixes, vérifiez que le pays ou * Default a un tarif pour la taille du panier.

Les tarifs en direct n'apparaissent pas : ouvrez WooCommerce > Status > Logs, source vfd_cargoson. Les erreurs de l'API sont toujours journalisées ; activez Debug log pour voir chaque calcul. Causes habituelles : aucun code postal de livraison saisi pour l'instant, aucun code postal d'enlèvement, clé API rejetée (clé erronée ou expirée, ou pas d'accès API dans votre formule Cargoson), aucun transporteur pour l'itinéraire ou le poids, ou un prix dans une autre devise. Avec Cargoson live prices, fixed prices if the API fails, les clients obtiennent quand même le tarif fixe pendant que vous corrigez le problème.

Cargoson rejette le type de colis : utilisez le code de colis que votre compte Cargoson emploie dans Package type code. La raison apparaît dans le journal.

Un prix dans une autre devise est rejeté : réglez Price currency sur la devise de vos prix Cargoson et saisissez le Currency conversion rate.

Les tarifs semblent périmés après une modification : enregistrez la page des réglages. Cela efface les tarifs Cargoson 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 toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes de livraison.

Cargoson est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Cargoson ni approuvée par Cargoson.