VibeFox Chilexpress for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

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

PHP: 8.0 ou ultérieur.

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'expédition, par exemple STGO. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de clés d'API.

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 de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_chilexpress dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Chilexpress, ou cliquez sur Settings sous le nom de l'extension 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. Remplissez le tableau des prix. 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, puis choisissez la source des tarifs (voir Configuration).

6. Ajoutez VibeFox Chilexpress à une zone de livraison pour le Chili dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Chilexpress. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne contient qu'un champ :

Title (zone): le nom de cette option de livraison au paiement pour cette zone. Laissez-le vide pour utiliser le Name global.

La page des réglages affiche 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, ou le tableau des prix n'a pas de ligne pour le Chili ni pour * Default. Chaque fois que vous enregistrez les réglages, les tarifs et les listes de comunas en cache sont effacés. Les nombres peuvent être saisis avec un point ou une virgule ; un nombre invalide n'est pas enregistré et un message d'erreur s'affiche.

Général

Enable/Disable: active ou désactive la livraison Chilexpress dans toutes les zones à la fois.

Name: le nom de la méthode de livraison affiché au client au paiement. Default: Chilexpress.

Tax status: Taxable ajoute la taxe WooCommerce au coût de livraison (si les taxes sont activées), None ne l'ajoute pas. Les tarifs de l'API Chilexpress sont utilisés exactement tels qu'ils sont cotés. Choisissez None si le tarif inclut 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 des prix optionnels par taille de colis dans la devise de votre boutique. 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 la croix pour en supprimer une. La ligne * Default s'applique aux pays sans ligne propre. Un pays sans ligne (et sans *) n'a pas de prix fixe. Une ligne dont le prix et le prix par taille valent tous deux 0 donne une livraison gratuite.

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)

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 au paiement).

Origin county code: le code county Chilexpress (comuna) d'où vous expédiez, 2 à 5 lettres, par exemple STGO (Santiago Centro), PROV (Providencia), LCON (Las Condes), VALP (Valparaíso) ou CONC (Concepción). 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 proposé est utilisé.

CLP exchange rate: Chilexpress cote en pesos chiliens. Nécessaire seulement si la devise de votre boutique n'est pas le CLP : le prix de 1 CLP dans la devise de votre boutique, par exemple 0.001. Sans lui, les tarifs de l'API ne sont pas utilisés.

Disponibilité

Min weight (kg): le poids minimal du panier pour que la méthode apparaisse. 0 signifie sans limite.

Max weight (kg): la méthode est masquée au-delà de ce poids de panier. Default: 25. 0 signifie sans limite.

Minimum subtotal: n'affiche la méthode que si le sous-total du panier (après remises, hors taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Excluded shipping classes: masque la méthode si un article du panier appartient à l'une de ces classes d'expédition WooCommerce.

Ignore shipping zones: propose la méthode pour les pays indiqués ci-dessous même si elle n'est pas ajoutée à une zone de livraison.

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

Livraison gratuite

Free shipping: active le seuil de livraison gratuite.

Free shipping from: le sous-total du panier à partir duquel la livraison est gratuite. Utilisé uniquement lorsque 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 WooCommerce > Status > Logs, source vfd-chilexpress. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. Les clés d'API ne sont jamais journalisées.

Remove data on uninstall: si activé, la suppression de l'extension efface ses réglages et ses méthodes de zone. La désactivation n'efface jamais les réglages. Les lignes de livraison des commandes existantes sont toujours conservées.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, sous-total minimal et classes d'expédition exclues. Si la livraison gratuite s'applique, le client obtient un tarif gratuit et aucune requête n'est envoyée à Chilexpress.

Pour une adresse au Chili et une source de tarifs API, l'extension prend la région et la comuna dans le champ Ville et recherche le code county Chilexpress dans la liste des comunas de cette région (API Coverage). Les accents, espaces et variantes orthographiques sont ignorés : Ñuñoa et Nunoa correspondent, et Santiago correspond à Santiago Centro. Un code county saisi dans le champ Ville est également accepté. Ensuite, l'extension envoie à l'API Rating 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 ; l'extension utilise le service choisi ou le moins cher, et convertit le montant en pesos dans la devise de votre boutique. Le nom du service est enregistré sur la ligne de livraison de la commande comme Chilexpress service.

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 prix ou une comuna inconnue, le client ne voit aucune erreur. La méthode est masquée en mode API seul, ou le prix fixe est utilisé. La raison est écrite dans le journal WooCommerce.

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

L'extension ne calcule que les tarifs. Elle 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 comuna : le client saisit la comuna dans le champ Ville standard. Les envois internationaux utilisent les prix fixes.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Chilexpress. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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-le dans votre compte vibefox.net.

Sans clé active, Chilexpress n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, avec la mention (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Chilexpress 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 du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, Minimum subtotal et Excluded shipping classes. Avec des prix fixes, vérifiez que le pays ou * Default a une ligne.

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 des réglages. Sinon, activez Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd-chilexpress. Causes fréquentes : 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 destinée à un autre produit ou environnement. Les clés de test ne fonctionnent qu'avec Test environment activé.

Les tarifs API ne sont pas utilisés dans une boutique avec une autre devise: saisissez le CLP exchange rate.

Les tarifs API incluent-ils l'IVA ? Ils sont utilisés exactement tels que Chilexpress les cote. Si votre boutique ajoute une taxe à la livraison et que le tarif inclut déjà l'IVA, réglez Tax status sur None.

Les tarifs semblent périmés après une modification: enregistrez la page des réglages. Cela efface les tarifs et les listes de comunas en cache.

Le bloc de licence affiche une erreur: suivez le message du bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et 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, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve tous les réglages ; elle efface seulement les tarifs et les listes de comunas en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence, le statut de licence de cette extension et les caches 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 sont conservés pour une réinstallation ultérieure. Les lignes de livraison des commandes existantes sont toujours conservées.

Chilexpress est une marque déposée de son titulaire respectif. Cette extension n'est ni affiliée à Chilexpress ni approuvée par Chilexpress.