VibeFox Loggi 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.

Compte Loggi (uniquement pour les tarifs en temps réel): le tarif en temps réel utilise l'API GraphQL de Loggi avec une clé API que Loggi délivre aux comptes professionnels. Demandez-la à votre responsable de compte Loggi ou au support d'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é API et l'ID numérique de votre boutique. Si votre compte Loggi ne dispose d'identifiants que pour la nouvelle API de la plateforme REST Loggi (identifiant client et secret), le tarif 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 d'un compte Loggi.

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_loggi-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_loggi.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_loggi-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 Loggi 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. Saisissez l'e-mail de l'API Loggi, la clé API, l'ID de boutique et l'adresse de collecte et, si la devise par défaut de votre boutique n'est pas le BRL, le taux de change BRL. Ajoutez des prix fixes en filet de sécurité (voir Configuration), activez Enable Loggi et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_loggi.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 Loggi, 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 identiques dans les deux versions.

À l'installation, l'extension crée une petite table pour les tarifs Loggi en cache. Le mode est désactivé tant que vous n'activez pas Enable Loggi et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Loggi 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 Loggi > Edit. Les sections sont listées à gauche. Elles s'appliquent à toutes les zones géographiques. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des tarifs Loggi. Si une valeur est invalide, par exemple un nombre négatif, un e-mail non valide ou un ID de boutique qui n'est pas un nombre, la page affiche une erreur et rien n'est enregistré. 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 une configuration incomplète : aucun identifiant API (seuls les prix fixes sont utilisés), aucun identifiant API ni prix fixe (le mode n'est jamais affiché), aucune adresse de collecte ou aucun taux de change BRL. Un autre avertissement apparaît lorsque la boutique n'a pas de classe de poids avec l'unité kg ou de classe de longueur avec l'unité cm, et que l'unité de la classe par défaut n'est pas reconnue. Les poids des produits sont alors comptés en kg et les dimensions en cm. Ajoutez les classes dans System > Localisation > Weight Classes et Length Classes.

Général

Enable Loggi: affiche ou masque Loggi au moment du paiement. 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 : Loggi. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

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

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

API e-mail: l'e-mail de votre compte Loggi. La clé API lui est associée. Il doit s'agir d'une adresse e-mail valide. Le vider supprime aussi la clé API enregistrée.

API key: votre clé API Loggi. Elle n'est envoyée qu'à Loggi et n'est jamais journalisée. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it; clear the API e-mail to remove it. Ne saisissez une nouvelle valeur que pour la modifier. Si vous modifiez API e-mail, saisissez aussi la clé API de la nouvelle adresse, sans quoi la page affiche une erreur et rien n'est enregistré.

Shop ID: l'ID numérique (pk) de votre boutique dans le tableau de bord Loggi, par exemple 12345. Toute autre valeur est rejetée avec une erreur.

Staging: utilisez l'environnement de test (staging) de Loggi avec des identifiants de test. Le staging et la 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. Obligatoire pour les tarifs en temps réel : l'adresse de la boutique dans OpenCart est un texte libre, elle n'est donc jamais utilisée à sa place. Sans adresse de collecte, Loggi ne peut pas estimer et seuls les prix fixes sont utilisés.

BRL exchange rate: les tarifs Loggi sont en réaux brésiliens. Si la devise par défaut de votre boutique est le BRL, ce champ n'est pas nécessaire et la page l'indique. Sinon, saisissez la valeur de 1 BRL dans la devise de votre boutique, par exemple 0.16. Sans lui, les tarifs en temps réel ne sont pas utilisés. Seul un nombre positif est accepté. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Prix fixes (dans la devise par défaut de votre boutique, hors taxes)

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é rejetée, adresse hors zone de couverture).

Price table: une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en retirer une. Choisissez * All other countries pour tous les pays sans ligne propre. Chaque ligne comporte un Base price et des colonnes 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. 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 deuxième 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 tarif Loggi en temps réel et que la grille n'a pas de ligne pour le pays de destination (et pas de ligne *). Laissez-le vide pour masquer le mode dans ce cas.

Fixed price applies: la manière dont les prix fixes sont comptés. Un tarif Loggi en temps réel couvre déjà tout le panier et n'est jamais multiplié.

Conditions

Minimum weight (kg): masque le mode en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Maximum weight (kg): masque le mode au-dessus de ce poids de panier. Par défaut : 30. 0 signifie aucune limite. Minimum weight ne peut pas être supérieur à Maximum weight.

Minimum order amount: n'affiche le mode que lorsque le sous-total des produits nécessitant une livraison (après coupon, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from: le sous-total des produits nécessitant une livraison (après coupon, avant taxes) à partir duquel la livraison Loggi est gratuite. Laissez vide s'il n'y a pas de livraison gratuite.

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Choisissez No tax si vos prix et le tarif Loggi incluent déjà les taxes.

