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

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 à la date de rédaction). La clé API est délivrée dans votre compte Cargoson ; si votre formule n'affiche pas les réglages API, demandez au 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 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échargement terminé, cliquez sur Configure, ou retrouvez VibeFox Cargoson plus tard dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. 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). Cliquez sur Save.

À l'installation, le module crée le transporteur Cargoson avec le texte de délai de livraison Delivery by the cheapest Cargoson carrier. Le transporteur est affecté à toutes les zones 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. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Cargoson > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section dispose de son propre bouton Save, qui enregistre la page entière. Après l'enregistrement, vous voyez Settings saved. Cached Cargoson prices were cleared. Les nombres décimaux peuvent être saisis avec un point ou une virgule. Rien n'est enregistré et la page affiche une erreur si un champ numérique contient du texte ou un nombre négatif, si Currency conversion rate vaut 0, si Minimum weight est supérieur à Maximum weight, si Method title dépasse 64 caractères, si Price currency n'est pas un code à 3 lettres, ou si une ligne du tableau de tarifs contient un code pays ou un prix invalide. Si le module ne connaît pas l'unité de poids de la boutique, un avertissement après l'enregistrement indique que les poids des produits sont pris en kilogrammes ; définissez l'unité dans International > Localization (Local units).

General

Enable Cargoson : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et au moment du paiement. Par défaut : Cargoson. Obligatoire. C'est aussi le nom du transporteur dans Shipping > Carriers.

Shipping cost : le mode de calcul du prix.

La raison de l'absence de prix en direct est consignée dans le journal du module. Elle n'est jamais affichée au client.

API Cargoson (nécessaire pour les tarifs en direct uniquement)

API key : la clé API de votre compte Cargoson. Elle est envoyée uniquement à Cargoson et 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 uniquement pour la modifier.

Remove the saved API key : apparaît lorsqu'une clé est enregistrée. Activez l'option et enregistrez pour supprimer la clé.

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

Package type code : le code de type de colis Cargoson envoyé avec la demande de prix. 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 par défaut de votre boutique : 1 unité de la devise Cargoson = X unités de votre devise par défaut. Laissez le champ vide pour rejeter ces prix, afin qu'un client ne soit jamais facturé dans la mauvaise devise.

Expédition depuis (adresse d'enlèvement) (utilisé pour les tarifs en direct)

Collection country : le pays depuis lequel vous expédiez. Par défaut, c'est 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 le pays de votre boutique, le code postal de la boutique défini dans Shop Parameters > Contact > Stores est utilisé.

La date d'enlèvement envoyée à Cargoson est aujourd'hui, dans le fuseau horaire de la boutique, ou le lundi suivant pendant le week-end.

Tarifs fixes (utilisés lorsque Shipping cost vaut Fixed prices, et comme solution de repli pour les tarifs en direct)

Price per country and size : un tableau avec une colonne Country (code à 2 lettres), une colonne Price et des prix selon le poids du panier dans la devise par défaut de votre boutique, hors taxes : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg, XL au-delà de 5 kg. Un prix de taille vide ou égal à 0 utilise la colonne Price ; un 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 l'icône de corbeille pour en supprimer une. Utilisez * comme code pays pour tous les pays qui n'ont pas leur propre ligne. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) n'ont pas de tarif fixe, donc le transporteur est masqué pour eux. Les prix doivent être des nombres égaux ou supérieurs à 0. Une ligne vide est ignoré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 calculés par envoi.

Conditions

Minimum weight : masque le transporteur en dessous de ce poids de panier, en kg. 0 signifie aucune limite.

Maximum weight : masque le transporteur au-dessus de ce poids de panier, en kg. Par défaut : 25. 0 signifie aucune limite.

Minimum order amount : n'affiche le transporteur que lorsque le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez le champ vide pour l'afficher toujours.

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 : la règle de taxe du transporteur, ou No tax. Les prix de transport dans Cargoson sont généralement nets (hors TVA). Choisissez No tax si vos prix incluent déjà la taxe.

Disponibilité sans zones de livraison

