VibeFox J&T 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.

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. Vous avez besoin de quatre valeurs. Demandez un compte VIP J&T sur le site de J&T Express Malaisie (la page du module 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 responsable de compte J&T. J&T Philippines, Indonésie et les autres pays n'ont pas d'API publique de tarifs : utilisez donc la grille de prix pour ces pays. Si vous n'utilisez que la grille de prix et le coût de secours, vous n'avez pas besoin d'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 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 VibeFox J&T Express plus tard 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 la grille de prix et/ou le coût de secours. Pour les tarifs en temps réel en Malaisie, saisissez aussi les identifiants de l'API J&T, le code postal de l'expéditeur et, si la devise par défaut de votre boutique n'est pas le MYR, le taux de conversion de devise (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur J&T Express avec le texte de délai de livraison Courier delivery. Le transporteur est associé à toutes les zones 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.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox J&T Express > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Chaque enregistrement vide aussi le cache des tarifs J&T. Si les tarifs en temps réel ne sont configurés qu'en partie, un avertissement en haut de la page indique les réglages manquants ou signale l'absence du taux de conversion de devise. Les montants qui ne sont pas un nombre égal ou supérieur à 0 sont refusés avec une erreur, de même qu'un Currency conversion rate de 0 et un Min weight supérieur à Max weight. Si l'unité de poids de votre boutique n'est pas reconnue, un avertissement vous demande de définir une unité standard dans International > Localization.

Général

Les réglages de cette page s'appliquent à toutes les zones. Les zones, les groupes de clients et les limites de taille du transporteur se définissent dans Shipping > Carriers (ou utilisez Ignore shipping zones ci-dessous).

Enable J&T Express : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et au moment du paiement. Par défaut : J&T Express. Obligatoire.

Tax : la règle de taxe du transporteur, ou No tax. Une règle de taxe ajoute la TVA sur la livraison de votre boutique au coût. Choisissez No tax si le prix J&T inclut déjà tout ce que vous voulez facturer.

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

VIP customer code : votre code VIP J&T Express. Le vider efface aussi la clé API VIP enregistrée.

VIP API key : la clé API (mot de passe) que J&T Express vous a remise avec le code VIP. Elle n'est jamais journalisée. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

API account : le nom de votre compte API J&T Express. Le vider efface aussi la clé privée enregistrée.

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 journalisée. Comme la clé API VIP, elle n'est plus affichée après l'enregistrement.

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 Shop Parameters > Contact > Stores, 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 par défaut 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 votre devise par défaut est le MYR, le champ l'indique et le taux n'est pas nécessaire : les tarifs sont utilisés tels quels. Le point et la virgule sont tous deux acceptés comme séparateur décimal. Le taux doit être supérieur à 0.

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 par défaut de votre boutique, hors taxes)

Country prices : un tableau avec une ligne par pays. Cliquez sur Add country pour ajouter une ligne et sur l'icône corbeille pour en supprimer une. Choisissez * Any other country pour tous les pays sans ligne propre. Chaque ligne contient 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. Si un pays apparaît dans deux lignes, la dernière est conservée. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) ne reçoivent aucun 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 transporteur dans ce cas. 0 signifie livraison gratuite.

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 (produits nécessitant une livraison, après remises, avant taxes) à partir duquel la livraison est gratuite. Laissez-le vide si vous ne voulez pas de livraison gratuite.

Minimum subtotal : n'affiche le transporteur que lorsque le sous-total du panier atteint ce montant. Laissez-le vide pour l'afficher en permanence.

Min weight : masque le transporteur lorsque le panier pèse moins, en kg. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie pas de limite. Il ne peut pas être supérieur à Max weight.

Max weight : masque le transporteur lorsque le panier pèse davantage, en kg. Par défaut : 50. 0 signifie pas de limite.

Disponibilité sans zones de livraison

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, même s'il n'est pas lié à leur zone. Lorsque vous l'activez, le transporteur est lié à toutes les zones actives, ainsi qu'aux zones que vous créerez plus tard. Lorsqu'il est désactivé, le transporteur n'est proposé que dans ses propres zones de Shipping > Carriers. Le désactiver rend au transporteur ses zones précédentes.

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

Avancé

Debug log : écrit les calculs de prix dans logs/vfd_jtex_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API J&T sont toujours journalisées, même avec cette option désactivée. Aucune clé, aucun mot de passe ni code postal de client n'est écrit. 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 : lorsqu'il est activé, la désinstallation du module supprime les réglages du module, le transporteur, les tarifs en cache et le journal. Lorsqu'il est désactivé, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix J&T 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 d'abord les conditions : pays de livraison (avec Ignore shipping zones), poids du panier et sous-total minimum. Si le sous-total du panier atteint Free shipping from, le prix est de 0 et aucune requête n'est envoyée à J&T.

Sinon, le coût provient 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 dont la devise par défaut n'est pas le MYR, un taux de conversion est défini. Le module 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 par défaut de votre boutique.

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

3. Coût de secours.

Si aucune de ces sources ne fournit de prix, le transporteur est masqué pour ce panier. Per item ne s'applique qu'aux prix de grille et de secours. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.

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, pour que le paiement n'attende pas J&T à chaque actualisation. Le délai d'expiration 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 grille ou de secours est utilisé, et la raison est écrite dans le journal.

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 les frais de livraison. Il ne crée ni bordereaux d'envoi, lettres de transport ou étiquettes, ne réserve pas d'enlèvements, n'annule ni ne suit d'envois, et ne permet pas aux clients de choisir un point relais. Créez et suivez vos envois dans votre compte J&T comme d'habitude. Le module a été conçu selon le format de requête du plugin officiel de J&T Express Malaisie. Vérifiez les prix avec votre compte J&T avant la mise en production.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox J&T Express est le premier bloc de Modules > Module Manager > VibeFox J&T 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-jt-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-le dans votre compte vibefox.net.

Sans clé active, le transporteur J&T Express n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back office : le transporteur est donc masqué pour vous aussi. 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 suivant 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

J&T Express n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable J&T Express est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids et Minimum subtotal. Vérifiez que Country prices contient une ligne pour le pays ou une ligne *, ou que Fallback cost est défini. Les produits peuvent aussi être limités à certains transporteurs sur leur page produit. Activez Debug log et consultez le champ Log sur la page du module.

Le prix provient de la grille, pas de J&T : les tarifs en temps réel exigent 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. Vérifiez les avertissements en haut de la page du module. Si J&T rejette la requête ou ne répond pas, l'erreur est journalisée et le prix de grille ou de secours est utilisé. La requête échouée est relancée après 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. Vérifiez aussi Free shipping from.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs J&T.

La page indique que le transporteur J&T Express est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Hooks pour développeurs : le hook actionVfdJtexQuoteRequest modifie le corps de la requête de tarif (par exemple le type de service), et actionVfdJtexApiUrl modifie le point d'entrée des tarifs.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox J&T Express et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) et les réglages et le journal sont effacés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur enregistré son statut précédent.

J&T Express est une marque commerciale de son propriétaire. Ce module n'est ni affilié à J&T Express ni approuvé par J&T Express.