VibeFox Chilexpress for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur, avec l'extension cURL pour les tarifs en temps réel. Le module refuse de s'installer sur les anciennes versions de PHP.

Clés d'API Chilexpress (uniquement pour les tarifs en temps réel) : créez un compte sur le portail développeur de Chilexpress (developers.wschilexpress.com) et souscrivez à deux produits : Rating (Cotizador) et Coverage (Coberturas / Georreferencia). Chaque produit a sa propre clé d'abonnement. Les clés de test ne fonctionnent qu'avec l'environnement de test ; les clés de production sont délivrées aux clients professionnels de Chilexpress disposant d'un contrat client. Vous avez aussi besoin du code county Chilexpress de la comuna d'où vous expédiez, par exemple STGO. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de clés d'API.

Régions chiliennes (uniquement pour les tarifs en temps réel) : les tarifs en temps réel nécessitent la région de l'adresse de livraison. PrestaShop ne propose pas de régions chiliennes par défaut ; le module peut les ajouter pour vous (voir Chilean regions ci-dessous). Le pays Chile doit exister dans la boutique.

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 Chilexpress 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. Remplissez le tableau Country prices. Pour les tarifs en temps réel, saisissez les deux clés d'abonnement, votre code county d'origine et, si la devise de la boutique n'est pas le CLP, le taux de change CLP ; cliquez sur Add Chilean regions si la page le demande ; choisissez ensuite la source des tarifs (voir Configuration) et cliquez sur Save.

À l'installation, le module crée le transporteur Chilexpress avec le texte de délai de livraison Chilexpress courier. Le transporteur est lié à la zone Chili 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. Pour proposer Chilexpress dans d'autres zones, ajoutez-les au transporteur à cet endroit, ou activez Ignore shipping zones.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Chilexpress > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi les tarifs Chilexpress et les listes de comunas en cache. Les modifications nécessitent l'autorisation « configure » pour le module ; sans elle, la page affiche You do not have permission to configure this module.

La page signale les problèmes en haut : des tarifs API sont sélectionnés mais une clé, le code county d'origine ou le taux de change CLP manque ; le tableau des prix n'a aucune ligne pour le Chili ni pour la valeur par défaut ; la boutique n'a pas de régions chiliennes ou le formulaire d'adresse chilien n'a pas de champ de région ; l'unité de poids ou de dimension de la boutique n'est pas reconnue par le module (il la lit alors comme kg ou cm ; définissez-la dans International > Localization, Local units) ; le transporteur a été supprimé. Les nombres peuvent être saisis avec un point ou une virgule, selon la langue de votre back office. Un nombre invalide ou négatif, un CLP exchange rate égal à 0, un Min weight (kg) supérieur au Max weight (kg) ou un Name de plus de 64 caractères sont des erreurs, et rien n'est enregistré tant que vous ne les avez pas corrigées.

Général

Enable/Disable : active ou désactive la livraison avec Chilexpress. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name : le nom du mode de livraison affiché au client au paiement. C'est le nom du transporteur. Par défaut : Chilexpress. Obligatoire, jusqu'à 64 caractères.

Tax : la règle de taxe du transporteur, ou No tax (la valeur par défaut d'un nouveau transporteur). Les tarifs de l'API Chilexpress sont utilisés tels qu'ils sont cotés. Choisissez No tax si la cotation comprend déjà l'IVA et que votre boutique ajouterait une taxe en plus.

Tarifs

Rate source : d'où vient le prix.

Les tarifs en temps réel ne sont disponibles que pour les destinations au Chili. Les autres pays utilisent toujours les prix fixes.

Country prices : un tableau des pays de destination avec une colonne Price et, en option, des prix par taille de colis, dans la devise par défaut de votre boutique, hors taxes. La taille est déterminée par le poids du panier : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg, XL au-delà de 5 kg. Une taille laissée à 0 utilise Price. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. La ligne * Default s'applique aux pays sans ligne propre. Un pays sans ligne (et sans * Default) n'a pas de prix fixe, le transporteur y est donc masqué. Une ligne dont le prix et les prix par taille sont tous à 0 donne la livraison gratuite. Un tableau vide affiche une ligne pour le Chili à 0 ; la dernière ligne ne peut pas être supprimée, seulement remise à 0. Saisissez donc de vrais prix avant d'enregistrer la page. Un pays en double ou un prix invalide est corrigé (le doublon est ignoré, le prix est ramené à 0) et un avertissement liste les corrections.

Calculation type : Per order facture le prix fixe une seule fois. Per item (fixed price x number of items) le multiplie par le nombre d'articles du panier. Un tarif de l'API Chilexpress est toujours coté pour le colis entier.

API Chilexpress (tarifs en temps réel)

La section commence par des liens vers le portail développeur et vers les pages d'abonnement Rating et Coverage.

Test environment : utilise l'environnement de test de Chilexpress (qaservices.wschilexpress.com). Utilisez-le avec des clés de test et désactivez-le sur une boutique en production.

Rating API key : la clé d'abonnement du produit Rating (Cotizador).

Coverage API key : la clé d'abonnement du produit Coverage (Coberturas / Georreferencia). Elle sert à trouver le code county Chilexpress de la comuna du client (le champ Ville de l'adresse, avec sa région).

