VibeFox Delhivery 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.
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 de l'extension. Les jetons de test fonctionnent avec l'environnement de staging. Il vous faut aussi le pincode à 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
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_delhivery-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_delhivery.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_delhivery-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 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 Delhivery et cliquez sur Install (le bouton vert +).
3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page de configuration.
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 le jeton API et votre pincode d'origine, 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). Activez Enable Delhivery et cliquez sur Save.
OpenCart 4
1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_delhivery.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 récupère le code de l'extension à partir 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 Delhivery, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).
4. Saisissez la clé de licence et les paramètres comme aux étapes 4 et 5 pour OpenCart 3. La page des paramètres et ses champs sont identiques dans les deux versions.
Après l'installation, le mode de livraison reste désactivé tant que vous n'activez pas Enable Delhivery et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les paramètres Delhivery conservés sont de nouveau utilisés.
Configuration
Tous les paramètres se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. Les sections sont listées à gauche. Un bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface également les tarifs Delhivery mis en cache. Les montants acceptent « 9.99 » et « 9,99 ». Si une valeur est incorrecte, rien n'est enregistré et la page indique la raison, par exemple Enter a valid method title (without < > ; = # { })., un message indiquant qu'un champ doit être un nombre positif ou nul, ou Sort order must be a whole number. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les paramètres.
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 en haut de la page vous rappelle que les tarifs en temps réel ne sont pas utilisés tant que vous n'avez pas saisi le taux. Si la boutique ne dispose pas de classe de poids en kilogrammes et que son unité de poids n'est pas une unité standard (kg, g, lb ou oz), un avertissement indique que les poids des produits sont lus en kilogrammes. Définissez une unité standard dans System > Localisation > Weight Classes.
Général
Les paramètres s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode de livraison dans Availability.
Enable Delhivery: propose Delhivery au 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 : Delhivery. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.
Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Avec une classe, OpenCart ajoute la taxe au coût de livraison.
Sort order: la position de Delhivery parmi les modes de livraison au paiement. Un nombre entier.
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). N'utilisez Staging qu'avec un jeton de test Delhivery.
API token: votre jeton API Delhivery. Il n'est envoyé que 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. Ne saisissez une nouvelle valeur que pour la modifier.
Remove saved token: activez-le et enregistrez pour supprimer le jeton enregistré. Seuls les tarifs fixes sont alors utilisés.
Origin pincode: le pincode à 6 chiffres de votre lieu d'enlèvement ou de votre entrepôt, par exemple 110001. S'il ne comporte pas 6 chiffres, les paramètres sont enregistrés avec l'avertissement The origin pincode must have 6 digits — live rates are not requested until it is fixed.
Tarifs en temps réel
Un tarif en temps réel est demandé pour les destinations indiennes disposant d'un pincode valide à 6 chiffres, pour un envoi aller (livré).
Shipping mode: le mode de facturation Delhivery utilisé pour le tarif : Express (par défaut) ou Surface.
Payment type: le type de paiement envoyé à Delhivery : Pre-paid (par défaut) ou COD (cash on delivery — Delhivery adds its COD charge). L'extension ne le modifie pas selon le mode de paiement choisi par le client.
Rate amount: Delhivery renvoie le montant avec et sans GST.
INR to (store currency) conversion rate: l'intitulé indique 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. Si vous le laissez vide, les tarifs en temps réel ne sont pas utilisés et les tarifs fixes s'appliquent. Il n'est pas nécessaire 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 pincode, que la destination est hors d'Inde, que le pincode n'est pas desservi ou que 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 CODE_PAYS:prix, par exemple IN:120. Vérifié avant le tarif de secours. Les lignes dans un autre format sont supprimées à l'enregistrement, et un avertissement les liste.
Fallback price: utilisé lorsque ni un tarif en temps réel ni un tarif par pays ne s'appliquent. Laissez vide pour masquer le mode de livraison (par défaut). 0 signifie gratuit.
Fixed price is charged: Per order (par défaut) facture le tarif une fois. Per item (price × quantity) le multiplie par le nombre d'articles du panier. Un tarif Delhivery en temps réel s'applique toujours au poids total du colis.
Conditions
Free shipping from: la livraison est gratuite si le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint au moins ce montant. Aucune requête n'est envoyée à Delhivery. Laissez vide pour désactiver cette option.
Show from subtotal: n'affiche le mode de livraison que si ce sous-total atteint au moins ce montant. Laissez vide pour l'afficher en permanence.
Min weight (kg): le poids minimum du panier pour afficher le mode de livraison. 0 signifie aucune limite (par défaut).
Max weight (kg): masque le mode de livraison si le panier est plus lourd. 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 leur classe de poids OpenCart. Le tarif utilise le poids réel du panier (la somme des poids des produits), sans poids volumétrique ni cartons.
Disponibilité
Geo zone: proposer Delhivery 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. Non vérifié lorsque Ignore zones est activé.
Ignore zones: lorsqu'il est activé, la zone géographique n'est pas vérifiée et le mode de livraison est proposé pour les pays ci-dessous (tous les pays si la liste est vide).
Countries: les pays de destination pour ce mode. Utilisé uniquement lorsque Ignore zones est activé.
Avancé
Debug log: écrit le calcul des tarifs dans storage/logs/vfd_dlv_debug.log.php (sous OpenCart 4, system/storage/logs/vfd_dlv_debug.log.php). Ce fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. Les jetons et les pincodes complets des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_dlv_debug.old.log.php et un nouveau journal est créé.
Log: affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.
Remove data on uninstall: lorsqu'elle est activée, la désinstallation de l'extension supprime les paramètres Delhivery, les tarifs en cache et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une nouvelle installation. Les données de commande (mode, source du tarif, numéros AWB) ne sont jamais supprimées.
Import / Export
Export: cliquez sur Download JSON pour enregistrer les paramètres dans un fichier JSON. Le jeton API n'est pas exporté.
Import: collez un JSON exporté précédemment et cliquez sur Import pour restaurer les paramètres, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Le jeton API enregistré n'est pas modifié.
Fonctionnement au paiement
Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le tarif Delhivery. Si une Geo zone est définie (et que Ignore zones est désactivé) et que l'adresse se trouve en dehors, Delhivery n'est pas proposé. 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. L'extension vérifie ensuite les pays (si Ignore zones est activé), le poids du panier et Show from subtotal. Le sous-total 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 les avoirs ne sont pas pris en compte. Si la livraison gratuite s'applique, le tarif est de 0 et aucune requête n'est envoyée à Delhivery.
Pour une adresse indienne disposant d'un pincode valide à 6 chiffres (le code postal de l'adresse), l'extension envoie à Delhivery les pincodes 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, arrondi selon ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax class sélectionnée. Chaque réponse est mise en cache pendant 1 heure. Une requête échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Delhivery à chaque actualisation. Le délai d'expiration de l'API est de 10 secondes.
En l'absence de tarif en temps réel, le tarif du pays ou le tarif de secours est utilisé. Si aucun des deux n'est défini, le mode de livraison est masqué. Le client ne voit jamais d'erreur de l'API. La raison est écrite dans le journal.
L'extension calcule les tarifs et fournit aux clients un lien de suivi. Elle ne crée ni expéditions 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 pincodes, n'estime pas les dates de livraison, ne synchronise pas les statuts de suivi et ne calcule pas les tarifs internationaux Delhivery. Hors d'Inde, seuls les tarifs fixes sont utilisés.
Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Delhivery dans la fenêtre Shipping method options. Le mode de livraison fonctionne de la même manière que sous OpenCart 3.
Commandes et suivi
Lorsqu'une commande est passée avec Delhivery, l'extension enregistre avec la commande le mode d'expédition et la source du tarif. Ouvrez la commande dans Sales > Orders : le panneau Delhivery au-dessus de l'historique de la commande 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.
Sous OpenCart 4, le paiement conserve une seule commande et la met à jour à chaque nouvelle confirmation du client. Le mode et la source du tarif sont mis à jour avec elle. Si le client passe à un autre mode de livraison avant la saisie d'un AWB, le panneau Delhivery n'est plus affiché pour cette commande.
Créez l'expédition dans Delhivery One, puis saisissez son AWB dans le panneau et cliquez sur Save. La page n'est pas rechargée. Les lettres, les chiffres et les tirets sont conservés (64 caractères maximum). Enregistrez un champ vide pour supprimer l'AWB. Lorsqu'un AWB est présent, le panneau affiche un lien Track on delhivery.com. L'enregistrement de l'AWB requiert l'autorisation de modifier les commandes. Sans elle, le panneau est en lecture seule.
Un client inscrit voit Delhivery tracking: avec l'AWB sous forme de lien vers la page de suivi Delhivery, sur la page de commande de son compte. Lorsque vous ajoutez une entrée à l'historique de la commande et que vous notifiez le client, l'e-mail de statut de commande reçoit la même ligne avec le lien. L'e-mail de nouvelle commande ne contient pas de lien de suivi, car l'AWB est saisi ultérieurement. Le panneau et le lien de suivi fonctionnent aussi pour les anciennes commandes lorsque l'extension est désactivée.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Delhivery est le premier bloc de Extensions > Extensions > Shipping > VibeFox Delhivery > Edit, au-dessus des paramètres. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence 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: opencart-shipping-delhivery et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification 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é 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 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 son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, Delhivery n'est pas proposé aux clients lors du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sous OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de livraison 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 concerné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é à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 de l'extension supprime toujours la clé de licence et le statut de licence.
Dépannage
Delhivery n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Delhivery est activé. Vérifiez Geo zone, ou Ignore zones et Countries, les limites de poids et Show from subtotal. Sans tarif en temps réel, un tarif par pays ou un Fallback price est nécessaire. Vérifiez que les produits ont Requires Shipping réglé sur Yes.
Les tarifs en temps réel n'apparaissent pas : vérifiez le jeton API, un Origin pincode valide et, si votre devise par défaut n'est pas l'INR, le taux de change. Le client doit saisir comme code postal un pincode indien valide à 6 chiffres. Activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Il indique la raison, par exemple un pincode non desservi ou une erreur HTTP de Delhivery.
La GST est facturée deux fois : le montant total de Delhivery inclut déjà la GST. Réglez Rate amount sur Gross amount (excluding GST) ou Tax class 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 de l'extension. Cela efface les tarifs Delhivery mis en cache.
L'AWB ne peut pas être enregistré : le message You do not have permission to modify orders. signifie que votre groupe d'utilisateurs administrateurs a besoin de l'autorisation de modification pour sale/order dans System > Users > User Groups.
La page affiche « Warning: You do not have permission to modify VibeFox Delhivery! » : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les paramètres. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_delhivery (OpenCart 3) ou extension/vfd_delhivery/shipping/vfd_delhivery (OpenCart 4) dans System > Users > User Groups.
Pour les développeurs : l'extension déclenche les événements OpenCart catalog/vfd_delhivery/api_url et catalog/vfd_delhivery/api_timeout, qui permettent de modifier l'adresse de l'API et le délai d'expiration.
Désinstallation
Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Delhivery. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Delhivery, Sort order, Tax class et Geo zone. Les tarifs en cache et les événements de l'extension sont toujours supprimés. Si Remove data on uninstall est activé, les paramètres Delhivery et le journal de débogage sont également supprimés. S'il est désactivé, les autres paramètres sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les données Delhivery des commandes (mode, source du tarif et numéros AWB) ne sont jamais supprimées. Les commandes existantes conservent leur mode de livraison et leur coût.
Sous 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 Delhivery dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléversé.
Delhivery est une marque déposée de son titulaire. Cette extension n'est pas affiliée à Delhivery et n'est pas approuvée par Delhivery.