VibeFox J&T Express for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

WooCommerce: 5.0 ou ultérieur, installé et actif. L'extension ne s'active pas sans lui.

PHP: 8.0 ou ultérieur.

Accès à l'API de J&T Express Malaisie (uniquement pour les tarifs en temps réel): les tarifs en temps réel n'existent que pour J&T Express Malaisie, pour les adresses de livraison en Malaisie. Il vous faut quatre valeurs. Demandez un compte VIP J&T sur le site de J&T Express Malaisie (la page de configuration contient un lien) : J&T vous fournit le code client VIP et la clé API VIP. Le compte API et la clé privée de signature des requêtes sont délivrés par J&T pour l'intégration API. Demandez-les à votre gestionnaire de compte J&T. J&T Philippines, Indonésie et les autres pays n'ont pas d'API publique de tarifs : utilisez la grille de prix pour eux. Si vous n'utilisez que la grille de prix et le coût de secours, vous n'avez pas besoin d'un accès à l'API J&T.

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_jt_express dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox J&T Express, ou cliquez sur Settings sous le nom de l'extension dans 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 la grille de prix et/ou le coût de secours. Pour les tarifs en temps réel vers la Malaisie, saisissez aussi les identifiants API de J&T, le code postal de l'expéditeur et, si la devise de votre boutique n'est pas le MYR, le taux de conversion (voir Configuration).

6. Ajoutez VibeFox J&T Express à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez des pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox J&T Express. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone): le nom que le client voit pour cette zone. Laissez-le vide pour utiliser le Method title global.

Chaque fois que vous enregistrez les réglages, les tarifs J&T en cache sont effacés. Si les tarifs en temps réel ne sont que partiellement configurés, un avertissement en haut de la page énumère les réglages manquants ou indique que le taux de conversion de devise est absent.

Général

Enable/Disable: active ou désactive le mode dans toutes les zones à la fois. Par défaut : on.

Method title: le nom du mode de livraison affiché dans le panier et au moment du paiement. Une zone peut le remplacer. Par défaut : J&T Express.

Tax status: Taxable ajoute la taxe de livraison de votre boutique au coût, None ne l'ajoute pas. Choisissez None si le prix J&T inclut déjà tout ce que vous souhaitez facturer.

API J&T Express Malaisie (tarifs en temps réel) (facultatif, pour les adresses de livraison en Malaisie ; les quatre identifiants sont requis)

VIP customer code: votre code client VIP J&T Express.

VIP API key: la clé API (mot de passe) que J&T Express vous a remise avec le code VIP. Elle n'est jamais consignée dans un journal.

API account: le nom de votre compte API J&T Express.

API private key: la clé privée du compte API. Elle sert uniquement à signer les requêtes (SHA-256). Elle n'est jamais envoyée à J&T ni consignée.

Sender postcode: le code postal malaisien d'où partent les colis. Laissez-le vide pour utiliser le code postal de la boutique défini dans WooCommerce > Settings > General, lorsque la boutique se trouve en Malaisie. Les espaces sont supprimés à l'enregistrement.

Currency conversion rate: les tarifs J&T Express Malaisie sont en MYR. Si la devise de votre boutique n'est pas le MYR, indiquez combien d'unités de votre devise vaut un MYR (1 MYR = X). Sans ce taux, les tarifs en temps réel ne sont pas utilisés ; la grille de prix ou le coût de secours s'applique à la place. Si la devise de votre boutique est le MYR, laissez-le vide : les tarifs sont utilisés tels quels. Le point décimal et la virgule décimale sont acceptés.

Grille de prix et secours (utilisée pour les pays autres que la Malaisie, lorsque les tarifs en temps réel ne sont pas configurés ou lorsque J&T ne fournit aucun tarif ; prix dans la devise de votre boutique)

Country prices: une grille avec une ligne par pays. Cliquez sur Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * Any other country pour tous les pays sans ligne propre. Chaque ligne comporte un Base price et cinq tranches de poids : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 5 kg. Un prix de tranche supérieur à 0 remplace le prix de base pour les paniers de cette tranche. Une tranche à 0 utilise le prix de base. Un prix de base de 0 signifie livraison gratuite, et un prix de base vide est enregistré comme 0. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) n'ont pas de prix de grille.

Fallback cost: le prix utilisé lorsque ni J&T ni la grille ne fournissent de prix. Laissez-le vide pour masquer le mode dans ce cas.

Table / fallback price is: Per order facture le prix une seule fois. Per item (multiplied by the number of items) le multiplie par le nombre d'articles du panier. Les tarifs J&T en temps réel portent toujours sur la commande entière.

Conditions

Free shipping from: le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Laissez-le vide s'il n'y a pas de livraison gratuite.

Minimum subtotal: n'affiche le mode que si le sous-total du panier atteint ce montant. Laissez-le vide pour l'afficher toujours.

Min weight (kg): masque le mode lorsque le panier pèse moins. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie aucune limite.

Max weight (kg): masque le mode lorsque le panier pèse davantage. Par défaut : 50. 0 signifie aucune limite.