Normalement, le transporteur est proposé dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose Cargoson pour les pays ci-dessous, quelles que soient les zones affectées au transporteur. Lorsque vous activez l'option et enregistrez, le transporteur est affecté à toutes les zones ; les zones créées plus tard sont également affectées. Lorsque vous la désactivez et enregistrez, le transporteur retrouve ses anciennes zones.

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

Avancé

Debug log : enregistre chaque calcul de tarif dans logs/vfd_cgs_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API et les prix rejetés sont toujours consignés, même lorsque cette option est désactivée. La clé API et le code postal du client ne sont jamais consignés.

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 du module supprime les réglages Cargoson, le transporteur, les prix en cache, les devis des commandes et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix Cargoson. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Les poids des produits sont convertis de l'unité de votre boutique en kilogrammes. Le module vérifie d'abord les conditions : pays de livraison, poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Cargoson.

En mode tarifs fixes, le prix est pris dans le tableau. En mode tarifs en direct, le module envoie à Cargoson la date d'enlèvement, le pays et le code postal d'enlèvement, le pays et le code postal de livraison, ainsi qu'un colis avec le code de type de colis et le poids total du panier (au moins 0,1 kg). Un tarif en direct n'est demandé que si l'adresse de livraison comporte un code postal. Cargoson renvoie les prix de vos transporteurs ; le module retient le moins cher (celui du transporteur sélectionné, le cas échéant) et le convertit dans votre devise par défaut si nécessaire. Le prix est calculé dans votre devise par défaut, puis affiché dans la devise du panier du client.

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, pour 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. Le transporteur est masqué, ou le tarif fixe est utilisé en mode de repli.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module calcule uniquement les tarifs. Il ne crée pas d'expéditions ni de réservations dans Cargoson, n'imprime pas d'étiquettes et ne suit pas les colis, et les clients ne peuvent pas choisir de point relais automatique ni de point de retrait. Le panier est évalué comme un seul colis au poids total ; les dimensions du colis ne sont pas envoyées. Seul le prix le plus bas est affiché, et non une liste de transporteurs.

Commandes

La page d'une commande Cargoson affiche un bloc Cargoson shipping avec le tarif calculé au moment du paiement :

Carrier, Service et Cargoson service ID : le transporteur et le service Cargoson proposés, affichés lorsqu'un tarif en direct a été utilisé.

Price source : Cargoson live price, Fixed price ou Free shipping threshold.

Calculated price (excl. tax) : le prix dans la devise par défaut de votre boutique.

Le devis est enregistré lors de la validation de la commande et ne change pas ensuite. Réservez l'envoi dans Cargoson ou avec ses propres intégrations.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Cargoson est le premier bloc de Modules > Module Manager > VibeFox Cargoson > Configure, 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 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: presta-shipping-cargoson et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation de configuration du 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-le dans votre compte vibefox.net.

Sans clé active, le transporteur Cargoson n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué 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, sous 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 que vous travaillez 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Cargoson n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Cargoson est activé. 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 figure dans Countries). Contrôlez les limites de poids et Minimum order amount. En mode tarifs fixes, vérifiez que le pays ou * a un prix pour la taille du panier. Les produits peuvent aussi être limités à certains transporteurs dans la fiche produit.

Les tarifs en direct n'apparaissent pas : consultez le champ Log sur la page du module. Les erreurs de l'API sont toujours consignées ; activez Debug log pour voir chaque calcul. Causes fréquentes : aucun code postal de livraison saisi, aucun code postal d'enlèvement, clé API refusé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 voient toujours 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 utilise 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 tarifs Cargoson et saisissez le Currency conversion rate.

La TVA est facturée deux fois sur la livraison : vos tarifs Cargoson incluent déjà la TVA. Réglez Tax sur No tax.

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

La page indique que le transporteur Cargoson est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Cargoson et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les prix en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) ainsi que les réglages, les devis des commandes et le journal. Si l'option est désactivée, le transporteur est seulement désactivé, les réglages et les devis des commandes passées sont conservés, et seuls les devis des paniers sans commande sont supprimés. Réinstaller le module rend au transporteur enregistré son statut précédent ; ainsi, Reset n'active pas un transporteur que vous aviez désactivé.

Cargoson est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à Cargoson ni approuvé par Cargoson.