Après l'enregistrement, un champ de clé reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. La clé est enregistrée telle que vous la saisissez ; seuls les espaces en début et en fin sont supprimés.

Remove the saved Rating API key et Remove the saved Coverage API key : ne s'affichent que lorsqu'une clé est enregistrée. Cochez l'option et cliquez sur Save pour supprimer la clé.

Origin county code : le code county Chilexpress (comuna) d'où vous expédiez, de 2 à 5 lettres, par exemple STGO (Santiago Centro), PROV (Providencia) ou VALP (Valparaíso). Il est vide après l'installation. Une valeur qui n'est pas un code county est rejetée avec une erreur.

Service : le service Chilexpress utilisé pour le tarif. S'il n'est pas proposé pour la destination, le service le moins cher disponible est utilisé.

CLP exchange rate : Chilexpress cote en pesos chiliens. Il n'est nécessaire que si la devise par défaut de votre boutique n'est pas le CLP : le prix de 1 CLP dans cette devise, par exemple 0.001. Sans lui, les tarifs de l'API ne sont pas utilisés. Si la devise de la boutique est le CLP, laissez-le vide. La valeur doit être supérieure à 0.

Chilean regions : les comunas du Chili sont recherchées par région, donc les tarifs en temps réel nécessitent la région de l'adresse. Si la boutique n'a pas de régions chiliennes, le champ affiche le bouton Add Chilean regions. Il ajoute les 16 régions comme états du Chili (codes ISO RM, VS…), active « Contains states » pour le Chili et ajoute le champ de région au formulaire d'adresse chilien. Les régions déjà existantes (par code ou par nom) ne sont pas ajoutées une seconde fois. Lorsque tout est en place, le champ affiche Chilean addresses have a region avec le nombre de régions.

Disponibilité

Min weight (kg) : le poids minimal du panier pour que le transporteur apparaisse. 0 signifie aucune limite.

Max weight (kg) : le transporteur est masqué au-delà de ce poids de panier. Par défaut : 25. 0 signifie aucune limite ; un champ vide signifie 25 kg. Min weight (kg) ne peut pas être supérieur à cette valeur.

Minimum subtotal : n'affiche le transporteur que lorsque le sous-total du panier (produits nécessitant une livraison, après remises, hors taxes) atteint au moins ce montant. Laissez le champ vide pour l'afficher toujours.

Ignore shipping zones : propose le transporteur pour les pays ci-dessous même si leur zone n'est pas liée à lui : le transporteur est lié à toutes les zones, et les zones créées plus tard y sont liées aussi. Lorsque vous le désactivez, le transporteur retrouve ses zones précédentes.

Countries : les pays de destination pour ce mode, choisis parmi les pays actifs de la boutique. Laissez vide pour autoriser tous les pays. Ce champ n'est utilisé que si Ignore shipping zones est activé.

Livraison gratuite

Free shipping : active le seuil de livraison gratuite.