Excluded shipping classes: masque le mode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Disponibilité sans zones de livraison

Ignore shipping zones: propose le mode pour les pays indiqués ci-dessous, même s'il n'est ajouté à aucune zone de livraison. Lorsque l'option est désactivée, le mode n'apparaît que dans les zones auxquelles il a été ajouté.

Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log: écrit les calculs de prix dans WooCommerce > Status > Logs, source vfd-jt-express. Les erreurs de l'API J&T sont toujours consignées, même si cette option est désactivée. Aucune clé, aucun mot de passe ni aucun code postal de client n'est écrit. Désactivez le journal lorsque vous avez terminé.

Remove data on uninstall: lorsqu'elle est activée, la suppression de l'extension efface ses réglages, les méthodes de zone et les tarifs en cache. Désactiver l'extension ne supprime jamais rien.

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : pays de livraison, poids du panier, sous-total minimum et classes d'expédition exclues. Si le sous-total du panier atteint Free shipping from, le mode s'affiche avec un coût de 0, mais seulement si le pays a un prix : une ligne dans Country prices, un Fallback cost ou un tarif J&T en temps réel. J&T n'est interrogé que lorsque la grille et le coût de secours ne fournissent pas de prix.

Sinon, le coût est tiré de la première source qui fournit un prix :

1. Tarif J&T en temps réel: uniquement lorsque les quatre identifiants API et un code postal d'expéditeur sont renseignés, que le pays de livraison est la Malaisie, que le client a saisi un code postal à 5 chiffres et que, pour les boutiques qui ne sont pas en MYR, un taux de conversion est défini. L'extension envoie à J&T les codes postaux de l'expéditeur et du destinataire ainsi que le poids du panier (au moins 0,1 kg) pour le service standard EZ, un colis, et convertit le prix renvoyé en MYR dans la devise de votre boutique.

2. Country prices: la ligne du pays de livraison, ou la ligne *, avec le prix de la tranche de poids du panier.

3. Fallback cost.

Si aucune de ces sources ne fournit de prix, le mode est masqué. Per item ne s'applique qu'aux prix de grille et de secours.

Chaque réponse de J&T 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 J&T à chaque actualisation. Le délai d'attente d'une requête est de 10 secondes. Si J&T renvoie une erreur, un prix nul ou aucune réponse, le client ne voit aucune erreur. Le prix de la grille ou le coût de secours est utilisé, et la raison est consignée dans le journal.

Le mode fonctionne au paiement classique et sur les blocs Panier et Paiement. Il est compatible avec le stockage haute performance des commandes (HPOS) de WooCommerce.

L'extension ne calcule que les frais de livraison. Elle ne crée ni bordereaux, ni lettres de transport, ni étiquettes, ne réserve pas d'enlèvements, n'annule ni ne suit d'envois, et ne permet pas au client de choisir un point relais. Créez et suivez vos envois dans votre compte J&T comme d'habitude. L'extension a été développée selon le format de requête de l'extension officielle de J&T Express Malaisie. Vérifiez les tarifs avec votre compte J&T avant la mise en service.

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 J&T Express. 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, J&T Express n'est pas affiché aux clients au moment du paiement. Les gestionnaires connectés de la boutique le voient toujours, marqué (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 affectées.

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

Dépannage

J&T Express n'apparaît pas au moment du paiement: vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids, Minimum subtotal et Excluded shipping classes. Vérifiez que Country prices comporte une ligne pour le pays ou une ligne *, ou que Fallback cost est renseigné. Activez le Debug log et consultez WooCommerce > Status > Logs.

Le prix provient de la grille, et non de J&T: les tarifs en temps réel nécessitent les quatre identifiants API, un code postal d'expéditeur, une adresse de livraison malaisienne avec un code postal à 5 chiffres et, pour les boutiques qui ne sont pas en MYR, le Currency conversion rate. Consultez les avertissements en haut de la page de configuration. Si J&T rejette la requête ou ne répond pas, l'erreur est consignée et le prix de la grille ou le coût de secours est utilisé. La requête échouée est relancée au bout de 10 minutes.

Pas de tarifs en temps réel pour les Philippines ou l'Indonésie: J&T ne propose pas d'API publique de tarifs pour ces pays. Utilisez-y la grille de prix et le coût de secours.

Un pays bénéficie de la livraison gratuite par erreur: sa ligne a un prix de base de 0 (un prix de base vide est enregistré comme 0). Saisissez un prix de base ou supprimez la ligne.

Les tarifs semblent obsolètes après une modification: enregistrez la page de configuration. Cela efface les tarifs J&T en cache.

Hooks pour développeurs: le filtre vfd_jtex_quote_request modifie le corps de la requête de tarif (par exemple le type de service), vfd_jtex_api_url modifie le point d'accès des tarifs, et le filtre standard woocommerce_shipping_vfd_jt_express_is_available contrôle la disponibilité.

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 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

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs lignes de livraison.

J&T Express est une marque déposée de son titulaire respectif. Cette extension n'est ni affiliée à J&T Express ni approuvée par elle.