VibeFox GIG Logistics for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Identifiants de l'API GIG Logistics (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API tierce de GIG Logistics. GIG Logistics fournit aux clients professionnels un nom d'utilisateur d'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 la grille tarifaire et le coût de secours, vous n'avez pas besoin d'identifiants d'API.

Le Nigeria dans votre boutique : les tarifs en temps réel ne sont demandés que pour les adresses de livraison au Nigeria. Le pays Nigeria doit donc exister et être actif dans International > Locations > Countries.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox GIG Logistics 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. Renseignez la grille tarifaire et/ou le coût de secours. Pour les tarifs en temps réel, saisissez aussi le nom d'utilisateur et le mot de passe de l'API, le téléphone, la ville et l'État d'enlèvement, ainsi que le taux de conversion de devise si votre devise par défaut n'est pas le NGN (voir Configuration). Cliquez sur Save.

5. Si le champ Nigerian states affiche le bouton Add Nigerian states, cliquez dessus (voir Configuration).

À l'installation, le module crée le transporteur GIG Logistics avec le texte de délai de livraison Courier delivery. Le transporteur est rattaché à la zone du Nigeria (dans une boutique par défaut, l'Afrique) 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. Ne définissez pas de prix à cet endroit : le prix vient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox GIG Logistics > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs GIG Logistics, les jetons d'API et les coordonnées d'adresses mis en cache.

Au-dessus des sections, la page affiche des avertissements lorsque les tarifs en temps réel ne peuvent pas être utilisés : seul le nom d'utilisateur ou le mot de passe de l'API est renseigné, le Sender phone ou la ville ou l'État d'enlèvement manque, ou votre devise par défaut n'est pas le NGN et aucun Currency conversion rate n'est défini. La page signale aussi l'absence du transporteur GIG Logistics, et le cas où l'unité de poids de votre boutique (International > Localization > Local units) n'est pas reconnue par le module ; dans ce cas, les poids des produits sont lus en kg. À l'enregistrement, un nombre incorrect (un montant négatif, un Currency conversion rate de 0, une latitude hors de -90 à 90, une longitude hors de -180 à 180), un Min weight (kg) supérieur à Max weight (kg), un Method title vide ou non valide, ou une règle de taxe inconnue est signalé, et rien n'est enregistré.

General

Les réglages de cette page s'appliquent à toutes les zones du transporteur.

Enable/Disable : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et au paiement. Par défaut : GIG Logistics. Obligatoire.

Tax : la règle de taxe du transporteur, ou No tax. Une règle de taxe ajoute votre taxe sur les frais de port au coût. Choisissez No tax si le tarif GIG inclut déjà tout ce que vous voulez facturer.

GIG Logistics API (live prices) (facultatif)

Avec des identifiants d'API, le tarif est demandé à GIG Logistics pour chaque adresse nigériane. Sans identifiants, ou lorsque l'API ne renvoie aucun tarif, la grille tarifaire et le coût de secours sont utilisés.

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

API password : votre mot de passe de l'API tierce de GIG Logistics. Il sert uniquement à se connecter à l'API et n'est jamais journalisé. 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. Pour supprimer le mot de passe, effacez API username et enregistrez.

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 tarifs réels. Par défaut : désactivé.

Currency conversion rate : GIG Logistics renvoie les tarifs en NGN. Si la devise par défaut de votre boutique n'est pas le NGN, indiquez 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 tarifs 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. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Pickup (sender) address

Lieu où GIG Logistics récupère les colis, au Nigeria. Si votre boutique est au Nigeria, les champs vides de rue, de ville et d'État reprennent l'adresse de la boutique indiquée dans Shop Parameters > Contact > Stores.

Sender name : le nom de l'expéditeur transmis à GIG Logistics. Vide, c'est le nom de la boutique qui est utilisé.

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

Street address : l'adresse de rue de l'enlèvement.

