VibeFox GIG Logistics for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Identifiants de l'API GIG Logistics (uniquement pour les prix en temps réel) : les prix en temps réel utilisent l'API tierce de GIG Logistics. GIG Logistics délivre aux clients professionnels un nom d'utilisateur API (généralement une adresse e-mail) et un mot de passe. Demandez-les sur la page développeur de GIG Logistics (giglogistics.com/developer). Les identifiants de test ne fonctionnent qu'avec l'API de test. Si vous n'utilisez que le tableau de prix et le coût de secours, vous n'avez pas besoin d'identifiants API.

Nigeria dans votre boutique : les prix en temps réel ne sont demandés que pour les adresses de livraison au Nigeria. OpenCart contient déjà le pays Nigeria avec ses 37 États ; il doit être activé dans System > Localisation > Countries.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_gig_logistics-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_gig_logistics.ocmod.zip. N'installez que le paquet de 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_gig_logistics-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'installateur, vous pouvez aussi 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 GIG Logistics et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des 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. Remplissez le tableau de prix et/ou le coût de secours. Pour les prix en temps réel, saisissez aussi le nom d'utilisateur et le mot de passe de l'API, le téléphone d'enlèvement, la rue, la ville et l'État, ainsi que le taux de conversion de devise si votre devise par défaut n'est pas le NGN (voir Configuration). Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_gig_logistics.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 GIG Logistics, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

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

Après l'installation, la méthode reste désactivée tant que vous n'avez pas activé Enable/Disable et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit. Les sections sont listées à gauche. Un seul bouton Save, en bas, enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les prix GIG Logistics, les jetons API et les coordonnées des adresses en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

En haut de la page, et de nouveau après chaque enregistrement, l'extension affiche des avertissements lorsque les prix en temps réel ne peuvent pas être utilisés : seul l'un du nom d'utilisateur ou du mot de passe API est saisi, Sender phone ou la ville et l'État d'enlèvement manquent, ou votre devise par défaut n'est pas le NGN et aucun Currency conversion rate n'est défini. Elle signale aussi si votre boutique n'a pas de classe de poids avec l'unité kg (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 kg. À l'enregistrement, une valeur incorrecte est signalée (un montant négatif, un Currency conversion rate de 0, une latitude hors de -90 à 90, une longitude hors de -180 à 180), de même qu'un Min weight (kg) supérieur à Max weight (kg), un Method title vide ou invalide, une valeur de tri qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue ; rien n'est alors enregistré.

Général

La méthode est proposée pour la zone géographique sélectionnée dans Conditions, ou pour les pays de Ignore shipping zones. Les réglages de cette page s'appliquent à toutes les zones.

