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

Jeton API Delhivery (uniquement pour les tarifs en temps réel) : connectez-vous à Delhivery One et ouvrez Settings > API setup. L'article d'aide de Delhivery « API token generation » explique les étapes. Les deux liens se trouvent sur la page du module. Les jetons de test fonctionnent avec l'environnement de préproduction (staging). Vous avez également besoin du code PIN à 6 chiffres de votre lieu d'enlèvement. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de jeton.

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 Delhivery dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Saisissez le jeton API et votre code PIN d'expédition, choisissez Express ou Surface ainsi que Pre-paid ou COD. Si la devise par défaut de votre boutique n'est pas l'INR, saisissez le taux de change. Vous pouvez également saisir des tarifs fixes (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur Delhivery avec le texte de délai de livraison Courier delivery (India) et la page de suivi Delhivery comme URL de suivi. Le transporteur est affecté à toutes les zones 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 provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Delhivery > Configure. Ils s'appliquent à toutes les zones. Chaque section dispose de son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide également le cache des tarifs Delhivery. Les montants acceptent « 9.99 » et « 9,99 ». Si un champ numérique ne contient pas un nombre positif ou nul, une erreur s'affiche et rien n'est enregistré.

Si la devise par défaut de votre boutique n'est pas l'INR, qu'un jeton API est enregistré et qu'aucun taux de change n'est défini, un avertissement au-dessus du formulaire vous rappelle que les tarifs en temps réel ne sont pas utilisés tant que vous n'avez pas saisi le taux. Si l'unité de poids de votre boutique n'est pas une unité standard (kg, g, lb ou oz), un avertissement vous demande de la définir dans International > Localization (Local units), car sinon les poids des produits sont lus en kilogrammes.

Général

Enable Delhivery : 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 : Delhivery. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax. Avec une règle, PrestaShop ajoute la taxe au coût de livraison.

Compte API Delhivery (nécessaire uniquement pour les tarifs en temps réel)

Environment : Production (track.delhivery.com) (par défaut) ou Staging / test account (staging-express.delhivery.com). Utilisez Staging uniquement avec un jeton de test Delhivery.

API token : votre jeton API Delhivery. Il est envoyé uniquement dans l'en-tête d'autorisation et n'est jamais écrit dans les journaux. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur seulement si vous voulez la modifier.

Remove saved token : activez l'option et enregistrez pour supprimer le jeton enregistré. Seuls les tarifs fixes sont ensuite utilisés.

Origin pincode : le code PIN à 6 chiffres de votre lieu d'enlèvement ou de votre entrepôt, par exemple 110001. S'il ne comporte pas 6 chiffres, un avertissement s'affiche et les tarifs en temps réel ne sont pas demandés tant que ce n'est pas corrigé.

Tarifs en temps réel

Un tarif en temps réel est demandé pour les destinations indiennes avec un code PIN valide à 6 chiffres, pour un envoi aller (livraison).

Shipping mode : le mode de facturation Delhivery utilisé pour le tarif : Express (par défaut) ou Surface.

Payment type : le type de paiement transmis à Delhivery : Pre-paid (par défaut) ou COD (cash on delivery — Delhivery adds its COD charge). Le module ne le change pas selon le mode de paiement choisi par le client.

Rate amount : Delhivery renvoie le montant avec et sans GST.

INR to (shop currency) conversion rate : l'intitulé affiche la devise par défaut de votre boutique. Les tarifs Delhivery sont en roupies indiennes. Si votre devise par défaut n'est pas l'INR, indiquez combien d'unités de votre devise vaut une roupie, par exemple 0.011. Le taux doit être supérieur à 0. Laissez-le vide et les tarifs en temps réel ne sont pas utilisés : ce sont les tarifs fixes qui s'appliquent. Inutile si votre devise par défaut est l'INR.

Tarifs fixes (utilisés lorsqu'aucun tarif en temps réel n'est disponible)

Les tarifs fixes sont utilisés lorsqu'il n'y a pas encore de jeton ou de code PIN, lorsque la destination est hors de l'Inde, lorsque le code PIN n'est pas desservi ou lorsque l'API renvoie une erreur. Ils sont exprimés dans la devise par défaut de votre boutique, hors taxes.

Prices per country : un par ligne, au format COUNTRY_CODE:price, par exemple IN:120. Vérifié avant le prix de secours. Les lignes dans un autre format sont supprimées à l'enregistrement, et un avertissement les liste.

Fallback price : utilisé lorsqu'aucun tarif en temps réel ni prix par pays ne s'applique. Laissez-le vide pour masquer le transporteur. 0 signifie gratuit.

Fixed price is charged : Per order facture le prix une seule fois. Per item (price × quantity) le multiplie par le nombre d'articles du panier. Un tarif Delhivery en temps réel porte toujours sur le poids total du colis.

Conditions

Free shipping from : la livraison est gratuite si le sous-total du panier (produits soumis à expédition, après remises, avant taxes) atteint au moins ce montant. Aucune requête n'est envoyée à Delhivery. Laissez vide pour désactiver.

Show from subtotal : affiche le transporteur uniquement si le sous-total du panier atteint au moins ce montant. Laissez vide pour l'afficher toujours.

