VibeFox Jadlog for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 5.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
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é. Il vous faut le jeton de l'API Embarcador, le CNPJ (ou CPF) de l'expéditeur enregistré dans le contrat, le compte courant (conta corrente) et, si vous en avez un, le numéro de contrat. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de contrat Jadlog.
Clé de licence VibeFox : à acheter 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 transférer le dossier vfd_jadlog dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Jadlog, 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. Collez le jeton de l'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 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).
6. Ajoutez VibeFox Jadlog à une zone de livraison pour le Brésil dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays. Pour proposer aussi les points Jadlog Pickup, ajoutez la méthode une seconde fois à la zone et choisissez Pickup (40) comme service.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Jadlog. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone comporte deux champs :
Title (zone) : le nom que voit le client pour cette zone. Laissez-le vide pour utiliser le Method title général.
Jadlog service (zone) : le service de cette méthode de zone. Same as the global setting utilise le service de la page de réglages principale. Ajoutez la méthode deux fois pour proposer, par exemple, la livraison à domicile (.Package) et les points Jadlog Pickup dans la même zone.
Lorsque le titre de la zone est vide et que le service est Pickup, le mot « Pickup » est ajouté au titre général, afin que les deux méthodes aient des noms différents.
En haut de la page de réglages, l'extension affiche des avertissements si la configuration est incomplète : pas de jeton d'API, pas de CNPJ ni de compte courant, pas de CEP d'origine, ou pas de taux de change BRL pour une boutique qui ne vend pas en BRL. À chaque enregistrement des réglages, les tarifs Jadlog et les listes de points Pickup en cache sont effacés.
Général
Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois.
Method title : le nom de la méthode de livraison affiché dans le panier et lors du paiement. Par défaut : Jadlog. Une zone peut le remplacer.
Tarifs Jadlog en temps réel
Les tarifs en temps réel ne sont demandés que pour les adresses au Brésil avec 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 vide pour n'utiliser que des tarifs fixes.
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. L'extension vous avertit si le nombre de chiffres est incorrect.
Current account (conta corrente) : le numéro de votre compte courant Jadlog. Sans lui et sans le CNPJ, Jadlog ne peut pas établir de tarif 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ù partent les colis, sur 8 chiffres. Il est enregistré au format 00000-000. Laissez-le vide pour utiliser le code postal de la boutique défini dans WooCommerce > Settings > General, si l'adresse de la boutique est au Brésil.
Jadlog service : le service (modalidade) de votre contrat : .Package (3, par défaut), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12), Emergencial (14) ou Pickup (40). Pickup propose les points Jadlog Pickup proches du client. Une méthode de zone peut utiliser un autre service.
Insurance type : Normal (N) (par défaut) ou Own insurance policy (A — apólice), 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 de votre boutique est le BRL, ce champ n'est pas nécessaire. Sinon, saisissez la valeur de 1 BRL dans la devise de votre boutique, par exemple 0.16. Le tarif Jadlog est multiplié par ce taux, et la valeur déclarée de la commande envoyée à Jadlog est reconvertie en BRL. Sans 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 à côté du titre de la méthode, par exemple « Jadlog (3 jours ouvrés) ». Activé par défaut. Le délai de livraison est toujours enregistré dans la commande.
Points Jadlog Pickup (utilisés par le service Pickup (40) ; nécessitent le jeton de l'API)
Points to show : nombre de points Pickup à proposer, de 1 à 10. Par défaut : 5.
Tarifs fixes (utilisés en l'absence 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 de votre boutique. Cliquez sur + Add country pour ajouter une ligne et sur la croix 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 comme pays pour tous les autres pays. Les lignes sans aucun tarif sont supprimées à l'enregistrement.
Fallback cost : utilisé lorsque ni Jadlog ni le tableau ne fournissent de tarif. Laissez-le vide pour masquer la méthode dans ce cas.
Fixed price applies : Per order facture le tarif une seule fois. Per item (price × quantity) le multiplie par le nombre d'articles du panier. Cela ne concerne que les tarifs fixes et le coût de secours. Les tarifs Jadlog couvrent déjà l'ensemble du panier.
Conditions
Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie aucune limite.
Maximum weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 150. 0 signifie aucune limite.
Minimum order amount : n'affiche la méthode que si le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez-le vide pour toujours l'afficher.
Excluded shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.
Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Laissez-le vide pour ne pas proposer de livraison gratuite.
Tax status : Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas. Les tarifs Jadlog sont des tarifs transporteur définitifs. Choisissez None si WooCommerce ne doit pas y ajouter de taxe.
Disponibilité sans zones de livraison
Ignore shipping zones : propose Jadlog pour les pays ci-dessous même si la méthode n'est ajoutée à aucune zone de livraison. Dans ce mode, le Jadlog service général est utilisé.
Countries : les pays de destination pour ce mode. Laissez-le 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 : enregistre chaque requête et réponse Jadlog dans WooCommerce > Status > Logs, source vfd-jadlog. 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é.
Remove data on uninstall : si activé, la suppression de l'extension efface tous les réglages Jadlog et toutes les méthodes de zone. La désactivation de l'extension ne supprime jamais les réglages. Les tarifs en cache sont toujours supprimés.
Fonctionnement lors du 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, montant minimum de commande et classes d'expédition exclues. 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, l'extension envoie à Jadlog les CEP d'origine et de destination, le poids, votre CNPJ, votre compte courant, le contrat, le service, le type d'assurance et la valeur déclarée de la commande, puis affiche le tarif renvoyé dans la devise de votre boutique. Les paniers sans poids sont calculés sur la base de 0,1 kg. S'il n'existe pas de tarif en temps réel (pas de jeton, adresse hors du Brésil, CEP incomplet, pas de taux de change BRL, erreur de Jadlog), l'extension utilise le tableau Price per country, puis le Fallback cost. Si aucun ne fournit de tarif, la méthode est masquée 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 de l'API. La raison est écrite dans le journal.
La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension calcule uniquement les tarifs et liste les points Pickup. Elle 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. Elle n'affiche pas de carte des points Pickup et ne demande pas à Jadlog de devis internationaux. Utilisez des tarifs fixes pour les autres pays.
Points Pickup
Une méthode avec le service Pickup (40) n'est proposée que pour les adresses au Brésil. Lorsque le client a saisi un CEP complet à 8 chiffres, l'extension demande à Jadlog les points Pickup actifs les plus proches et propose jusqu'à Points to show points. Chaque point est une option de livraison distincte, avec son propre tarif, par exemple « Jadlog Pickup : nom du point — adresse ». Le client choisit un point en sélectionnant l'option de livraison, que ce soit sur le paiement classique ou sur les blocs Panier et Paiement.
Le tarif jusqu'à chaque point est demandé à Jadlog. Si Jadlog ne donne 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.
Sans jeton d'API, sans CEP complet à 8 chiffres, lorsque Jadlog est indisponible ou lorsqu'il n'y a aucun point actif à proximité, la méthode Pickup est masquée. Une commande sans point ne pourrait pas être expédiée.
Commandes
La ligne de livraison de la commande conserve le service Jadlog et, lorsque Jadlog l'a renvoyé, le délai de livraison en jours ouvrés. Pour une commande Pickup, le nom de la ligne de livraison contient le nom et l'adresse du point, et la commande enregistre aussi le nom, l'adresse et l'identifiant du point Pickup. Vous les voyez sous la ligne de livraison dans l'écran d'administration de la commande. Le client voit le point choisi sur la page de remerciement et dans les e-mails de commande.
Enregistrez 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 pour cela.
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 Jadlog. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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, Jadlog n'est pas affiché aux clients lors du paiement. Les gestionnaires de la boutique connectés 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 l'assistance nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Jadlog n'apparaît pas lors du 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é). Vérifiez les avertissements en haut de la page de réglages, les limites de poids, Minimum order amount et Excluded shipping classes. Si le client n'a pas encore saisi de CEP complet à 8 chiffres, seuls les tarifs fixes peuvent être utilisés ; ajoutez donc une ligne dans Price per country ou un Fallback cost.
Seuls des tarifs fixes sont affichés : activez le Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd-jadlog. Le journal 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 de l'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 : la méthode Pickup nécessite le jeton de l'API et un CEP complet à 8 chiffres au Brésil. Si Jadlog n'a aucun point actif près du CEP, la méthode est masquée. 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 de votre boutique).
Les tarifs semblent trop bas ou trop élevés : renseignez les poids et dimensions des produits. Les paniers sans poids sont calculés sur la base de 0,1 kg, et le poids volumétrique nécessite les dimensions.
Les tarifs semblent obsolètes après une modification : enregistrez la page de réglages. Cela efface les tarifs Jadlog et les listes de points Pickup en cache.
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 état connu.
Désinstallation
La désactivation de l'extension conserve tous les réglages et toutes les méthodes de zone. Seuls les tarifs en cache et les listes de points Pickup sont effacés. Pour supprimer l'extension, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de licence de cette extension, ainsi que les tarifs en cache, 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 commandes existantes conservent leurs lignes de livraison avec le service Jadlog et le point Pickup.
Jadlog est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Jadlog ni approuvée par Jadlog.