Enable/Disable : affiche ou masque GIG Logistics au moment du paiement (l'état de cette extension). Par défaut : désactivé.

Method title : le nom de la méthode d'expédition affiché dans le panier et lors du paiement. Par défaut : GIG Logistics. Obligatoire, de 1 à 64 caractères, sans les caractères < > ; = # { }.

Tax class : la classe de taxe du coût d'expédition, ou No tax. Une classe de taxe ajoute votre taxe d'expédition au coût. Choisissez No tax si le prix GIG comprend déjà tout ce que vous voulez facturer.

Sort order : la position de la méthode parmi les méthodes d'expédition. Un nombre entier.

API GIG Logistics (prix en temps réel) (facultatif)

Avec des identifiants API, le prix est demandé à GIG Logistics pour chaque adresse nigériane et mis en cache pendant une heure. Sans identifiants, ou lorsque l'API ne renvoie aucun prix, le tableau de prix et le coût de secours sont utilisés. La section contient un lien vers la page développeur de GIG Logistics.

API username : votre nom d'utilisateur de l'API tierce GIG Logistics, généralement votre adresse e-mail.

API password : votre mot de passe de l'API tierce GIG Logistics. Il sert uniquement à la connexion à l'API et n'est jamais journalisé. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. To remove it, clear the API username and save. Ne saisissez une nouvelle valeur que pour la modifier.

Test mode : utilise l'API de test (dev) de GIG Logistics. Les identifiants de test ne fonctionnent qu'avec l'API de test. Désactivez-le pour obtenir des prix réels. Par défaut : désactivé.

Currency conversion rate : GIG Logistics renvoie les prix en NGN. Si la devise par défaut de votre boutique n'est pas le NGN, saisissez la valeur d'un NGN dans votre devise par défaut (1 NGN = ? de votre devise, par exemple 0.0006). Le taux doit être supérieur à 0. Sans lui, les prix GIG en temps réel ne sont pas utilisés. Si votre devise par défaut est le NGN, le champ l'indique et il n'est pas nécessaire.

Adresse d'enlèvement (expéditeur)

Lieu où GIG Logistics récupère les colis, au Nigeria. OpenCart n'a pas d'adresse de boutique structurée, saisissez donc ici la rue et la ville. Lorsque le pays de votre boutique est le Nigeria, un State vide utilise la région de la boutique définie dans System > Settings > Store > Local.

Sender name : le nom de l'expéditeur transmis à GIG Logistics. Vide signifie le nom de la boutique.

Sender phone : votre numéro de téléphone, par exemple 08030000000. GIG Logistics l'exige pour les prix en temps réel.

Street address : la rue de l'enlèvement, par exemple 1 Adeola Odeku Street.

City / area : la ville ou le quartier de l'enlèvement, par exemple Victoria Island. Obligatoire pour les prix en temps réel.

State : l'État nigérian de l'adresse d'enlèvement, choisi parmi les 37 États. L'option par défaut, Store region (System > Settings > Store > Local), utilise la région de votre boutique lorsque celle-ci est au Nigeria. Obligatoire pour les prix en temps réel.

Pickup latitude : latitude cartographique facultative du point d'enlèvement, par exemple 6.4281. GIG Logistics calcule les prix en fonction de la distance. Vide signifie que les coordonnées sont recherchées à partir de l'adresse.

Pickup longitude : longitude cartographique facultative du point d'enlèvement, par exemple 3.4219.

Address lookup : recherche les coordonnées cartographiques des adresses avec OpenStreetMap (Nominatim). GIG Logistics calcule le prix à partir des coordonnées d'enlèvement et de livraison. La rue, la ville et l'État du client sont envoyés à nominatim.openstreetmap.org, et les résultats sont mis en cache pendant 30 jours. Sans cette option, seul le texte de l'adresse est envoyé, et GIG Logistics peut ne pas renvoyer de prix. Par défaut : activé.

Tableau de prix et secours

Utilisé pour les autres pays, lorsque les prix en temps réel ne sont pas configurés ou lorsque GIG Logistics ne renvoie aucun prix. Les prix sont exprimés dans la devise par défaut de votre boutique, hors taxes.

Country prices : un tableau avec un prix de base par pays. Cliquez sur Add country pour ajouter une ligne. Choisissez * Any other country pour tous les pays sans ligne propre. Les colonnes XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg sont des prix facultatifs par tranche de poids : un prix de tranche supérieur à 0 remplace le prix de base pour les paniers de cette tranche. Un prix de 0 signifie livraison gratuite. Les cellules de prix vides ou invalides sont enregistrées comme 0 ; renseignez donc le prix de base de chaque ligne ajoutée. Les valeurs corrigées sont listées après l'enregistrement, dans un avertissement qui commence par Country prices:. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) n'obtiennent aucun prix du tableau.

Fallback cost : utilisé lorsque ni GIG Logistics ni le tableau ne donnent de prix. Vide signifie que la méthode est masquée dans ce cas.

Table / fallback price is : Per order facture le prix une seule fois. Per item (multiplied by the number of items) le multiplie par le nombre d'articles du panier. Les prix GIG en temps réel s'appliquent toujours à la commande entière.

Conditions

Free shipping from : le sous-total du panier (produits nécessitant une expédition, après le coupon, hors taxes) à partir duquel la livraison est gratuite. Vide signifie jamais gratuite.

Minimum subtotal : n'affiche la méthode que lorsque le sous-total du panier atteint ce montant. Vide signifie toujours.

Min weight (kg) : le poids minimum du panier en kg. Les poids des produits sont convertis avec leur classe de poids. 0 signifie aucune limite.

Max weight (kg) : le poids maximum du panier en kg. Par défaut : 30. 0 signifie aucune limite.

Geo zone : proposez la méthode uniquement pour les adresses de cette zone géographique. All zones signifie aucune limite. Non utilisé avec Ignore shipping zones. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Disponibilité sans zones d'expédition

Ignore shipping zones : proposez la méthode pour les pays indiqués ci-dessous, quelle que soit la zone géographique. La Geo zone de Conditions n'est alors pas vérifiée.

Countries : les pays de destination pour ce mode, choisis parmi les pays activés de votre boutique. Vide signifie tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log : écrit les calculs de prix dans storage/logs/vfd_gigl_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_gigl_debug.log.php). Le fichier n'est pas lisible depuis le web. Les erreurs de l'API et de recherche d'adresse sont toujours journalisées, même lorsque le journal est désactivé. Aucun mot de passe, jeton ni adresse de client n'est écrit. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_gigl_debug.old.log.php et un nouveau journal est démarré.

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 et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les prix en cache sont toujours supprimés. Les commandes sont toujours conservées.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le mot de passe de l'API n'est pas exporté.

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. Le mot de passe de l'API enregistré est conservé.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les méthodes d'expédition, il demande à l'extension le prix GIG Logistics. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, la méthode n'est pas proposée. Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Le sous-total correspond au prix de ces produits après la remise du coupon, hors taxes. Les cartes-cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. L'extension vérifie d'abord les conditions : le pays de livraison (avec Ignore shipping zones), le poids du panier et le sous-total minimum. Si le sous-total atteint Free shipping from, le prix est de 0 et aucune requête n'est envoyée à GIG Logistics.

