VibeFox Blue Express 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 Blue Express (pour les tarifs en temps réel uniquement) : les tarifs en temps réel nécessitent un compte e-commerce Blue Express et sa clé API (x-api-key). Demandez-la à Blue Express : developers.bluex.cl ou gpo.integraciones@bx.cl. Le service que vous utilisez (EX, PY ou MD) doit être activé dans votre contrat Blue Express. Si vous utilisez uniquement des prix fixes, vous n'avez pas besoin de clé API.
Régions chiliennes : pour un tarif en temps réel, l'adresse de livraison doit avoir une région chilienne. Si votre boutique n'a pas de régions pour le Chili, le module peut les ajouter pour vous (voir Configuration).
Points de retrait : la carte Blue Express est chargée depuis widget-pudo.blue.cl dans le navigateur du client.
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 plus tard VibeFox Blue Express dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez la clé API, le service, le code du district d'origine (par exemple SCL), le taux de change CLP si la devise de votre boutique n'est pas le CLP, et les prix fixes (par exemple CL=4500). Activez Pickup point carrier si vous voulez proposer le retrait dans les points Blue Express. Cliquez sur Save. Voir Configuration.
À l'installation, le module crée deux transporteurs : Blue Express (livraison à domicile, texte de délai de livraison Home delivery, activé) et Blue Express pickup point (texte de délai de livraison Pickup at a Blue Express point, désactivé tant que vous ne l'activez pas). Les deux sont affectés à 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. N'y définissez pas de prix : le prix provient toujours du module.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Blue Express > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Chaque enregistrement efface aussi les tarifs Blue Express et les données de communes en cache. Des avertissements apparaissent en haut de la page pour les réglages qui masqueraient les transporteurs ou le tarif en temps réel : pas de clé API, devise de la boutique différente du CLP sans taux de change, tableau de prix fixes vide, pas de régions pour le Chili, unité de poids ou de dimensions de la boutique inconnue du module (les poids sont alors lus en kg et les dimensions en cm), ou transporteur supprimé. Les valeurs non valides sont refusées avec une erreur et rien n'est enregistré : un nom de transporteur vide ou non valide, un nom de plus de 64 caractères, un nombre négatif ou non valide, ou Min weight (kg) supérieur à Max weight (kg). Les conditions et les prix ci-dessous s'appliquent aux deux transporteurs.
Général
Enable/Disable : active ou désactive le transporteur de livraison à domicile. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.
Name : le nom du transporteur affiché au paiement pour la livraison à domicile. Par défaut : Blue Express. Obligatoire, 64 caractères maximum.
Tax status : None (no tax on shipping) ou Taxable avec l'une de vos règles de taxe. Les prix Blue Express incluent l'IVA. Choisissez None si PrestaShop ne doit pas ajouter de taxe par-dessus. Cela s'applique aux deux transporteurs.
Retrait dans les points Blue Express (PUDO)
Pickup point carrier : propose la livraison dans un point Blue Express choisi par le client, comme second transporteur à côté de la livraison à domicile. Désactivé par défaut. C'est le même interrupteur que le statut du transporteur Blue Express pickup point dans Shipping > Carriers.
Pickup point name : le nom du transporteur affiché au paiement pour le retrait dans un point Blue Express. Par défaut : Blue Express pickup point. Obligatoire, 64 caractères maximum.
API Blue Express (nécessaire pour les tarifs en temps réel)
API key : votre clé API Blue Express (en-tête x-api-key). Sans elle, seuls les prix fixes sont utilisés. Après l'enregistrement, le champ reste vide et affiche A key is saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Cochez Remove the saved API key puis enregistrez pour la supprimer.
Service : le service Blue Express utilisé pour le tarif : Express (EX) (par défaut), Prioritario (PY) ou SameDay (MD). Il doit être activé dans votre contrat Blue Express.
Origin district code : le code de district Blue Express du lieu d'expédition, par exemple SCL pour Santiago (par défaut). Demandez à Blue Express en cas de doute.
CLP per 1 unit of store currency : lorsque la devise par défaut de votre boutique n'est pas le CLP, le libellé l'affiche, par exemple CLP per 1 EUR. Les prix Blue Express sont en pesos chiliens (CLP). Saisissez combien de CLP vaut une unité de la devise par défaut de votre boutique, par exemple 1050. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés. Ignoré si la devise de la boutique est le CLP.
Prix
Rate source : le mode de calcul du prix. Le tarif en temps réel nécessite une adresse chilienne avec région et commune (ville). Les erreurs sont écrites dans le journal, sans jamais être affichées au client.
Fixed prices : une ligne par pays au format COUNTRY_CODE=PRICE, dans la devise par défaut de votre boutique, hors taxes, par exemple CL=4500 dans une boutique en CLP ou CL=4.50 dans une boutique en EUR. La virgule et le point sont acceptés comme séparateur décimal. Les lignes non valides sont ignorées et listées dans un avertissement à l'enregistrement. Un pays sans ligne n'a pas de prix fixe : les transporteurs sont alors masqués pour ce pays quand le prix fixe est nécessaire. Les prix fixes peuvent être utilisés pour n'importe quel pays.
Fixed price per : Order facture le prix une seule fois. Item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'au prix fixe. Le tarif de l'API est toujours pour l'expédition complète.
Conditions
Min weight (kg) : masque les transporteurs lorsque le panier pèse moins. 0 signifie aucune limite.
Max weight (kg) : masque les transporteurs lorsque le panier pèse plus. Par défaut : 100. 0 signifie aucune limite, un champ vide signifie 100 kg. Min weight (kg) ne peut pas être supérieur à Max weight (kg).
Minimum order subtotal : affiche les transporteurs seulement à partir de ce sous-total du panier (devise de la boutique, après remises, hors taxes). Laissez vide pour les afficher toujours.
Livraison gratuite
Free shipping : active la livraison gratuite à partir d'un sous-total du panier.
Free from subtotal : le sous-total du panier (devise de la boutique, après remises, hors taxes) à partir duquel la livraison est gratuite. Utilisé uniquement lorsque Free shipping est activé.
Disponibilité sans zones d'expédition
Ignore shipping zones : propose les deux transporteurs dans toutes les zones. Les pays sont alors limités par la liste ci-dessous. Les zones créées ultérieurement sont également ajoutées. Lorsque vous désactivez à nouveau l'option, les transporteurs retrouvent les zones qu'ils avaient auparavant.
Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.
Avancé
Debug log : enregistre les requêtes et les décisions dans logs/vfd_blex_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 enregistrées. La clé API et les adresses des clients ne sont jamais enregistrées. Désactivez le journal lorsque vous avez terminé.
Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.
Remove data on uninstall : si activé, la désinstallation du module supprime les réglages et les transporteurs. Les points de retrait enregistrés dans les commandes sont conservés.
Régions chiliennes (affiché uniquement lorsque votre boutique n'a pas de régions chiliennes utilisables)
Blue Express a besoin de la région d'une adresse chilienne (RM, VS, etc.) pour le tarif en temps réel. PrestaShop n'inclut pas les régions chiliennes par défaut. Cliquez sur Add Chilean regions pour ajouter les 16 régions chiliennes comme états du Chili, avec les codes utilisés par Blue Express, et pour afficher le champ région dans le formulaire d'adresse chilienne. Les régions que vous avez déjà, par code ou par nom, ne sont pas ajoutées en double. Rien n'est modifié tant que vous ne cliquez pas sur le bouton. Vous pouvez aussi les ajouter vous-même dans International > Locations > States avec les codes RM, VS, etc.
Fonctionnement au paiement
À l'étape de livraison, PrestaShop demande au module le prix de chaque transporteur Blue Express. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module vérifie Countries (avec Ignore shipping zones), le poids du panier et le Minimum order subtotal. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Blue Express.
Pour un tarif en temps réel, l'adresse doit être au Chili, avec une région et une ville (commune). Le module demande d'abord à Blue Express de reconnaître la commune, puis demande le prix pour le service, le district d'origine, la destination et les colis. Chaque produit est envoyé avec son poids et ses dimensions convertis en kg et en cm. Les produits sans poids ni taille sont envoyés comme 0,01 kg, 10 x 10 x 10 cm. La valeur déclarée est envoyée en CLP. Le prix en CLP est converti dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.
Les tarifs sont mis en cache pendant 1 heure et les données de communes pendant 12 heures. Un appel API en échec est mémorisé pendant 5 minutes, et le délai d'attente est de 10 secondes, afin qu'une API lente ou indisponible ne ralentisse pas chaque actualisation du paiement. Les erreurs de l'API ne sont jamais affichées au client : le transporteur est masqué ou, en mode de repli, le prix fixe est utilisé. La raison est écrite dans le journal.
Si vous modifiez un 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 crée pas d'envois ni d'étiquettes dans Blue Express, n'attribue pas de numéros de suivi et n'affiche pas de mises à jour de suivi. Créez l'envoi dans votre compte Blue Express. Il n'existe pas de grilles tarifaires régionales par commune : utilisez le tarif de l'API Blue Express ou un prix fixe par pays. Les tarifs en temps réel ne fonctionnent que pour le Chili.
Points de retrait
Lorsque le client sélectionne Blue Express pickup point à l'étape de livraison, un encadré avec le bouton Choose pickup point apparaît en dessous. Le bouton ouvre la carte officielle Blue Express, où le client choisit un point. Le point choisi s'affiche avec son nom et son adresse, et le bouton devient Change pickup point. Le point est enregistré dans le panier et le tarif est recalculé avec le prix du retrait Blue Express (PUDO). Si le prix change, la page se recharge pour l'afficher. Tant qu'aucun point n'est choisi, le transporteur affiche le prix du colis en livraison à domicile.
Le client ne peut pas poursuivre sans point : Please choose a Blue Express pickup point. La boutique le vérifie lorsque le client clique sur Continue à l'étape de livraison. Un code de point mal formé est refusé avec The selected Blue Express pickup point is not valid. Please choose it again on the map., et le choix précédent est conservé.
Lorsque la commande est passée, le point est enregistré dans la commande avec son code d'agence Blue Express, son nom et son adresse. Sur la page de commande du back-office, il s'affiche dans le bloc Blue Express pickup point. Cliquez sur Edit pour choisir un autre point avec Choose on the Blue Express map ou pour saisir à la main le Agency code, le Name et l'Address, puis cliquez sur Save pickup point. La modification est enregistrée comme message privé de la commande. Modifier le point ne nécessite que des droits d'édition des commandes, pas l'accès aux pages Modules. Le client voit le point sur la page de confirmation de commande, sur la page de détail de la commande et dans l'e-mail de confirmation de commande, à côté du nom du transporteur. Le nouvel e-mail de commande envoyé à la boutique (du module Mail alerts) affiche aussi le code d'agence. Les commandes existantes conservent leurs données de point de retrait.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Blue Express est le premier bloc de Modules > Module Manager > VibeFox Blue Express > 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. En dessous figurent la ligne Product: presta-shipping-blue-express 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, les transporteurs Blue Express ne sont pas affichés aux clients au paiement et aucun tarif n'est calculé. La vitrine PrestaShop ignore que vous êtes connecté au back office : les transporteurs sont donc masqués 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, dans 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 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. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.
Dépannage
Blue Express n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable (ou Pickup point carrier) est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones et vérifiez Countries. Lisez les avertissements en haut de la page du module. Vérifiez les limites de poids, le Minimum order subtotal, et que Fixed prices contient une ligne pour le pays si vous utilisez les prix fixes ou le repli. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.
Les tarifs en temps réel n'apparaissent pas : avec Blue Express API only, les transporteurs sont masqués lorsqu'il n'y a pas de tarif. Activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Causes courantes : pas de clé API, devise de la boutique différente du CLP sans taux de change, région ou commune manquante dans l'adresse, commune non reconnue par Blue Express, ou erreur de l'API (par exemple HTTP 401 ou 403 lorsque la clé API est rejetée). Avec Blue Express API, fixed price if the API gives no rate, les clients obtiennent quand même le prix fixe pendant que vous corrigez le problème.
Les adresses chiliennes n'ont pas de région : la page affiche un avertissement sur les régions manquantes. Cliquez sur Add Chilean regions sur la page du module. Les clients dont les adresses ont été enregistrées sans région doivent modifier l'adresse et choisir la région.
Une taxe est ajoutée au prix Blue Express : les prix Blue Express incluent l'IVA. Réglez Tax status sur None (no tax on shipping).
La carte ne s'ouvre pas : la carte est chargée depuis widget-pudo.blue.cl dans le navigateur du client. Cette adresse doit donc être accessible et ne pas être bloquée sur votre site.
Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs et les données de communes en cache.
La page indique qu'un transporteur Blue Express manque : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. La réinitialisation conserve vos réglages et le statut des transporteurs.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Blue Express et choisissez Uninstall. La clé de licence, le statut de la licence et les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les deux transporteurs sont supprimés (les commandes conservent leur historique), ainsi que les réglages, le journal et les points de retrait non liés à une commande. Si l'option est désactivée, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module restaure les transporteurs avec le statut qu'ils avaient auparavant. Les points de retrait enregistrés dans les commandes ne sont jamais supprimés.
Blue Express est une marque commerciale de son propriétaire respectif. Ce module n'est ni affilié à Blue Express ni approuvé par Blue Express.