Free shipping from : le sous-total du panier (produits nécessitant une livraison, après remises, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement si Free shipping est activé. Dans ce cas, aucune requête n'est envoyée à l'API.

Avancé

Debug log : enregistre les requêtes API et les calculs de tarifs dans logs/vfd_chx_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 lorsque cette option est désactivée. Les clés d'API et les adresses des clients ne sont jamais journalisées.

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 : lorsque l'option est activée, la désinstallation du module supprime tous ses réglages, le transporteur, les tarifs en cache, les journaux et les services enregistrés avec les commandes. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les commandes elles-mêmes sont toujours conservées.

Fonctionnement lors du paiement

À l'étape de livraison, PrestaShop demande au module le prix Chilexpress. Seuls les produits nécessitant une livraison comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Le sous-total est calculé après les règles du panier (bons de réduction), hors taxes, dans la devise par défaut de votre boutique. Le module vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et sous-total minimal. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Chilexpress.

Pour une adresse au Chili et une source de tarifs API, le module prend la région de l'adresse et la comuna du champ Ville, puis recherche le code county Chilexpress dans la liste des comunas de cette région (Coverage API). Les accents, les espaces et les variantes orthographiques sont ignorés : Ñuñoa et Nunoa correspondent, et Santiago correspond à Santiago Centro. Un code county saisi directement dans le champ Ville est également accepté. Le module envoie ensuite à la Rating API les codes county d'origine et de destination, le poids du panier (au moins 0,1 kg), les dimensions du colis (longueur et largeur du plus grand produit, hauteurs cumulées) et le sous-total du panier en CLP comme valeur déclarée. Chilexpress renvoie ses services ; le module utilise le service choisi ou le moins cher, et convertit le montant en pesos dans la devise par défaut de votre boutique. Le prix est arrondi selon les décimales de cette devise, puis affiché dans la devise du panier du client.

Les tarifs sont mis en cache pendant 1 heure et les listes de comunas pendant 7 jours. Une requête échouée est retenue pendant 5 minutes, afin qu'une API lente ou indisponible ne ralentisse pas chaque actualisation du paiement. Le délai d'attente de l'API est de 10 secondes. Si Chilexpress renvoie une erreur, aucun service avec un prix, ou si la comuna ou la région est inconnue, le client ne voit aucune erreur. Le transporteur est masqué en mode API seul, sinon le prix fixe est utilisé. La raison est inscrite dans le journal de débogage.

Si vous modifiez le 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 calcule que des tarifs. Il ne crée ni envois ni ordres de transport (OT), n'imprime pas d'étiquettes, ne réserve pas d'enlèvements et ne suit pas les colis ; réservez l'envoi dans votre compte Chilexpress. Les clients ne peuvent pas choisir un bureau Chilexpress, et il n'y a pas de sélecteur de comunas : le client saisit la comuna dans le champ Ville standard. Les envois internationaux utilisent les prix fixes.

Commandes

Lorsqu'une commande est passée avec le transporteur Chilexpress, le module enregistre la manière dont son prix a été calculé. La page de commande dans le back office affiche un bloc Chilexpress avec le Chilexpress service (pour un tarif en temps réel, le service coté par Chilexpress, par exemple Express) et le Price source : Live rate (Chilexpress Rating API), Fixed price ou Free shipping.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Chilexpress est le premier bloc de la page Modules > Module Manager > VibeFox Chilexpress > 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) 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. Sous ces boutons se trouvent la ligne Product: presta-shipping-chilexpress 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 : celui 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, le transporteur Chilexpress n'est pas 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 : le transporteur est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du 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é à nouveau 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 ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Chilexpress n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe (ou que Ignore shipping zones est activé et que le pays figure dans Countries). Vérifiez les limites de poids et le Minimum subtotal. Avec des prix fixes, vérifiez que le pays ou * Default a une ligne. Les produits peuvent aussi être limités à certains transporteurs sur la fiche produit.

La livraison au Chili est gratuite alors qu'elle ne devrait pas l'être : la ligne du Chili (ou * Default) dans Country prices a 0 dans Price et dans les colonnes de taille. Saisissez les prix et cliquez sur Save.

Le tarif en temps réel n'est pas affiché, le prix fixe est utilisé à la place : vérifiez d'abord les avertissements en haut de la page du module. Sinon, activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Causes typiques : l'adresse n'a pas de région ou le champ région manque (utilisez Add Chilean regions), une comuna que Chilexpress ne reconnaît pas (vérifiez le champ Ville et la région), une clé pour le mauvais produit ou le mauvais environnement, ou une destination sans couverture Chilexpress.

HTTP 401 ou 403 dans le journal : la clé d'abonnement est incorrecte, inactive, ou elle appartient à un autre produit ou à un autre environnement. Les clés de test ne fonctionnent que si Test environment est activé.

Les tarifs de l'API ne sont pas utilisés dans une boutique dont la devise est différente : saisissez le CLP exchange rate.

Les tarifs de l'API incluent-ils l'IVA ou non ? Ils sont utilisés tels que Chilexpress les cote. Si votre boutique ajoute une taxe à la livraison et que la cotation comprend déjà l'IVA, réglez Tax sur No tax.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page du module. Cela vide les tarifs en cache et les listes de comunas.

La page indique « The Chilexpress carrier was not found » : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

La page indique « The country Chile does not exist in this shop » : ajoutez ou activez le Chili dans International > Locations > Countries, puis utilisez Add Chilean regions.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Chilexpress et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache et les listes de comunas sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) et les réglages, le journal et les services enregistrés avec les commandes sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module restaure le transporteur enregistré avec son statut précédent. Les régions chiliennes ajoutées avec Add Chilean regions restent dans la boutique.

Chilexpress est une marque de son propriétaire respectif. Ce module n'est ni affilié à Chilexpress ni approuvé par Chilexpress.