VibeFox DHL Africa for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
Compte DHL Express (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent l'API MyDHL. Vous avez besoin de votre numéro de compte DHL Express et des identifiants de l'API MyDHL : une clé API et un secret API. Demandez-les sur le portail développeurs DHL (MyDHL API, « Get access ») ou auprès de votre gestionnaire de compte DHL Express. Les comptes qui disposent encore des identifiants DHL XML Services (Site ID et mot de passe) peuvent les utiliser à la place. Si vous n'utilisez que les tarifs 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier vfd_dhl_africa dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > DHL Express Africa, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Choisissez l'API DHL, saisissez la clé API, le secret API et votre numéro de compte DHL. Gardez 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 de votre boutique, définissez DHL quote currency et Exchange rate. Vous pouvez également définir des prix par pays et un coût de repli (voir Configuration).
6. Ajoutez DHL Express Africa à vos zones de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > DHL Express Africa. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :
Title (zone): le nom de cette option au paiement pour cette zone. Laissez-le vide pour utiliser le Name global.
Des avertissements au-dessus des réglages vous indiquent quand les tarifs en temps réel sont désactivés, parce que les identifiants ou l'origine sont manquants, et quand une devise de cotation est définie sans taux de change. À chaque enregistrement des réglages, les tarifs DHL en cache sont effacés. Les prix et les poids acceptent la virgule ou le point décimal.
Général
Enable/Disable: active ou désactive le mode dans toutes les zones à la fois.
Name: le nom du mode de livraison affiché au paiement. Par défaut : DHL Express.
Tax status: Taxable (avec les taxes WooCommerce activées) prend le tarif DHL sans la taxe incluse dans le tarif DHL, et WooCommerce applique sa propre taxe. None facture le tarif DHL tel qu'il est indiqué, taxes comprises.
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).
XML Site ID: votre Site ID DHL XML Services (API héritée uniquement).
XML password: votre mot de passe DHL XML Services (API héritée uniquement).
DHL account number: votre numéro de compte DHL Express (9 chiffres). L'API MyDHL l'exige. Avec XML Services, il renvoie vos tarifs de 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.
Expédition depuis
L'adresse à laquelle DHL récupère les colis. Le tarif en dépend.
Origin country: le pays depuis lequel vous expédiez.
Origin city: la ville depuis laquelle vous expédiez, par exemple Johannesburg. L'API MyDHL l'exige.
Origin postcode: laissez vide pour les pays sans codes postaux (par exemple le Kenya, le Nigeria, le Ghana).
Tarifs
Tous les prix sont exprimés dans la devise de votre boutique. Le tarif en temps réel correspond au 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 mode de livraison 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 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é.
Exchange rate: combien vaut 1 unité de la devise de cotation DHL dans la devise de votre boutique, par exemple 1 ZAR = 0.05. Laissez vide pour aucune conversion. Le taux 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 vide pour masquer le mode.
Country prices: un prix de repli par pays de destination, une ligne par pays : CC:Price, par exemple ZA:25.00. Utilisé en l'absence de tarif en temps réel.
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 à partir duquel ce mode est gratuit. DHL n'est pas interrogé. Laissez vide pour qu'il ne soit jamais gratuit.
Conditions
Minimum weight (kg): masque le mode en dessous de ce poids de panier. 0 signifie aucune limite.
Maximum weight (kg): masque le mode au-dessus de ce poids de panier. Par défaut : 70. 0 signifie aucune limite.
Minimum subtotal: n'affiche le mode que si le sous-total du panier atteint ce montant. Laissez vide pour toujours l'afficher.
Excluded shipping classes: masque le mode si le panier contient un produit appartenant à l'une de ces classes de livraison WooCommerce.
Disponibilité sans zones de livraison
Ignore shipping zones: propose le mode pour les pays ci-dessous, même si la zone de livraison correspondante ne le contient pas.
Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous expédiez. Utilisé uniquement avec Ignore shipping zones.
Avancé
Debug log: enregistre les calculs de tarifs dans WooCommerce > Status > Logs, source vfd-dhl-africa. Les erreurs DHL sont toujours enregistrées, même lorsque ce réglage est désactivé. Les identifiants et les adresses des clients ne sont jamais enregistrés.
Remove data on uninstall: lorsqu'elle est activée, la suppression de l'extension supprime ses réglages et ses méthodes de zone. La désactivation de l'extension ne supprime jamais de données.
Fonctionnement lors du paiement
Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord le poids du panier, le sous-total minimum et les classes de livraison exclues. Si la livraison gratuite s'applique, le client bénéficie de la livraison gratuite et aucune requête n'est envoyée à DHL.
Sinon, l'extension envoie à DHL l'origine et la destination (pays, ville, code postal), le poids du panier converti en kg (au minimum 0,5 kg) et un carton construit à partir des dimensions des produits en cm : la plus grande longueur, la plus grande largeur et la somme des hauteurs. 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 internationaux sont déclarés comme marchandises, avec le sous-total du panier comme valeur déclarée, afin que DHL cote des produits de type colis. Les envois nationaux ne sont pas déclarés. Un tarif en temps réel n'est demandé qu'une fois que le client a saisi une ville (avec XML Services, une ville ou un code postal).
Le produit DHL Express le moins cher est affiché comme un seul tarif portant votre titre. Le client ne voit ni le produit DHL ni de délai de livraison. Le nom du produit (par exemple « EXPRESS WORLDWIDE (P) ») est enregistré comme DHL product dans la ligne d'expédition de la commande, afin que vous sachiez quoi réserver.
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 actualisation. Le délai d'expiration de l'API est de 12 secondes. Si DHL renvoie une erreur ou n'a pas de service, le client ne voit aucune erreur : le prix de repli est utilisé ou le mode est masqué.
Le mode fonctionne avec le paiement classique et avec les blocs Panier et Paiement. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension calcule uniquement les tarifs. Elle 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 de service DHL, ne permet pas au client de choisir entre les produits DHL, ne répartit pas le colis en plusieurs cartons, n'ajoute pas d'assurance et ne calcule pas les droits et taxes. Le tarif ne concerne que la livraison. Les droits et taxes d'importation sont payés par le destinataire.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > DHL Express Africa. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, DHL Express n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.
Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
DHL Express n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids, Minimum subtotal et Excluded shipping classes. Sans tarif en temps réel, le mode n'apparaît que si un prix par pays ou un coût de repli est défini.
Les tarifs en temps réel n'apparaissent pas : vérifiez les avertissements en haut de la page des réglages (identifiants ou origine manquants). Activez Debug log et ouvrez WooCommerce > Status > Logs, source vfd-dhl-africa. Les erreurs DHL, comme des identifiants incorrects, l'absence de service pour le trajet ou un problème de devise, sont toujours enregistrées. Vérifiez que Test mode correspond à vos identifiants.
DHL renvoie le tarif en ZAR, NGN ou KES, mais ma boutique utilise une autre devise : définissez 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 : réglez Tax status sur Taxable pour que le tarif DHL soit pris sans la TVA DHL, ou sur None pour facturer le montant DHL tel qu'indiqué.
Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs DHL en cache.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation de l'extension conserve tous les réglages. Elle efface seulement les tarifs DHL en cache. Pour supprimer l'extension, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés, ainsi que les tarifs en cache. Les réglages et les méthodes de zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes ne sont jamais modifiées, et les commandes existantes conservent leurs lignes d'expédition.
DHL est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à DHL ni approuvée par DHL.