Geo zone: proposez Loggi 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. La zone géographique n'est pas vérifiée lorsque Ignore shipping zones est activé.

Pour les limites de poids et les colonnes de poids, un produit sans poids compte pour 0 kg.

Pays

OpenCart n'a pas de zones transporteur : la Geo zone limite le mode aux adresses d'une zone géographique. Vous pouvez à la place activer Ignore shipping zones et choisir une liste de pays.

Ignore shipping zones: proposez Loggi pour les pays ci-dessous, quelle que soit la Geo zone. La zone géographique n'est pas vérifiée dans ce mode. Par défaut : désactivé.

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

Avancé

Debug log: écrit les calculs de tarifs et les requêtes vers Loggi dans storage/logs/vfd_lggi_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_lggi_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même si cette option est désactivée. La clé API et les adresses des clients ne sont jamais journalisées. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_lggi_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 Loggi et le journal. Lorsqu'elle est désactivée (par défaut), les réglages sont conservés pour une réinstallation. Les prix 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 n'est pas exportée.

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. La clé API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif Loggi. Si une Geo zone est définie, que Ignore shipping zones est désactivé et que l'adresse est en dehors de la zone géographique, Loggi 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 montant de la commande. L'extension vérifie ensuite les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Le montant de la commande 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 la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Loggi.

Pour une adresse au Brésil avec un CEP complet à 8 chiffres, l'extension construit des colis Loggi : chaque article est tourné 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 l'ID de votre boutique, l'adresse de collecte, l'adresse de livraison (rue, ville, État et CEP) et les colis, puis convertit le total Loggi de BRL vers la devise par défaut de votre boutique. Le prix est arrondi aux décimales de cette devise et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Chaque tarif 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, pour que le paiement n'attende pas Loggi à chaque rafraîchissement. Le délai d'expiration 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'il n'y a pas d'adresse de collecte, qu'un produit est plus grand qu'un colis Loggi, que le panier nécessite plus de 10 colis, ou que Loggi renvoie une erreur, un colis rejeté, une adresse hors zone de couverture ou un total nul. S'il n'existe pas non plus de prix fixe, le mode est masqué. Le client ne voit jamais d'erreur d'API. La raison est écrite dans le journal de débogage.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Loggi dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sur OpenCart 3.

L'extension calcule uniquement les prix. Elle ne crée pas de commandes ni d'envois 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 ou de casiers. 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 les envois 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 License — VibeFox Loggi est le premier bloc de Extensions > Extensions > Shipping > VibeFox Loggi > Edit, 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) et 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: opencart-shipping-loggi 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é une place de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, le mode de livraison Loggi 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), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, si bien que sans clé active le mode est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, 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 la licence.

Dépannage

Loggi n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Loggi est activé. Vérifiez Geo zone, Ignore shipping zones et Countries, les avertissements en haut de la page de l'extension, les limites de poids et le Minimum order amount. Si le client n'a pas encore saisi un CEP complet ou si Loggi ne renvoie aucun prix, le mode a besoin d'un prix fixe : une ligne pour le pays, une ligne * ou Price for countries not in the table. Vérifiez que les produits ont Requires Shipping sur Yes.

Seuls les prix fixes sont affichés : consultez le champ Log sur la page de l'extension. Les erreurs sont toujours journalisées. Activez le Debug log pour chaque étape et rechargez le paiement. Raisons habituelles : e-mail, clé ou ID de boutique API manquant, pas d'adresse de collecte, pas de BRL exchange rate pour une devise de boutique autre que le BRL, pas encore de CEP complet à 8 chiffres, un produit plus grand que 55 cm ou plus lourd que 20 kg, ou une adresse hors de la couverture Loggi.

HTTP 401 ou 403 dans le journal : Loggi a rejeté l'e-mail ou la clé API. Vérifiez-les auprès de Loggi, et vérifiez 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 par défaut de votre boutique). Les prix fixes sont toujours dans la devise par défaut de la 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.

Par article ne multiplie pas le tarif Loggi : c'est voulu. Un tarif 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 : cliquez sur Save sur la page de l'extension. Cela vide les tarifs Loggi en cache.

La page indique « Warning: You do not have permission to modify VibeFox Loggi! » : 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_loggi (OpenCart 3) ou extension/vfd_loggi/shipping/vfd_loggi (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Loggi peut être remplacée par le réglage vfd_lggi_api_url (pour les tests) ; il n'a pas de champ sur la page de réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Loggi. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Loggi, Sort order, Tax class et Geo zone. Les tarifs Loggi en cache (avec leur table) sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Loggi 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.

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

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