VibeFox Loggi for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Compte Loggi (pour les prix en temps réel uniquement) : le prix en temps réel utilise l'API GraphQL de Loggi avec une clé d'API que Loggi délivre aux comptes professionnels. Adressez-vous à votre gestionnaire de compte Loggi ou au support intégration de Loggi (integracoes@loggi.com), voir aussi la documentation de l'API Loggi sur docs.api.loggi.com. Il vous faut trois valeurs : l'e-mail de votre compte Loggi, la clé d'API et l'identifiant numérique de votre boutique. Si votre compte Loggi ne dispose que d'identifiants pour la nouvelle API de la plateforme REST de Loggi (ID client et secret), le prix en temps réel n'est pas disponible et les prix fixes sont utilisés. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de compte Loggi.

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

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Loggi, ou cliquez sur Settings sous le nom de l'extension sur 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. Saisissez l'e-mail de l'API Loggi, la clé d'API, le Shop ID et l'adresse d'enlèvement et, si la devise de votre boutique n'est pas le BRL, le taux de change BRL. Ajoutez des prix fixes en secours (voir Configuration).

6. Ajoutez VibeFox Loggi à une zone de livraison pour le Brésil dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

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

Title (zone) : le nom que voient les clients pour cette zone. Laissez-le vide pour utiliser le Method title global.

Les avertissements en haut de la page signalent une configuration incomplète : pas d'identifiants d'API, pas d'adresse d'enlèvement ou pas de taux de change BRL. À chaque enregistrement des réglages, les prix Loggi 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 sur la page de paiement. Une zone peut le remplacer. Par défaut : Loggi.

API Loggi (prix en temps réel) (laissez les identifiants vides pour n'utiliser que des prix fixes)

API e-mail : l'e-mail de votre compte Loggi. La clé d'API appartient à ce compte.

API key : votre clé d'API Loggi. Elle n'est envoyée qu'à Loggi et n'est jamais journalisée.

Shop ID : l'identifiant numérique (pk) de votre boutique dans le tableau de bord Loggi. Seul un nombre positif est accepté. Une autre valeur est refusée avec une erreur et la valeur enregistrée est conservée.

Staging : utilise l'environnement de staging de Loggi avec des identifiants de test. Staging et production ont des comptes et des clés différents. Par défaut : désactivé.

Pickup address : l'endroit où Loggi récupère les colis, sur une seule ligne : numéro et rue, quartier, ville, État et CEP, par exemple Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Laissez-le vide pour utiliser l'adresse de la boutique de WooCommerce > Settings > General si elle se trouve au Brésil. Sans adresse d'enlèvement, Loggi ne peut pas estimer et seuls les prix fixes sont utilisés.

BRL exchange rate : les prix Loggi sont en reals 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. Sans lui, les prix en temps réel ne sont pas utilisés. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Prix fixes (dans la devise de votre boutique)

Les prix fixes sont utilisés lorsque l'API Loggi n'est pas configurée, pour les destinations hors du Brésil ou sans CEP complet, et chaque fois que Loggi ne renvoie aucun prix (API indisponible, clé refusée, adresse hors zone de couverture).

Price table : une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * All other countries pour tous les pays qui n'ont pas leur propre ligne. Chaque ligne comporte un Base price et des colonnes de poids : XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg. Une colonne de poids vide (ou à 0) utilise le prix de base. Un prix de base de 0 signifie livraison gratuite. "9.99" et "9,99" sont tous deux acceptés. Les lignes vides et une seconde ligne pour le même pays sont supprimées à l'enregistrement.

Price for countries not in the table : utilisé lorsqu'il n'y a pas de prix Loggi en temps réel et que la grille ne contient aucune ligne pour le pays de destination (ni de ligne *). Laissez-le vide pour masquer la méthode dans ce cas.

Fixed price applies : le mode de calcul des prix fixes. Un prix Loggi en temps réel couvre déjà tout le panier et n'est jamais multiplié.

Conditions

Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie pas de limite.

Maximum weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 30. 0 signifie pas de limite.

Minimum order amount : n'affiche la méthode que lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison Loggi est gratuite. Laissez vide pour ne pas proposer de livraison gratuite.

Excluded shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes de livraison WooCommerce.

Tax status : Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas. Choisissez None si vos prix et le prix Loggi incluent déjà les taxes.

Disponibilité sans zones de livraison

Ignore shipping zones : propose Loggi pour les pays indiqués ci-dessous, même si la méthode n'est ajoutée à aucune zone de livraison.

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 : journalise chaque calcul de tarif et chaque requête vers Loggi dans WooCommerce > Status > Logs (source vfd-loggi). Les erreurs de l'API sont toujours journalisées, même si cette option est désactivée. La clé d'API et les adresses des clients ne sont jamais journalisées.

Remove data on uninstall : si activé, supprimer l'extension efface tous les réglages Loggi et les méthodes de zone. Désactiver l'extension ne supprime jamais les réglages.

Fonctionnement au 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, montant minimum de commande et classes de livraison exclues. Si la livraison gratuite s'applique, le client voit la méthode sans frais et aucune requête n'est envoyée à Loggi.

Pour une adresse au Brésil avec un CEP complet à 8 chiffres, l'extension construit les colis Loggi : chaque article est orienté pour que son plus petit côté soit la hauteur, et les articles sont empilés dans un même colis tant qu'il reste dans 55 × 55 × 55 cm et 20 kg. Les produits sans poids ni dimensions comptent pour 1 cm par côté, et chaque colis pèse au moins 100 g. Loggi accepte 2 colis par estimation : les paniers plus volumineux sont donc envoyés en plusieurs requêtes et les totaux sont additionnés. L'extension envoie à Loggi votre Shop ID, l'adresse d'enlèvement, l'adresse de livraison et les colis, convertit le total Loggi de BRL dans la devise de votre boutique et l'affiche.

Chaque prix Loggi est mis en cache pendant 1 heure par panier, adresse, compte et environnement, afin que le même panier ne déclenche pas une nouvelle requête. Une estimation échouée est mise en cache pendant 10 minutes. Si Loggi est totalement injoignable, les requêtes sont suspendues pendant 2 minutes, afin que le paiement n'attende pas Loggi à chaque actualisation. Le délai d'attente de l'API est de 10 secondes.

Les prix fixes sont utilisés à la place lorsque l'API n'est pas configurée, que l'adresse est hors du Brésil ou n'a pas encore de CEP complet, que le taux de change BRL manque, qu'un produit dépasse la taille d'un colis Loggi, que le panier nécessite plus de 10 colis, ou que Loggi renvoie une erreur, un colis refusé, une adresse hors couverture ou un total nul. Si aucun prix fixe n'existe non plus, la méthode est masquée. 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 WooCommerce High-Performance Order Storage (HPOS).

L'extension ne calcule que des prix. Elle ne crée ni commandes ni expéditions Loggi, n'imprime pas d'étiquettes, ne suit pas les colis, n'affiche pas le délai de livraison au paiement et ne propose pas de points relais ni de casiers. Créez les expéditions dans le tableau de bord Loggi. Loggi ne livre qu'au Brésil. Utilisez les prix fixes pour les autres pays.

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 Loggi. 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, Loggi n'est pas affiché aux clients sur le 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. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Loggi n'apparaît pas au 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é). Contrôlez les avertissements en haut de la page des réglages, les limites de poids, Minimum order amount et Excluded shipping classes. Si le client n'a pas encore saisi de CEP complet ou si Loggi ne renvoie aucun prix, la méthode a besoin d'un prix fixe : une ligne pour le pays, une ligne * ou Price for countries not in the table.