City / area : la ville ou le quartier d'enlèvement, par exemple Victoria Island. Obligatoire pour les tarifs 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, Shop state (Shop parameters > Contact > Stores), utilise l'État de l'adresse de la boutique. Obligatoire pour les tarifs en temps réel.

Pickup latitude : latitude facultative du point d'enlèvement sur la carte, par exemple 6.4281. GIG Logistics calcule les tarifs selon la distance. Vide, les coordonnées sont déterminées à partir de l'adresse.

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

Address lookup : recherche les coordonnées sur la carte des adresses avec OpenStreetMap (Nominatim). GIG Logistics calcule le tarif à 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 tarif. Par défaut : activé.

Nigerian states : l'État de l'adresse de livraison est transmis à GIG Logistics et à la recherche d'adresse. PrestaShop n'a pas d'États nigérians par défaut ; sans eux, seules la rue et la ville sont utilisées. Le bouton Add Nigerian states ajoute les 37 États (codes LA, FC, etc.), active Contains states pour le Nigeria et ajoute le champ État au formulaire d'adresse nigériane. Les États déjà présents (par code ou par nom) ne sont pas ajoutés une seconde fois. Lorsque tout est en place, le champ indique le nombre d'États disponibles pour les adresses nigérianes. Rien n'est modifié tant que vous ne cliquez pas sur le bouton.

Price table and fallback

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

