VibeFox DHL Africa for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur avec l'extension cURL. Le module refuse de s'installer sur les anciennes versions de PHP ou sans cURL. Les DHL XML Services nécessitent aussi l'extension PHP SimpleXML.
Compte DHL Express (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API MyDHL. Il vous faut votre numéro de compte DHL Express et les identifiants de l'API MyDHL : une clé API et un secret API. Demandez-les sur le DHL Developer Portal (MyDHL API, "Get access") ou auprès de votre gestionnaire de compte DHL Express. Les comptes qui disposent encore d'identifiants DHL XML Services (Site ID et mot de passe) peuvent les utiliser à la place. Si vous n'utilisez que des prix de repli, vous n'avez pas besoin d'identifiants DHL.
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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox DHL Africa 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, puis cliquez sur Activate (voir Clé de licence).
4. Choisissez la DHL API, saisissez la clé API, le secret API et votre numéro de compte DHL. Laissez Test mode activé tant que vous utilisez des identifiants de test. Saisissez l'adresse Ship from. Si votre compte DHL n'est pas facturé dans la devise par défaut de votre boutique, réglez DHL quote currency et Exchange rate. Vous pouvez aussi définir des prix par pays et un coût de repli (voir Configuration). Cliquez sur Save.
À l'installation, le module crée le transporteur DHL Express avec le texte de délai de livraison DHL Express courier. 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. N'y définissez pas de prix : le prix provient toujours du module.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox DHL Africa > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs DHL en cache. Les prix et les poids acceptent la virgule ou le point décimal.
Des avertissements en haut de la page vous indiquent quand les tarifs en temps réel sont désactivés parce que la clé API, le secret API ou le numéro de compte manque (ou, avec XML Services, le Site ID ou le mot de passe), quand le pays ou la ville d'origine manque, quand XML Services est sélectionné (DHL les abandonne), quand une devise de cotation est définie sans taux de change, et quand l'unité de poids ou de dimension de la boutique dans International > Localization (Local units) n'est pas connue du module (il lit alors kg ou cm). Si une valeur n'est pas valide à l'enregistrement (un nom vide ou de plus de 64 caractères, un nombre non valide ou négatif, un taux de change de 0, un poids minimum supérieur au poids maximum, la devise de cotation, le pays d'origine ou la règle de taxe), une erreur indique le champ, l'ancienne valeur de ce champ est conservée, et les autres réglages sont enregistrés.
Général
Enable DHL Express Africa : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.
Name : le nom du transporteur affiché au client lors du paiement. Par défaut : DHL Express. Obligatoire, 64 caractères maximum.
Tax : la règle de taxe du transporteur, ou No tax. Avec une règle de taxe (et les taxes activées dans la boutique), le tarif DHL est pris sans la taxe cotée par DHL, et PrestaShop applique sa propre taxe. Avec No tax, le tarif DHL est facturé tel que coté, taxe incluse.
Compte DHL Express (nécessaire uniquement pour les tarifs en temps réel)
DHL API : l'interface DHL utilisée. Seuls les champs de l'API choisie sont affichés.
API key : votre nom d'utilisateur MyDHL API (clé API).
API secret : votre mot de passe MyDHL API (secret API). Après l'enregistrement, les champs API key et API secret restent vides et affichent Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.
Remove the saved API key and API secret : affiché uniquement lorsqu'une clé ou un secret est enregistré. Activez-le et cliquez sur Save pour supprimer les deux.
XML Site ID : votre Site ID DHL XML Services (API héritée uniquement). Le vider supprime aussi le mot de passe XML enregistré.
XML password : votre mot de passe DHL XML Services (API héritée uniquement). Comme le secret API, il n'est plus affiché après l'enregistrement.
DHL account number : votre numéro de compte DHL Express (9 chiffres). L'API MyDHL l'exige. Avec XML Services, il renvoie les tarifs de votre compte au lieu des tarifs publiés.
Test mode : utilise l'environnement de test DHL. Activé par défaut. Les identifiants de test ne fonctionnent que dans l'environnement de test, et les identifiants de production uniquement en production. Désactivez-le lorsque vous passez en production.
Ship from
L'adresse à laquelle DHL récupère les colis. Le tarif en dépend.
Origin country : le pays d'où vous expédiez.
Origin city : la ville d'où vous expédiez, par exemple Johannesburg. L'API MyDHL l'exige.
Origin postcode : laissez vide pour les pays sans code postal (par exemple Kenya, Nigeria, Ghana).
Rates
Tous les prix sont exprimés dans la devise par défaut de votre boutique, hors taxes. Le tarif en temps réel est le produit DHL Express le moins cher pour le colis. Si DHL n'est pas configuré, échoue ou n'a pas de service pour le trajet, le prix du pays est utilisé, puis le coût de repli. Sans l'un ni l'autre, le transporteur est masqué.
DHL quote currency : DHL cote dans la devise du pays de votre compte DHL (par exemple ZAR, NGN ou KES). Si DHL ne renvoie aucun montant dans la devise par défaut de votre boutique, le tarif en temps réel est converti depuis cette devise avec le taux de change ci-dessous. Sinon, il n'est pas utilisé. Par défaut : — None —.
Exchange rate : la valeur de 1 unité de la devise de cotation DHL dans la devise par défaut de votre boutique, par exemple 1 ZAR = 0.05. Il doit être supérieur à 0. Laissez-le vide s'il n'y a pas de conversion. Le taux de change est un réglage manuel.
Fallback cost : un coût forfaitaire lorsqu'il n'y a ni tarif en temps réel ni prix par pays. Laissez-le vide pour masquer le transporteur dans ce cas.
Country prices : un prix de repli par pays de destination, un par ligne : CC:Price, par exemple ZA:25.00. Utilisé lorsqu'il n'y a pas de tarif en temps réel. Les lignes dans un autre format sont ignorées, et un avertissement à l'enregistrement les répertorie.
Fallback price basis : Per order facture le prix une seule fois. Per item (multiplied by the cart quantity) le multiplie par le nombre d'articles. S'applique uniquement au prix par pays et au coût de repli. Le tarif DHL en temps réel porte toujours sur le colis entier.
Free shipping from : le sous-total du panier (produits nécessitant une livraison, après remises, avant taxes) à partir duquel ce transporteur est gratuit. DHL n'est pas interrogé. Laissez vide pour qu'il ne soit jamais gratuit.
Conditions
Minimum weight : masque le transporteur en dessous de ce poids de panier, en kg. 0 signifie sans limite. Il ne peut pas être supérieur à Maximum weight.
Maximum weight : masque le transporteur au-dessus de ce poids de panier, en kg. Par défaut : 70 (utilisé aussi lorsque le champ est vide). 0 signifie sans limite.
Minimum subtotal : n'affiche le transporteur que si le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.
Disponibilité sans zones de livraison
Ignore shipping zones : propose le transporteur sans que vous ayez à lui affecter des zones. Le transporteur reçoit toutes les zones, y compris celles que vous créerez plus tard, et ce sont les pays ci-dessous qui décident. Le désactiver rend au transporteur ses propres zones.
Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.
Avancé
Debug log : écrit les calculs de tarifs dans logs/vfd_dhla_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs DHL sont toujours journalisées, même lorsque cette option est désactivée. Les identifiants et les adresses des clients ne sont jamais journalisés.
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 du module supprime les réglages, le transporteur, les produits DHL enregistrés des commandes et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.
Fonctionnement lors du paiement
À l'étape de livraison, PrestaShop demande au module le prix DHL Express. 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 conditions : les pays de Ignore shipping zones, le poids du panier et le sous-total minimum. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à DHL.
Sinon, le module envoie à DHL l'origine et la destination (pays, ville, code postal), le poids du panier converti en kg (au moins 0,5 kg) et un carton construit à partir des dimensions des produits en cm : la plus grande longueur, la plus grande largeur et les hauteurs empilées. Les produits sans dimensions n'ajoutent rien. Si aucun produit n'a de dimensions, un carton de 10 x 10 x 10 cm est utilisé. Les envois vers un autre pays sont déclarés à la douane, avec le sous-total du panier comme valeur déclarée. Les envois nationaux ne sont pas déclarés. La date d'enlèvement est aujourd'hui, ou le lundi le week-end. Un tarif en temps réel n'est demandé qu'après que le client a saisi une ville (avec XML Services, une ville ou un code postal). Avant cela, les prix de repli s'appliquent.
Le produit DHL Express le moins cher est affiché comme un prix unique avec le nom de votre transporteur. Le client ne voit pas le produit DHL. Le prix est calculé dans votre devise par défaut, arrondi, puis affiché dans la devise du panier du client.
Chaque tarif est mis en cache pendant 1 heure par colis et par trajet. Une requête échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas DHL à chaque rafraîchissement. Le délai d'attente de l'API est de 12 secondes. Si DHL renvoie une erreur, n'a pas de service ou répond dans une devise inutilisable, le client ne voit aucune erreur : le prix de repli est utilisé ou le transporteur est masqué. La raison est écrite dans le journal de débogage.
Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.
Le module calcule uniquement les tarifs. Il ne crée pas d'envois DHL, n'imprime pas d'étiquettes ni de factures commerciales, ne réserve pas d'enlèvements, ne suit pas les colis, ne propose pas de points relais DHL, ne laisse pas le client choisir entre les produits DHL, ne regroupe pas plusieurs cartons, n'ajoute pas d'assurance et ne calcule pas les droits et taxes. Le tarif ne porte que sur le transport. Les droits de douane et taxes d'importation sont à la charge du destinataire.
Commandes
Lorsque la commande est passée, le module conserve le tarif calculé pour son panier. La page de la commande dans le back-office affiche alors un bloc DHL Express Africa, pour que vous sachiez quoi réserver auprès de DHL :
DHL product : le produit DHL Express du tarif en temps réel, par exemple « EXPRESS WORLDWIDE (P) ». Affiché uniquement pour les tarifs en temps réel.
Price source : Live DHL rate, Fallback price (no live rate) ou Free shipping threshold.
Calculated price (excl. tax) : le prix dans la devise par défaut de votre boutique.
Les recalculs ultérieurs du panier, par exemple lorsque la commande est modifiée dans le back-office, ne modifient pas ces valeurs. Les tarifs des paniers qui n'ont jamais donné lieu à une commande sont supprimés après 30 jours.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DHL Africa est le premier bloc de la page Modules > Module Manager > VibeFox DHL Africa > 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-dhl-africa 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 DHL Express n'est pas affiché aux clients lors du paiement, et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur vous est donc masqué également. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sous 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é 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
DHL Express n'apparaît pas au paiement : vérifiez que la licence est active et que Enable DHL Express Africa 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 Minimum subtotal. Sans tarif en temps réel, le transporteur n'apparaît que si un prix par pays ou un coût de repli est défini. Les produits peuvent aussi être limités à certains transporteurs sur la page du produit.
Les tarifs en temps réel n'apparaissent pas : vérifiez les avertissements en haut de la page du module (identifiants ou origine manquants). Activez le Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Les erreurs DHL, comme une erreur HTTP de l'API MyDHL, l'absence de produit pour le trajet ou un problème de devise, sont toujours journalisées. Vérifiez que Test mode correspond à vos identifiants et que l'adresse du client contient une ville.
DHL renvoie le tarif en ZAR, NGN ou KES mais ma boutique utilise une autre devise : le journal indique DHL quote not usable. Réglez DHL quote currency sur cette devise et saisissez le Exchange rate. Sans cela, le tarif en temps réel n'est pas utilisé et les prix de repli s'appliquent.
J'ai d'anciens identifiants DHL XML Services : choisissez XML Services (legacy) dans DHL API. Passez à l'API MyDHL lorsque vous recevez des identifiants MyDHL.
La taxe est facturée deux fois sur la livraison : définissez une règle de taxe dans Tax pour que le tarif DHL soit pris sans la TVA de DHL, ou choisissez No tax pour facturer le montant DHL tel que coté.
Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs DHL en cache.
La page indique que le transporteur DHL Express 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 fournit les hooks actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest et actionVfdDhlaXmlRequest pour modifier l'adresse de l'API, la déclaration en douane, le carton et les requêtes DHL.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox DHL Africa et choisissez Uninstall. La clé de licence, le statut de la licence et les tarifs DHL 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, les produits DHL enregistrés des commandes et le journal. S'il est désactivé, le transporteur est seulement désactivé, et les réglages ainsi que les produits DHL des commandes passées sont conservés. Réinstaller le module rétablit le statut qu'avait le transporteur.
DHL est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à DHL ni approuvé par DHL.