Seuls les prix fixes s'affichent : ouvrez WooCommerce > Status > Logs, source vfd-loggi. Les erreurs sont toujours journalisées. Activez Debug log pour voir chaque étape. Raisons fréquentes : e-mail, clé ou Shop ID de l'API manquant, pas d'adresse d'enlèvement, pas de BRL exchange rate pour une devise de boutique autre que le BRL, pas encore de CEP complet à 8 chiffres, un produit de plus de 55 cm ou de plus de 20 kg, ou une adresse hors couverture Loggi.

HTTP 401 ou 403 dans le journal : Loggi a refusé l'e-mail ou la clé de l'API. Vérifiez-les auprès de Loggi et assurez-vous que Staging correspond aux identifiants : les clés de staging et de production sont différentes.

Ma boutique vend en euros ou en dollars : Loggi répond en BRL. Saisissez le BRL exchange rate (la valeur de 1 BRL dans la devise de votre boutique). Les prix fixes sont toujours dans la devise de votre boutique.

Les prix ne sont pas exacts : renseignez le poids et les dimensions de vos produits. Sans eux, les produits comptent pour 1 cm par côté et chaque colis pour au moins 100 g.

Le mode Per item ne multiplie pas le prix Loggi : c'est voulu. Un prix Loggi en temps réel couvre tout le panier. Per item ne s'applique qu'aux prix fixes.

Les prix semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les prix Loggi 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é sur le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve tous les réglages. Seuls les prix Loggi en cache sont effacés. 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 ainsi que les prix 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.

Loggi est une marque appartenant à son titulaire respectif. Cette extension n'est ni affiliée à Loggi ni approuvée par Loggi.