Country prices : une grille avec un tarif de base par pays. Cliquez sur Add country pour ajouter une ligne, et sur l'icône de corbeille pour en supprimer une. Choisissez * Any other country pour tous les pays qui n'ont pas leur propre ligne. Les colonnes XS (jusqu'à 1 kg), S (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (au-delà de 5 kg) sont des tarifs facultatifs par tranche de poids : un tarif de tranche supérieur à 0 remplace le tarif de base pour les paniers de cette tranche. Un tarif de 0 signifie livraison gratuite. Les cellules de prix vides sont enregistrées à 0 ; renseignez donc le tarif de base pour chaque ligne ajoutée. Si un pays apparaît deux fois, la ligne la plus récente est conservée. Les valeurs corrigées sont listées dans un avertissement après l'enregistrement. Les pays sans ligne (lorsqu'il n'y a pas de ligne *) n'obtiennent aucun tarif de la grille.

Fallback cost : utilisé lorsque ni GIG Logistics ni la grille ne donnent de tarif. Vide, le transporteur est masqué dans ce cas.

Table / fallback price is : Per order facture le tarif une seule fois. Per item (multiplied by the number of items) le multiplie par le nombre d'articles du panier. Les tarifs 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 livraison, après remises, hors taxes) à partir duquel la livraison est gratuite. Vide, la livraison n'est jamais gratuite.

Minimum subtotal : affiche le transporteur uniquement lorsque le sous-total du panier atteint ce montant. Vide, il est toujours affiché.

Min weight (kg) : le poids minimal du panier en kg. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie pas de limite.

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

Availability without shipping zones

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, même si ses zones ne les incluent pas. Lorsque vous l'activez, le transporteur est rattaché à toutes les zones actives, et les zones créées plus tard y sont rattachées aussi. Lorsque vous le désactivez, le transporteur retrouve ses anciennes zones.

Countries : les pays de destination pour ce mode. Vide, il s'agit de tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.

Advanced

Debug log : écrit les calculs de tarifs dans logs/vfd_gigl_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 journalisées, même lorsque le journal est désactivé. Aucun mot de passe, jeton ou adresse de client n'est écrit.

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'il est activé, la désinstallation du module supprime ses réglages, le transporteur, les caches et les journaux. Lorsqu'il est désactivé, tout est conservé pour une réinstallation. Les commandes sont toujours conservées.

Fonctionnement au paiement

À l'étape d'expédition, PrestaShop demande au module le tarif GIG Logistics. Seuls les produits nécessitant une livraison comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module vérifie d'abord les conditions : le pays de livraison (avec Ignore shipping zones), le poids du panier et le sous-total minimal. Si le sous-total atteint Free shipping from, le tarif est de 0 et aucune requête n'est envoyée à GIG Logistics.

Ensuite, le tarif est repris de la première source qui en fournit un. D'abord, le tarif GIG Logistics en temps réel, si des identifiants d'API sont saisis, que l'adresse est au Nigeria, que l'adresse 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. Le module 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 tarif est demandé pour une livraison à vélo. Ensuite, la grille Country prices. Enfin, le Fallback cost. Si aucune source ne donne de tarif, le transporteur est masqué pour ce panier. Le tarif est calculé dans votre devise par défaut, puis affiché dans la devise du panier du client.

Chaque réponse de GIG est mise en cache pendant 1 heure, de sorte que le même panier ne déclenche pas une nouvelle requête. Une requête ou une connexion échouée est mise en cache pendant 10 minutes, afin 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. 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 tarif nul, le client ne voit aucune erreur. La grille ou le coût de secours est utilisé, et l'erreur est écrite dans le journal de débogage.

Si vous modifiez le 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 ne calcule que les tarifs. Il ne crée pas d'expéditions, de lettres de transport ou 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. Les commandes sont expédiées via votre compte GIG Logistics comme d'habitude. Les tarifs en temps réel ne sont demandés que pour les adresses nigérianes. Pour les autres pays, utilisez la grille tarifaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox GIG Logistics est le premier bloc de Modules > Module Manager > VibeFox GIG Logistics > 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-gig-logistics 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 : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer 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, le transporteur GIG Logistics n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office, donc le transporteur est masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au 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 le support 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 la licence.

Dépannage

GIG Logistics n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable 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 et vérifiez Countries. Contrôlez les limites de poids et le Minimum subtotal. Vérifiez que la grille (le pays ou *) ou le Fallback cost donne un tarif pour le pays. Des produits peuvent aussi être limités à certains transporteurs sur la fiche produit.

Le tarif vient de la grille, et non de GIG Logistics : les tarifs en temps réel exigent le nom d'utilisateur et le mot de passe de l'API, le Sender phone, la ville et l'État d'enlèvement, une adresse de livraison au Nigeria 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 Configure. Activez le Debug log, rechargez le paiement et regardez le champ Log sur la page du module pour connaître la raison. Une requête échouée est relancée au bout de 10 minutes.

Login failed dans le journal : GIG Logistics a refusé le nom d'utilisateur ou le mot de passe de l'API. Vérifiez-les, ainsi que Test mode : les identifiants de test ne fonctionnent qu'avec l'API de test. Enregistrez les réglages pour relancer immédiatement la tentative.

GIG Logistics ne renvoie aucun tarif : GIG calcule les tarifs selon la distance. Gardez Address lookup activé, ou saisissez Pickup latitude et Pickup longitude. Cliquez sur Add Nigerian states pour que l'État de livraison soit aussi transmis. Confirmez les tarifs avec votre compte GIG Logistics avant la mise en production.

L'avertissement sur la ville et l'État d'enlèvement persiste : choisissez un État dans State et renseignez City / area. L'adresse de la boutique n'est utilisée que lorsque le pays de la boutique est le Nigeria, et l'État de la boutique n'est connu qu'après l'ajout des États nigérians et leur sélection dans Shop Parameters > Contact > Stores.

La taxe est ajoutée au tarif GIG : réglez Tax sur No tax si le tarif GIG inclut déjà tout ce que vous voulez facturer.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs, jetons et coordonnées mis en cache.

La page indique que le transporteur GIG Logistics 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 GIG Logistics et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs, jetons et coordonnées d'adresses mis en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur enregistré son statut précédent. Les États nigérians ajoutés avec Add Nigerian states restent dans votre boutique dans les deux cas.

GIG Logistics est une marque de son propriétaire respectif. Ce module n'est ni affilié à GIG Logistics ni approuvé par GIG Logistics.