VibeFox J&T Express for OpenCart — Aide

Prérequis

OpenCart: 3.0.x (testé en 3.0.5.0) ou 4.0.2 et ultérieur (testé en 4.1.0.3).

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 l'extension 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-y la grille de prix. 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

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_jt_express-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_jt_express.ocmod.zip. N'installez que le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_jt_express-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD, vous n'avez donc pas besoin d'actualiser Extensions > Modifications. Au lieu de l'Installer, vous pouvez copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox J&T Express et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton au crayon) pour ouvrir la page de réglages.

4. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Renseignez la grille de prix et/ou le coût de secours. Pour les tarifs en temps réel en Malaisie, saisissez aussi les identifiants API J&T, le code postal de l'expéditeur et, si la devise par défaut de votre boutique n'est pas MYR, le taux de conversion (voir Configuration). Activez Enable J&T Express et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_jt_express.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées, sur la même page. Cliquez sur Install (le bouton vert +) à côté de celui-ci.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox J&T Express, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton au crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page de réglages et ses champs sont les mêmes dans les deux versions.

Après l'installation, le mode est désactivé tant que vous n'activez pas Enable J&T Express et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages J&T Express que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des tarifs J&T. Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison : un titre de mode invalide, un montant qui n'est pas un nombre supérieur ou égal à 0, un Currency conversion rate égal à 0, un Min weight (kg) supérieur à Max weight (kg), ou un ordre de tri qui n'est pas un nombre entier. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Les avertissements au-dessus des réglages (réaffichés après chaque enregistrement) signalent que les tarifs en temps réel ne sont que partiellement configurés : ils listent les réglages API manquants, ou indiquent que la devise de votre boutique n'est pas MYR et que le taux de conversion manque. Un autre avertissement apparaît si votre boutique n'a pas de classe de poids avec l'unité kg dans System > Localisation > Weight Classes. Les poids des produits sont alors convertis selon le nom de leur unité (kg, g, lb, oz), et les autres unités sont lues comme des kg.

Général

Le mode est proposé pour la zone géographique choisie, ou pour les pays de Ignore shipping zones. Les réglages de cette page s'appliquent à toutes les zones.