Min weight : le poids minimum du panier en kg pour afficher le transporteur. 0 signifie aucune limite.

Max weight : masque le transporteur si le panier est plus lourd, en kg. Par défaut : 30. 0 signifie aucune limite, un champ vide signifie 30 kg. Min weight ne peut pas être supérieur à Max weight : la page affiche une erreur et rien n'est enregistré.

Les poids des produits sont convertis en kg à partir de l'unité de poids de votre boutique. Le tarif utilise le poids réel du panier (la somme des poids des produits), sans poids volumétrique ni cartons.

Disponibilité sans zones de livraison

Ignore zones : lorsque l'option est désactivée, les pays sont définis par les zones du transporteur dans Shipping > Carriers. Lorsqu'elle est activée, le transporteur est lié à toutes les zones (y compris celles que vous créerez plus tard) et proposé pour les pays indiqués ci-dessous. La désactiver rend au transporteur ses zones précédentes.

Countries : les pays de destination pour ce mode, choisis parmi vos pays actifs. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Utilisé uniquement lorsque Ignore zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_dlv_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. Les jetons et les codes PIN complets des clients ne sont jamais journalisés.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsque l'option est activée, la désinstallation du module supprime les réglages Delhivery, le transporteur, les tarifs en cache, les données de commande et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les numéros AWB des commandes ne sont jamais supprimés.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix Delhivery. Seuls les produits physiques 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 pays (lorsque Ignore zones est activé), le poids du panier et Show from subtotal. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Delhivery.

Pour une adresse indienne avec un code PIN valide à 6 chiffres, le module envoie à Delhivery les codes PIN d'origine et de destination, le poids du panier en grammes, le mode d'expédition et le type de paiement. Le montant renvoyé est converti de l'INR vers la devise par défaut de votre boutique, puis affiché dans la devise du panier du client. Chaque réponse est mise en cache pendant 1 heure. Une requête en échec est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Delhivery à chaque actualisation. Le délai d'attente de l'API est de 10 secondes.

S'il n'y a pas de tarif en temps réel, le prix du pays ou le prix de secours est utilisé. Si aucun des deux n'est défini, le transporteur est masqué. Le client ne voit jamais d'erreur d'API. La raison est écrite dans le journal.

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 calcule les tarifs et donne aux clients un lien de suivi. Il ne crée ni envois ni lettres de transport, n'imprime pas d'étiquettes, ne demande pas d'enlèvements ni de manifestes, ne vérifie pas la desserte des codes PIN, n'estime pas les dates de livraison, ne synchronise pas les statuts de suivi et ne calcule pas les tarifs internationaux Delhivery. Hors de l'Inde, seuls les tarifs fixes sont utilisés.

Commandes et suivi

Lorsqu'une commande est passée avec Delhivery, le module enregistre avec la commande le mode d'expédition et la source du prix. Sur la page de commande dans l'administration, le bloc Delhivery affiche Mode : (Express ou Surface), Price : (tarif Delhivery en temps réel, tarif fixe ou seuil de livraison gratuite) et le Delhivery AWB / tracking number, ou Not entered yet.

Créez l'envoi dans Delhivery One, puis saisissez son numéro AWB comme numéro de suivi de la commande dans le bloc Carriers de la page de commande (Edit). Le bloc Delhivery affiche alors un lien Track on delhivery.com. Le client voit un lien de suivi dans l'historique de la commande et reçoit l'e-mail « En transit » de PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Delhivery est le premier bloc de la page Modules > Module Manager > VibeFox Delhivery > 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-delhivery 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 : celui de la boutique principale, y compris dans une configuration multiboutique. Supprimer 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 Delhivery n'est pas affiché aux clients lors du paiement, et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas concerné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 suivant 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

Delhivery n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Delhivery 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 zones et vérifiez Countries. Contrôlez les limites de poids et Show from subtotal. Sans tarif en temps réel, il faut un prix par pays ou un Fallback price. Les produits peuvent aussi être limités à certains transporteurs sur la fiche produit.

Les tarifs en temps réel n'apparaissent pas : vérifiez le jeton API, un Origin pincode valide et, si la devise par défaut n'est pas l'INR, le taux de change. Le client doit saisir un code PIN indien valide à 6 chiffres. Activez Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Il indique la raison, par exemple un code PIN non desservi ou une erreur HTTP de Delhivery.

Le GST est facturé deux fois : le montant total de Delhivery inclut déjà le GST. Réglez Rate amount sur Gross amount (excluding GST) ou réglez Tax sur No tax.

Tests : réglez Environment sur Staging et utilisez un jeton de test Delhivery.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs Delhivery.

La page indique que le transporteur Delhivery est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Pour les développeurs : le module exécute les hooks actionVfdDlvApiUrl et actionVfdDlvApiTimeout, qui permettent de modifier l'adresse de l'API et le délai d'attente.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Delhivery et choisissez Uninstall. La clé de licence, le statut de la licence et les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur retrouve ses zones précédentes et est supprimé (les commandes conservent leur historique), et les réglages, le journal et les données Delhivery des commandes (mode et source du prix) sont supprimés. Si l'option est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module restaure le transporteur dans l'état qu'il avait auparavant. Les numéros AWB restent dans les commandes.

Delhivery est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à Delhivery ni approuvé par elle.