VibeFox Jadlog for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.
Contrat Jadlog (pour les tarifs en temps réel et les points Pickup) : les tarifs en temps réel et la liste des points Pickup proviennent de l'API Embarcador de Jadlog. Votre franchise Jadlog délivre l'accès une fois le contrat signé. Vous avez besoin du jeton de l'API Embarcador, du CNPJ (ou CPF) de l'expéditeur enregistré dans le contrat, du compte courant (conta corrente) et, si vous en avez un, du numéro de contrat. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de contrat Jadlog.
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 Jadlog 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. Collez le jeton d'API, saisissez le CNPJ, le compte courant, le numéro de contrat et le CEP d'origine, choisissez le service Jadlog et, si la devise par défaut de votre boutique n'est pas le BRL, saisissez le taux de change BRL. Ajoutez des tarifs fixes ou un coût de secours si vous le souhaitez (voir Configuration). Cliquez sur Save.
5. Pour proposer également les points Jadlog Pickup, activez Enable Jadlog Pickup et cliquez sur Save.
À l'installation, le module crée deux transporteurs : Jadlog (livraison à domicile, activé, texte du délai de livraison Jadlog delivery to your address) et Jadlog Pickup (désactivé, texte du délai de livraison Pickup at a Jadlog Pickup point). Les deux sont liés à la zone Brésil 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. N'y définissez pas de tarifs : le prix provient toujours du module.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Jadlog > Configure. Ils s'appliquent aux deux transporteurs Jadlog. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs Jadlog et les listes de points Pickup mis en cache.
En haut de la page, le module affiche des avertissements pour une configuration incomplète : pas de jeton d'API (seuls les tarifs fixes sont utilisés, et les points Pickup ne peuvent pas être listés), pas de jeton d'API ni de tarifs fixes (la méthode n'est jamais affichée), pas de CNPJ ni de compte courant, pas de CEP d'origine, pas de taux de change BRL pour une boutique qui ne vend pas en BRL, une unité de poids ou de dimensions de la boutique que le module ne connaît pas (les poids sont alors pris en kg et les dimensions en cm ; définissez les unités dans International > Localization, Local units), ou un transporteur Jadlog qui a été supprimé. Lors de l'enregistrement, les valeurs erronées sont signalées : un CEP sans 8 chiffres, un CNPJ sans 14 chiffres (ou 11 pour un CPF), un nombre non valide, un poids minimum supérieur au poids maximum (les deux poids conservent leurs valeurs enregistrées), un pays inconnu ou un tarif non valide dans le tableau des prix.
General
Enable/Disable : active ou désactive la livraison à domicile Jadlog. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.
Method title : le nom du transporteur de livraison à domicile affiché dans le panier et lors du paiement. Par défaut : Jadlog. Obligatoire.
Tax status : None ou Taxable avec l'une de vos règles de taxe. Il est enregistré pour les deux transporteurs Jadlog. Les tarifs Jadlog sont des tarifs de transport définitifs. Choisissez None si PrestaShop ne doit pas ajouter de taxe à ces tarifs.
Jadlog live prices
Les tarifs en temps réel ne sont demandés que pour les adresses au Brésil disposant d'un CEP complet à 8 chiffres.
API token : le jeton Embarcador fourni par Jadlog. Vous pouvez le coller avec ou sans le mot « Bearer ». Laissez le champ vide pour n'utiliser que des tarifs fixes. 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.
Remove the saved API token : cochez la case et cliquez sur Save pour supprimer le jeton enregistré.
CNPJ : le CNPJ (14 chiffres) ou le CPF (11 chiffres) de l'expéditeur enregistré dans le contrat Jadlog. Les points, barres obliques et tirets sont acceptés.
Current account (conta corrente) : le numéro de votre compte courant Jadlog. Sans lui et sans le CNPJ, Jadlog ne peut pas établir de devis et seuls les tarifs fixes sont utilisés.
Contract number : le numéro de votre contrat Jadlog, si votre franchise vous en a attribué un.
Origin CEP : le code postal d'où les colis sont expédiés, sur 8 chiffres. Il est enregistré au format 00000-000. Laissez le champ vide pour utiliser le code postal de la boutique défini dans Shop Parameters > Contact > Stores, si l'adresse de la boutique est au Brésil.
Jadlog service : le service (modalidade) de votre contrat pour la livraison à domicile : .Package (3, par défaut), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) ou Emergencial (14). Jadlog Pickup (40) est le second transporteur.
Insurance type : Normal (N) (par défaut) ou Own insurance policy (A - apolice), selon ce qui est convenu dans votre contrat Jadlog.
Volumetric weight : Jadlog facture le plus élevé entre le poids réel et le poids volumétrique.
BRL exchange rate : Jadlog cote en réais brésiliens. Si la devise par défaut de votre boutique est le BRL, ce champ n'est pas nécessaire. Sinon, saisissez la valeur de 1 BRL dans votre devise par défaut, par exemple 0.16. Le tarif Jadlog est multiplié par ce taux, et la valeur déclarée de la commande transmise à Jadlog est reconvertie en BRL. Sans ce taux, les tarifs en temps réel ne sont pas utilisés et seuls les tarifs fixes s'appliquent. Le point et la virgule sont tous deux acceptés comme séparateur décimal.
Delivery time : affiche le délai de livraison renvoyé par Jadlog lors du paiement, sous le transporteur Jadlog et à côté de chaque point Pickup, par exemple « Delivery time: 3 business days ». Activé par défaut. Le délai de livraison est toujours enregistré avec la commande.
Jadlog Pickup
Un second transporteur avec le service Jadlog Pickup (40). Il nécessite le jeton d'API. Sans points, le transporteur est masqué.
Enable Jadlog Pickup : active ou désactive le transporteur Jadlog Pickup. C'est le même interrupteur que son statut dans Shipping > Carriers. Désactivé après l'installation.
Jadlog Pickup carrier name : le nom de cette option lors du paiement. Par défaut : Jadlog Pickup. Obligatoire.
Points to show : le nombre de points Pickup à proposer, de 1 à 10. Par défaut : 5.
Fixed prices (utilisés lorsqu'il n'y a pas de jeton d'API, pour les pays que Jadlog ne dessert pas, et chaque fois que Jadlog ne renvoie aucun tarif)
Price per country : un tableau avec les colonnes Country, Price, XS, S, M, L et XL, dans la devise par défaut de votre boutique. Cliquez sur + Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. La colonne de taille est choisie selon 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. Price est utilisé lorsque la colonne de taille est vide. Un tarif de 0 signifie livraison gratuite pour ce pays. Utilisez * Default (other countries) pour tous les autres pays. Les lignes sans aucun tarif sont supprimées lors de l'enregistrement.
Fallback cost : utilisé lorsque ni Jadlog ni le tableau ne fournissent de tarif. Laissez le champ vide pour masquer le transporteur dans ce cas.
Fixed price applies : Per order facture le tarif une seule fois. Per item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'aux tarifs fixes et au coût de secours. Les tarifs Jadlog couvrent déjà l'ensemble du panier.
Conditions
Minimum weight (kg) : masque les transporteurs lorsque le panier pèse moins. 0 signifie aucune limite.
Maximum weight (kg) : masque les transporteurs lorsque le panier pèse plus. Par défaut : 150. 0 signifie aucune limite.
Minimum order amount : n'affiche les transporteurs que lorsque le sous-total du panier (produits soumis à livraison, après remises, avant taxes) atteint ce montant. Laissez le champ vide pour les afficher en permanence.
Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Laissez le champ vide s'il n'y a pas de livraison gratuite.
Availability without shipping zones
Ignore shipping zones : propose Jadlog pour les pays indiqués ci-dessous, même si ses transporteurs ne sont pas liés à leur zone. Lorsque vous l'activez, les deux transporteurs sont liés à toutes les zones actives, et les zones créées plus tard y sont également liées. Lorsque vous le désactivez à nouveau, les transporteurs retrouvent les zones qu'ils avaient auparavant.
Countries : les pays de destination pour ce mode, en dehors des zones propres aux transporteurs. Laissez le champ vide pour autoriser tous les pays. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.
Advanced
Debug log : enregistre chaque requête et réponse Jadlog dans logs/vfd_jdlg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours enregistrées, même lorsque cette option est désactivée. Le jeton, le CNPJ et le compte ne sont jamais enregistrés, et le CEP du client est raccourci. 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'elle est activée, la désinstallation du module supprime tous les réglages Jadlog et ses transporteurs. Lorsqu'elle est désactivée, la désinstallation désactive seulement les transporteurs. Les tarifs en cache sont toujours supprimés. Les commandes ne sont jamais modifiées.
Fonctionnement lors du paiement
À l'étape de livraison, PrestaShop demande au module le tarif de chaque transporteur Jadlog. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : poids du panier et montant minimum de commande et, avec Ignore shipping zones, les pays autorisés. Si le sous-total du panier atteint Free shipping from, la livraison est gratuite et aucune demande de tarif n'est envoyée à Jadlog.
Pour une adresse de livraison au Brésil avec un CEP complet à 8 chiffres, le module envoie à Jadlog le CEP d'origine et de destination, le poids, votre CNPJ, le compte courant, le contrat, le service, le type d'assurance et la valeur déclarée de la commande. Le tarif renvoyé est converti dans la devise par défaut de votre boutique et affiché dans la devise du panier du client. Les paniers sans poids sont calculés sur 0,1 kg. S'il n'y a pas de tarif en temps réel (pas de jeton, adresse hors du Brésil, CEP incomplet, pas de taux de change BRL, erreur Jadlog), le module utilise le tableau Price per country, puis le Fallback cost. Si aucun ne fournit de tarif, le transporteur est masqué pour ce panier.
Chaque tarif est mis 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. Si Jadlog ne répond pas, renvoie une erreur serveur ou refuse le jeton, l'API n'est plus appelée pendant 10 minutes. Le délai d'attente de l'API est de 10 secondes. Le client ne voit jamais d'erreur d'API. La raison est écrite dans le journal.
Si vous modifiez un 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 calcule uniquement les tarifs et liste uniquement les points Pickup. Il ne crée pas d'envois Jadlog, n'imprime pas d'étiquettes, ne demande pas d'enlèvements, n'annule pas d'envois et ne suit pas les colis. Il n'affiche pas de carte des points Pickup et ne demande pas de devis internationaux à Jadlog. Pour les autres pays, utilisez des tarifs fixes.
Points Pickup
Le transporteur Jadlog Pickup n'est proposé que pour les adresses au Brésil, et seulement lorsque le jeton d'API est enregistré. Lorsque le client a saisi un CEP complet à 8 chiffres, le module demande à Jadlog les points Pickup actifs les plus proches et affiche jusqu'à Points to show points sous le transporteur, chacun avec son tarif, par exemple « nom du point — tarif (3 business days) — adresse ». Si la liste n'est pas encore en cache, elle est chargée lorsque le client sélectionne le transporteur, afin que l'étape de livraison n'attende pas Jadlog.
Le tarif de chaque point est demandé à Jadlog. Si Jadlog ne fournit aucun tarif pour un point, le tarif fixe est utilisé, et un point sans aucun tarif est ignoré. Les listes de points sont mises en cache pendant 12 heures. Le tarif du transporteur est celui du point choisi. Avant qu'un point ne soit choisi, il s'agit du tarif du point le plus proche qui en a un. Un point sans tarif ne masque pas le transporteur tant que d'autres points en ont un. Une fois que le client a choisi un point, l'étape de livraison est actualisée avec le nouveau tarif.
Un point est obligatoire. Sans point, le client ne peut pas continuer et voit Please select a Jadlog Pickup point. Le module vérifie que le point figure dans la liste Jadlog pour le CEP de livraison. Si ce n'est pas le cas, le client voit The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Lorsque le CEP est incomplet, qu'il n'y a pas de points à proximité ou que Jadlog est indisponible, un message s'affiche sous le transporteur.
Sans jeton d'API, sans CEP à 8 chiffres, lorsque Jadlog est indisponible ou lorsqu'il n'y a aucun point actif à proximité, le transporteur Jadlog Pickup est masqué. Une commande sans point ne pourrait pas être expédiée.
Commandes
Lorsqu'une commande est passée avec un transporteur Jadlog, le module enregistre le service Jadlog et, si Jadlog l'a renvoyé, le délai de livraison en jours ouvrés. Pour une commande Jadlog Pickup, il enregistre aussi le nom, l'adresse et l'identifiant du point Pickup.
La page de commande de l'administration affiche un bloc Jadlog avec Jadlog service, Delivery time et, pour Jadlog Pickup, Pickup point, Pickup point address et Pickup point ID. Le client voit le point choisi sur la page de confirmation de commande et dans le détail de la commande. Le point est ajouté au nom du transporteur dans l'e-mail de confirmation de commande. L'e-mail de nouvelle commande de la boutique (si vous utilisez le module d'alertes par e-mail) contient également l'identifiant du point.
Créez vous-même l'envoi dans le système Jadlog. La commande affiche le service et l'identifiant du point Pickup dont vous avez besoin.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox achetée sur vibefox.net. Le bloc de licence License — VibeFox Jadlog est le premier bloc de la page Modules > Module Manager > VibeFox Jadlog > 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-jadlog 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. Supprimer 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, les transporteurs Jadlog ne sont pas affichés aux clients lors du paiement et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office ; les transporteurs sont donc masqués pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais vous ne pouvez pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, dans 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 l'assistance 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 après 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 licence.
Dépannage
Jadlog n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable/Disable (ou Enable Jadlog Pickup) est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, ou activez Ignore shipping zones. Consultez les avertissements en haut de la page du module, les limites de poids et le Minimum order amount. Si le client n'a pas encore saisi un CEP complet à 8 chiffres, seuls les tarifs fixes peuvent être utilisés : ajoutez alors une ligne dans Price per country ou un Fallback cost. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.
Seuls des tarifs fixes sont affichés : activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Il indique la raison : pas de CNPJ ni de compte courant, pas de CEP d'origine, CEP de destination incomplet, pas de taux de change BRL, ou le message d'erreur de Jadlog.
HTTP 401 ou 403 dans le journal : Jadlog a refusé le jeton d'API. Vérifiez-le auprès de votre franchise Jadlog. L'API est suspendue pendant 10 minutes après cette erreur. L'enregistrement des réglages lève la suspension, vous pouvez donc réessayer immédiatement.
Les points Pickup n'apparaissent pas : le transporteur Jadlog Pickup nécessite Enable Jadlog Pickup, le jeton d'API et un CEP complet à 8 chiffres au Brésil. Si Jadlog n'a aucun point actif près du CEP, le transporteur est masqué. Consultez le journal pour en connaître la raison.
Les tarifs sont en réais au lieu de ma devise : saisissez le BRL exchange rate (la valeur de 1 BRL dans la devise par défaut de votre boutique).
Les tarifs semblent trop bas ou trop élevés : renseignez les poids et les dimensions des produits. Les paniers sans poids sont calculés sur 0,1 kg, et le poids volumétrique nécessite des dimensions.
Une taxe est ajoutée aux tarifs Jadlog : réglez Tax status sur None.
Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs Jadlog et les listes de points Pickup mis en cache.
La page indique qu'un transporteur Jadlog est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Jadlog et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. Les tarifs en cache et les listes de points Pickup sont toujours supprimés. Si Remove data on uninstall est activé, les deux transporteurs sont supprimés (les commandes conservent leur historique), et les réglages et le journal sont effacés. S'il est désactivé, les transporteurs sont seulement désactivés et tous les réglages sont conservés. Réinstaller le module rend aux transporteurs le statut qu'ils avaient. Le service Jadlog, le délai de livraison et le point Pickup enregistrés avec les commandes sont toujours conservés.
Jadlog est une marque déposée de son propriétaire. Ce module n'est ni affilié à Jadlog ni approuvé par Jadlog.