Ensuite, le prix provient de la première source qui en fournit un. D'abord, le prix GIG Logistics en temps réel, si des identifiants API sont saisis, que l'adresse se trouve au Nigeria, qu'elle comporte une ville ou un État, que le téléphone, la ville et l'État d'enlèvement sont renseignés, et qu'un taux de conversion est défini pour les boutiques dont la devise par défaut n'est pas le NGN. L'extension se connecte à l'API GIG Logistics et envoie les adresses et coordonnées d'enlèvement et de livraison ainsi que les articles du panier avec leurs noms, quantités, poids et valeurs. Les produits sans poids sont envoyés comme 1 kg. Le prix est demandé pour une livraison à vélo. Deuxièmement, le tableau Country prices. Troisièmement, le Fallback cost. Si aucune de ces sources ne donne de prix, la méthode est masquée pour ce panier. 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 GIG 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 ou une connexion échouée est mise en cache pendant 10 minutes, pour que le paiement n'attende pas GIG Logistics à chaque actualisation. Le jeton de connexion est conservé 30 minutes et renouvelé automatiquement lorsque GIG le refuse. Les coordonnées des adresses sont conservées 30 jours, et une adresse introuvable 1 jour. Le délai d'attente de l'API est de 10 secondes, et celui de la recherche d'adresse de 5 secondes.

Si GIG Logistics renvoie une erreur ou un prix nul, le client ne voit aucune erreur. Le prix du tableau ou le coût de secours est utilisé, et l'erreur est écrite dans le journal de débogage.

L'extension ne calcule que des prix. Elle ne crée pas d'envois, de lettres de transport ni d'étiquettes GIG Logistics, ne réserve pas d'enlèvements, ne suit pas les colis et ne permet pas aux clients de choisir un centre de service. Elle n'ajoute rien aux commandes : la commande affiche le titre de la méthode et le coût d'expédition comme pour toute autre méthode d'expédition OpenCart. Les prix en temps réel ne sont demandés que pour les adresses nigérianes. Pour les autres pays, utilisez le tableau de prix.

Sur OpenCart 4, le client clique sur Choose dans le bloc de méthode d'expédition de la page de paiement, puis choisit GIG Logistics dans la fenêtre Shipping method options, où l'option affiche le titre de la méthode et le prix, par exemple GIG Logistics - $4.50. La méthode fonctionne de la même façon que sur OpenCart 3.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox GIG Logistics est le premier bloc de Extensions > Extensions > Shipping > VibeFox GIG Logistics > 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-gig-logistics et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation Modify pour l'extension peuvent changer 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 issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, la méthode d'expédition GIG Logistics n'est pas affichée aux clients au moment du paiement, et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (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 la méthode est masquée 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 concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 l'état de la licence.

Dépannage

GIG Logistics n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez la Geo zone, ou Ignore shipping zones et Countries, les limites de poids et le Minimum subtotal. Vérifiez que le tableau (le pays ou *) ou le Fallback cost donne un prix pour le pays. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Le prix provient du tableau et non de GIG Logistics : les prix en temps réel nécessitent le nom d'utilisateur et le mot de passe API, le Sender phone, la ville et l'État d'enlèvement, une adresse de livraison nigériane avec une ville ou un État et, pour les boutiques dont la devise par défaut n'est pas le NGN, le Currency conversion rate. Consultez les avertissements en haut de la page Edit. Activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension pour voir la raison. Une requête échouée est relancée au bout de 10 minutes.

Échec de connexion dans le journal : GIG Logistics a refusé le nom d'utilisateur ou le mot de passe API. Vérifiez-les et vérifiez le Test mode : les identifiants de test ne fonctionnent qu'avec l'API de test. Enregistrez les réglages pour relancer immédiatement.

GIG Logistics ne renvoie aucun prix : GIG calcule ses prix en fonction de la distance. Gardez Address lookup activé, ou saisissez Pickup latitude et Pickup longitude. Confirmez les prix avec votre compte GIG Logistics avant de passer en production.

L'avertissement sur la ville et l'État d'enlèvement persiste : choisissez un État dans State et renseignez City / area. La région de la boutique n'est utilisée que lorsque le pays de la boutique dans System > Settings > Store > Local est le Nigeria.

Une taxe est ajoutée au prix GIG : réglez Tax class sur No tax si le prix GIG comprend déjà tout ce que vous voulez facturer.

Les prix semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela efface les prix, jetons et coordonnées en cache.

La page indique « Warning: You do not have permission to modify VibeFox GIG Logistics! » : le groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez à ce groupe l'autorisation de modification pour extension/shipping/vfd_gig_logistics (OpenCart 3) ou extension/vfd_gig_logistics/shipping/vfd_gig_logistics (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API GIG Logistics et celle de la recherche d'adresse peuvent être remplacées par les réglages vfd_gigl_api_base_url et vfd_gigl_geocode_url (pour les tests) ; elles n'ont 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 GIG Logistics. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort order, Tax class et Geo zone. Les prix, jetons et coordonnées en cache sont toujours supprimés. Si Remove data on uninstall est activé, les autres réglages et le journal de débogage sont aussi supprimés. S'il est désactivé, ils sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur méthode d'expédition et leur coût.

Sur 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 GIG Logistics dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

GIG Logistics est une marque déposée de son propriétaire respectif. Cette extension n'est pas affiliée à GIG Logistics et n'est pas approuvée par GIG Logistics.