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

Compte Cargoson (pour les prix en direct uniquement) : les prix en direct utilisent l'API de tarification du fret de Cargoson. Les demandes de tarif de fret nécessitent un abonnement Cargoson avec accès à l'API (offre Advanced ou supérieure au moment de la rédaction). La clé API est délivrée dans votre compte Cargoson ; demandez l'aide du support Cargoson si votre offre n'affiche pas les réglages API. Les prix proviennent des transporteurs et des grilles tarifaires connectés à ce compte. Si vous n'utilisez que des prix 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

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

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

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

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

5. Choisissez la façon dont les frais de livraison sont calculés et remplissez les sections correspondantes : les prix fixes et, pour les prix en direct, la clé API et le code postal d'enlèvement (voir Configuration). Activez Enable Cargoson et cliquez sur Save.

OpenCart 4

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

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

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

Après l'installation, le mode de livraison reste désactivé tant que vous n'avez pas activé Enable Cargoson et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Cargoson que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Les sections sont listées à gauche. Un seul bouton Save en bas enregistre toute la page sans la recharger. 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 les erreurs si Method title est vide ou dépasse 64 caractères, si un champ numérique contient du texte ou un nombre négatif, si Currency conversion rate vaut 0, si Minimum weight (kg) est supérieur à Maximum weight (kg), si Price currency n'est pas un code à 3 lettres, si une ligne du tableau des prix contient un pays ou un prix invalide, ou si Sort order n'est pas un nombre entier. Si l'unité de poids de la boutique n'est pas reconnue par l'extension, un avertissement après l'enregistrement indique que les poids des produits sont pris en kilogrammes ; ajoutez une classe de poids avec l'unité kg dans System > Localisation > Weight Classes. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Général

Le client voit un seul tarif Cargoson. Vous pouvez limiter le mode à une zone géographique ou à des pays dans Availability.

Enable Cargoson : affiche ou masque Cargoson au paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client dans le panier et au paiement, 64 caractères au maximum. Par défaut : Cargoson. Obligatoire.

Shipping cost : la manière dont le prix est calculé.

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

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

