VibeFox Blue Express for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. Le plugin refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

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 n'utilisez que des prix fixes, vous n'avez pas besoin de clé API.

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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_blue_express dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Blue Express, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez la clé API, le service, le code de 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). Voir la section Configuration.

6. Allez dans WooCommerce > Settings > Shipping > Shipping zones et ajoutez VibeFox Blue Express à votre zone Chili. Dans les réglages de la méthode, choisissez le titre et le type de livraison (à domicile ou retrait dans un point Blue Express). Ajoutez-la deux fois pour proposer les deux options.

Configuration

Les réglages principaux se trouvent dans WooCommerce > Settings > Shipping > VibeFox Blue Express. Ils s'appliquent à toutes les zones d'expédition. Des avertissements concernant les réglages qui masqueraient la méthode ou le tarif en temps réel (pas de clé API, pas de taux de change CLP, tableau de prix fixes vide) s'affichent en haut de la page. L'enregistrement des réglages vide le cache.

Fenêtre de zone (lorsque vous ajoutez la méthode à une zone d'expédition)

Title: le nom de la méthode d'expédition affiché au client pour cette zone. Laissez vide pour utiliser le Name global.

Delivery type: As in the global settings (par défaut), Home delivery ou Pickup at a Blue Express point (PUDO). Ajoutez la méthode deux fois à une zone pour proposer la livraison à domicile et le retrait.

Général

Enable/Disable: active ou désactive la méthode partout, dans toutes les zones d'expédition.

Name: le nom de la méthode d'expédition affiché au paiement. Une zone peut définir son propre titre. Par défaut : Blue Express.

Tax status: les prix Blue Express incluent l'IVA. Choisissez None si WooCommerce ne doit pas ajouter de taxe en plus, ou Taxable s'il doit le faire.

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.

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). En cas de doute, demandez à Blue Express.

CLP per 1 (your currency): les prix Blue Express sont exprimés en pesos chiliens (CLP). Si votre boutique utilise une autre devise, indiquez combien de CLP vaut une unité de cette devise, par exemple 1050. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés. Ignoré lorsque la devise de votre boutique est le CLP.

Prix

Rate source: la manière dont le prix est calculé.

Fixed prices: une ligne par pays au format COUNTRY_CODE=PRICE, dans la devise de votre boutique, par exemple CL=4500 dans une boutique en CLP ou CL=4.50 dans une boutique en EUR. La virgule ou le point est accepté comme séparateur décimal. Les lignes invalides sont signalées à l'enregistrement. 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 API concerne toujours l'envoi complet.

Conditions

Min weight (kg): masque la méthode lorsque le panier pèse moins. 0 signifie pas de limite.

Max weight (kg): masque la méthode lorsque le panier pèse plus. Par défaut : 100. 0 signifie pas de limite.

Minimum order subtotal: n'affiche la méthode qu'à partir de ce sous-total de panier (devise de la boutique). Laissez vide pour l'afficher toujours.

Excluded shipping classes: si un article du panier appartient à une classe d'expédition WooCommerce sélectionnée, la méthode est masquée.

Livraison gratuite

Free shipping: active la livraison gratuite à partir d'un sous-total de panier.

Free from subtotal: le sous-total du panier (devise de la boutique) à partir duquel la livraison est gratuite.

Retrait dans les points Blue Express (PUDO)

Pickup point by default: lorsqu'elle est activée, les méthodes Blue Express livrent dans un point Blue Express choisi par le client. C'est la valeur par défaut pour les méthodes de zone dont Delivery type = As in the global settings. Le client doit choisir un point pour passer la commande.

Disponibilité sans zones d'expédition

Ignore shipping zones: propose la méthode même si elle n'est pas ajoutée à la zone d'expédition correspondante. Elle utilise alors les réglages globaux (pas de titre de zone ni de type de livraison).

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: consigne les requêtes et les décisions dans WooCommerce > Status > Logs, source « vfd-blue-express ». Les erreurs API sont toujours consignées. La clé API et les adresses des clients ne sont jamais consignées.

Remove data on uninstall: lorsqu'elle est activée, la suppression du plugin supprime ses réglages et ses méthodes de zone. La désactivation ne supprime jamais les réglages. Les points de retrait enregistrés dans les commandes sont conservés.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, le plugin vérifie le poids du panier, le Minimum order subtotal et les Excluded shipping classes. Si la livraison gratuite s'applique, le tarif est de 0 et aucune requête n'est envoyée à Blue Express.

Pour obtenir un tarif en temps réel, l'adresse doit être au Chili, avec une région et une ville (commune). Le plugin 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 dimensions 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 de votre boutique.

Les tarifs sont mis en cache pendant 1 heure et les données des 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 API ne sont jamais affichées au client : la méthode est masquée ou, en mode de repli, le prix fixe est utilisé. La raison est écrite dans le journal.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage de commandes haute performance de WooCommerce (HPOS).

Le plugin ne crée ni envois ni étiquettes chez Blue Express, n'attribue pas de numéros de suivi et n'affiche pas 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

Avec le type de livraison Pickup at a Blue Express point (PUDO), le client voit Choose pickup point sous l'option Blue Express, aussi bien au paiement classique qu'au paiement par blocs. Le bouton ouvre la carte officielle de 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 tarif est alors recalculé avec le prix du retrait Blue Express (PUDO).

La commande ne peut pas être passée sans point : le client voit Please choose a Blue Express pickup point. Cette vérification est effectuée sur le serveur.

Le point choisi est enregistré dans la commande avec son code d'agence Blue Express, son nom et son adresse. Sur l'écran de commande de l'administration, il s'affiche sous l'adresse de livraison, sous le nom Blue Express pickup point. Cliquez sur Edit pour choisir un autre point sur la carte Blue Express ou saisir à la main le code d'agence, le nom et l'adresse, puis cliquez sur Save pickup point. La modification est consignée dans une note de commande. Le client voit le point sur la page de commande et dans les e-mails de commande (HTML et texte brut). Les e-mails envoyés à la boutique affichent aussi le code d'agence. Les commandes existantes conservent leurs données de point de retrait.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Blue Express. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 sur 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, Blue Express n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin 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, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Blue Express 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 de l'adresse du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Lisez les avertissements en haut de la page des réglages. Contrôlez les limites de poids, le Minimum order subtotal et les Excluded shipping classes, ainsi que la présence d'une ligne pour le pays dans Fixed prices si vous utilisez des prix fixes ou la solution de repli.

Les tarifs en temps réel n'apparaissent pas : avec Blue Express API only, la méthode est masquée lorsqu'il n'y a pas de tarif. Activez Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs (source « vfd-blue-express »). Causes fréquentes : 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 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 continuent de recevoir le prix fixe pendant que vous corrigez le problème.

La taxe s'ajoute au prix Blue Express : les prix Blue Express incluent l'IVA. Réglez Tax status sur None si WooCommerce ne doit pas ajouter de taxe en plus.

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 : enregistrez la page des réglages. Cela vide les tarifs et les données des communes 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, puis 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, le plugin continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation du plugin conserve tous les réglages et vide seulement le cache. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence, l'état de la licence de ce plugin et le cache sont toujours supprimés. Les réglages et les méthodes de zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils restent en place pour une réinstallation ultérieure. Les points de retrait enregistrés dans les commandes ne sont jamais supprimés.

Blue Express est une marque commerciale de son titulaire respectif. Ce plugin n'est ni affilié à Blue Express ni approuvé par Blue Express.