Enable J&T Express: affiche ou masque le mode au moment du paiement (l'état de cette extension). Par défaut : désactivé.

Method title: le nom du mode de livraison affiché au client dans le panier et au paiement. Par défaut : J&T Express. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Une classe de taxe ajoute votre taxe de livraison au coût. Choisissez No tax si le prix J&T inclut déjà tout ce que vous voulez facturer.

Sort order: la position du mode parmi les modes de livraison au paiement. Un nombre entier.

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

Le tarif est demandé à J&T Express Malaisie pour chaque code postal malaisien et mis en cache pendant une heure. Sans les identifiants, et pour les autres pays, la grille de prix et le coût de secours sont utilisés.

VIP customer code: votre code VIP J&T Express. Le vider supprime 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. Pour la supprimer, videz VIP customer code et enregistrez.

API account: le nom de votre compte API J&T Express. Le vider supprime 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. Pour la supprimer, videz API account et enregistrez.

Sender postcode: le code postal malaisien d'où les colis sont expédiés, par exemple 50000. Obligatoire pour les tarifs en temps réel : l'adresse de la boutique dans OpenCart est un texte libre, le code postal n'est donc jamais pris depuis celle-ci.

Currency conversion rate: les tarifs J&T Express Malaisie sont en MYR. Si la devise par défaut de votre boutique n'est pas MYR, indiquez combien d'unités de votre devise vaut 1 MYR (1 MYR = X), par exemple 0.20. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés, et on utilise la grille de prix ou le coût de secours. Si votre devise par défaut est MYR, le champ l'indique et n'est pas nécessaire : les tarifs sont utilisés tels quels. Le taux doit être supérieur à 0.

Grille de prix et coût de secours (utilisés 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: une grille avec une ligne par pays. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en retirer 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. 0 signifie livraison gratuite.

Table / fallback price is: Per order (par défaut) 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 le coupon, hors taxes) à partir duquel la livraison est gratuite. Laissez vide s'il n'y a pas de livraison gratuite.

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

Min weight (kg): masque le mode lorsque le panier pèse moins. Les poids des produits sont convertis avec leur classe de poids. 0 signifie aucune limite (par défaut). Ne peut pas être supérieur à Max weight (kg).

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

Geo zone: proposer le mode uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisée lorsque Ignore shipping zones est activé.

Disponibilité sans zones de livraison

Ignore shipping zones: proposer le mode pour les pays ci-dessous, quelle que soit la zone géographique. Par défaut : désactivé.

Countries: les pays de destination pour ce mode, choisis parmi les pays activés dans votre boutique. Laissez vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log: écrit les calculs de prix dans storage/logs/vfd_jtex_debug.log.php (sous OpenCart 4, system/storage/logs/vfd_jtex_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API J&T sont toujours journalisées, même si cette option est désactivée. Aucune clé, aucun mot de passe, le code client ni les codes postaux des clients ne sont écrits. Désactivez le journal une fois terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_jtex_debug.old.log.php et un nouveau journal commence.

Log: affiche la taille et les dernières entrées du journal de débogage. Cliquez sur Clear log pour le vider.

Remove data on uninstall: lorsqu'elle est activée, la désinstallation de l'extension supprime les réglages J&T Express et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les tarifs en cache sont toujours supprimés.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé API VIP et la clé privée ne sont pas exportées.

Import: collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Les clés enregistrées sont conservées.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix J&T Express. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse est en dehors, le mode n'est pas proposé. Seuls les produits dont Requires Shipping est sur Yes sont pris en compte : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. L'extension vérifie ensuite les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et sous-total minimum. Le sous-total correspond au prix des produits nécessitant une livraison, après la remise du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. Si le sous-total atteint Free shipping from, le prix est 0 et aucune requête n'est envoyée à J&T.

Sinon, le coût est pris dans 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 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 en MYR renvoyé dans votre devise par défaut.

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 mode est masqué pour ce panier. Per item ne s'applique qu'aux prix de grille et de secours. Le prix est calculé dans votre devise par défaut, arrondi à ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

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 rafraîchissement. Le délai d'expiration des requêtes 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 prix de secours est utilisé, et la raison est écrite dans le journal.

Sous OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement et choisit J&T Express dans la fenêtre Shipping method options. Le mode fonctionne de la même manière que sous OpenCart 3.

L'extension calcule uniquement les frais de livraison. Elle ne crée pas de lettres de transport, de bordereaux ou d'étiquettes, ne réserve pas d'enlèvements, n'annule ni ne suit les envois, et ne permet pas au client de choisir un point relais. Elle n'ajoute rien aux commandes : la commande affiche le titre du mode et le coût de livraison comme pour tout autre mode OpenCart. Créez et suivez les envois dans votre compte J&T comme d'habitude. L'extension a été développée selon le format de requête de l'intégration officielle de J&T Express Malaisie. Confirmez les prix auprès de votre compte J&T avant la mise en production.

Clé de licence

L'extension 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 Extensions > Extensions > Shipping > VibeFox J&T Express > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: opencart-shipping-jt-express et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify pour l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier état connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique dans la configuration d'OpenCart. 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, le mode de livraison J&T Express n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), ce qui vous permet de configurer et de tester l'extension avant d'acheter une clé. Sous OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode est masqué pour tout le monde. Une fois la page Edit ouverte une fois, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. 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é de nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

J&T Express n'apparaît pas au paiement : vérifiez que la licence est active et que Enable J&T Express est activé. Vérifiez la Geo zone (ou que Ignore shipping zones est activé et que le pays figure dans Countries), les limites de poids et le Minimum subtotal. Vérifiez que Country prices contient une ligne pour le pays ou une ligne *, ou que Fallback cost est défini. Vérifiez que les produits ont Requires Shipping sur Yes. Activez le Debug log et consultez le champ Log sur la page de l'extension.

Le prix vient 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 en Malaisie avec un code postal à 5 chiffres et, pour les boutiques hors MYR, le Currency conversion rate. Vérifiez les avertissements en haut de la page de l'extension. 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 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 obtient 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 de l'extension. Cela vide le cache des tarifs J&T.

La page indique « Warning: You do not have permission to modify VibeFox J&T Express! » : le groupe d'utilisateurs de votre administration ne peut peut-être que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_jt_express (OpenCart 3) ou extension/vfd_jt_express/shipping/vfd_jt_express (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : d'autres extensions peuvent modifier le corps de la requête de tarif (par exemple le type de service) avec l'événement OpenCart vfd_jt_express/quote_request, et l'adresse du point d'accès des tarifs avec vfd_jt_express/api_url.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox J&T Express. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable J&T Express, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages J&T Express et le journal de débogage sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation. Les commandes existantes conservent leur mode de livraison et leur coût.

Sous OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox J&T Express dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléversé.

J&T Express est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à J&T Express ni approuvée par J&T Express.