API Cargoson (obligatoire pour les prix 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. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API key : activez l'option puis enregistrez pour supprimer la clé enregistrée.

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

Package type code : le 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 dans 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 débité dans une mauvaise devise.

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

Collection country : le pays depuis lequel vous expédiez. La première option, Store country, utilise le pays de votre boutique.

Collection postcode : le code postal depuis lequel vous expédiez. Cargoson l'exige pour les prix en direct. L'adresse de la boutique dans OpenCart est un texte libre : le code postal n'en est donc jamais repris ; saisissez-le ici.

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

Prix fixes (utilisés lorsque Shipping cost vaut Fixed prices, et en secours pour les prix en direct)

Price per country and size : une liste de lignes avec un Country, un Price et des prix selon le poids du panier, dans la devise par défaut de la 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. Choisissez * All other countries pour les prix appliqués à tous les pays sans ligne propre. Les pays sans ligne (lorsqu'il n'existe pas de ligne *) n'ont pas de tarif fixe, donc le mode est masqué pour eux. Les prix doivent être des nombres supérieurs ou égaux à 0. Une ligne vide est ignorée.

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

Conditions

Minimum weight (kg) : masque le mode en dessous de ce poids de panier. 0 signifie sans limite (par défaut).

Maximum weight (kg) : masque le mode au-dessus de ce poids de panier. Par défaut : 25. 0 signifie sans limite.

Minimum order amount : n'affiche le mode que lorsque le sous-total des produits nécessitant une livraison (après le coupon, hors taxes) atteint ce montant. Laissez le champ vide pour l'afficher toujours.

Free shipping : active la livraison gratuite Cargoson à partir du montant indiqué ci-dessous.

Free shipping from : le sous-total des produits nécessitant une livraison (après le coupon, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Les prix des transporteurs dans Cargoson sont généralement hors TVA. Choisissez No tax si vos prix incluent déjà la taxe.

Disponibilité

Geo zone : ne propose Cargoson qu'aux adresses de cette zone géographique. All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : ne vérifie pas la zone géographique ; la liste de pays ci-dessous décide.

Countries : les pays de destination pour ce mode. Laissez le champ vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : enregistre chaque calcul de tarif dans storage/logs/vfd_cgs_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API et les prix rejetés sont toujours journalisés, même si cette option est désactivée. La clé API et le code postal du client ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_cgs_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal de débogage. 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 Cargoson, les prix en cache et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les devis Cargoson des commandes passées sont toujours conservés.

Import / Export

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

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

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Cargoson. Si une Geo zone est définie, que Ignore shipping zones est désactivé et que l'adresse est hors de la zone, Cargoson n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Les poids des produits sont convertis de leur classe de poids en kilogrammes. L'extension vérifie ensuite les conditions : pays autorisés, poids du panier et montant minimum de commande. Le montant de la commande est le prix des produits nécessitant une livraison, après la réduction du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit de boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Cargoson.

En mode fixe, le prix est tiré du 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). Un prix en direct n'est demandé que lorsque l'adresse de livraison a un code postal. Cargoson renvoie les prix de vos transporteurs ; l'extension retient le moins cher (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, arrondi à ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

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 : le mode est masqué, ou le prix fixe est utilisé en mode de secours.

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 ; les clients ne peuvent pas choisir de point relais automatique ni de point de retrait. Le panier est calculé comme un seul colis avec le 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.

Sous OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement et choisit Cargoson dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sous OpenCart 3.

Commandes

Lorsqu'un client passe une commande avec Cargoson, le tarif calculé au paiement est enregistré avec la commande. Dans Sales > Orders, la page de commande affiche un panneau Cargoson shipping :

Carrier, Service et Cargoson service ID : le transporteur et le service Cargoson proposés, affichés lorsqu'un prix 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 panneau s'affiche aussi lorsque le mode est désactivé. Sous OpenCart 4, la commande est créée une fois à l'étape de confirmation et mise à jour à chaque retour du client sur cette étape ; le devis enregistré est donc le dernier calculé au paiement. Si le client passe à un autre mode de livraison, le devis Cargoson de la commande est supprimé. La modification de la commande dans l'administration ne change pas le devis, qui ne change pas non plus par la suite. 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 License — VibeFox Cargoson est le premier bloc de Extensions > Extensions > Shipping > VibeFox Cargoson > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau l'état, 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-cargoson 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 état connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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, Cargoson n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration depuis le même navigateur voit toujours le mode dans la boutique, marqué (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 de l'administrateur, donc sans clé active le mode est masqué 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 concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : une fois par jour pendant les 14 premiers jours suivant 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 l'état 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é. Vérifiez la Geo zone (ou Ignore shipping zones et Countries), les limites de poids et le Minimum order amount. En mode fixe, vérifiez que le pays ou * All other countries a un prix pour la taille du panier. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les prix en direct n'apparaissent pas : consultez le champ Log de la page de l'extension. Les erreurs de l'API sont toujours journalisées ; activez Debug log pour voir chaque calcul. Raisons habituelles : aucun code postal de livraison saisi, Collection postcode manquant, clé API rejetée (clé erronée ou expirée, ou offre Cargoson sans accès API), aucun transporteur pour l'itinéraire ou le poids, ou prix dans une autre devise. Avec Cargoson live prices, fixed prices if the API fails, les clients obtiennent le prix 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 la Currency conversion rate.

La taxe est appliquée deux fois sur la livraison : vos prix Cargoson incluent déjà la TVA. Réglez Tax class sur No tax.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide le cache des prix Cargoson.

La page indique « Warning: You do not have permission to modify VibeFox Cargoson! » : le groupe d'utilisateurs de votre administration ne peut peut-être que consulter les réglages. Donnez au groupe l'autorisation de modification pour extension/shipping/vfd_cargoson (OpenCart 3) ou extension/vfd_cargoson/shipping/vfd_cargoson (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Cargoson peut être remplacée par le réglage vfd_cgs_api_url (pour les tests) ; il n'a pas de champ sur la page de réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Cargoson. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Cargoson, Sort order, Tax class et Geo zone. Les prix en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Cargoson et le journal de débogage sont aussi supprimés. Sinon, les autres réglages sont conservés et réutilisés lors d'une réinstallation. Les devis Cargoson des commandes passées 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 et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Cargoson dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de poubelle) pour supprimer le paquet téléversé.

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