VibeFox DHL Africa 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 avec l'extension cURL. DHL XML Services nécessite aussi l'extension SimpleXML de PHP.

Compte DHL Express (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent l'API MyDHL. Il vous faut votre numéro de compte DHL Express et des identifiants de l'API MyDHL : une clé d'API et un secret d'API. Demandez-les sur le portail développeurs de DHL (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 les tarifs de secours, 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

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet pour OpenCart 3 vfd_dhl_africa-oc3-(version).ocmod.zip et le paquet pour OpenCart 4 vfd_dhl_africa.ocmod.zip. Installez uniquement 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_dhl_africa-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 DHL Africa et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page de réglages.

4. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Choisissez l'API DHL, saisissez la clé d'API, le secret d'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 par défaut de votre boutique, réglez DHL quote currency et Exchange rate. Vous pouvez éventuellement définir des prix par pays et un coût de secours (voir Configuration). Activez Enable DHL Express Africa et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_dhl_africa.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension 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 lui.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox DHL Africa, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page de réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'activez pas Enable DHL Express Africa et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages DHL que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des devis DHL. Les prix et les poids acceptent la virgule ou le point décimal. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Les avertissements en haut de la page vous indiquent quand les tarifs en temps réel sont désactivés parce que la clé d'API, le secret d'API ou le numéro de compte est manquant (ou, avec XML Services, le Site ID ou le mot de passe), quand le pays ou la ville d'origine est absent, quand XML Services est sélectionné (DHL les retire), quand une devise de devis est définie sans taux de change, et quand l'unité de poids ou de longueur de la boutique n'est pas connue de l'extension (les poids des produits sont alors lus en kg et les dimensions en cm ; ajoutez une classe de poids avec l'unité kg dans System > Localisation > Weight Classes, ou une classe de longueur avec l'unité cm dans System > Localisation > Length Classes).

Si une valeur n'est pas valide à l'enregistrement (un titre de mode vide ou de plus de 64 caractères, un nombre invalide ou négatif, un taux de change de 0, un poids minimal supérieur au poids maximal, une devise de devis, un pays d'origine, une classe de taxe ou une zone géographique inconnus, un ordre de tri qui n'est pas un nombre entier), un avertissement au-dessus des réglages indique le champ, par exemple Select a valid origin country. It was not saved. L'ancienne valeur de ce champ est conservée, et les autres réglages sont enregistrés.

Général

Enable DHL Express Africa : affiche ou masque DHL Express au paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client au paiement. Par défaut : DHL Express. Obligatoire, 64 caractères maximum.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Avec une classe de taxe (et des taxes activées dans la boutique), le tarif DHL est pris sans la taxe indiquée par DHL, et OpenCart ajoute sa propre taxe. Avec No tax, le tarif DHL est facturé tel que coté, taxe incluse.

Sort order : la position de DHL Express parmi les modes de livraison au paiement. Un nombre entier.

Compte DHL Express (nécessaire uniquement pour les tarifs en temps réel)

DHL API : l'interface DHL utilisée.

API key : votre nom d'utilisateur MyDHL API (clé d'API).

API secret : votre mot de passe MyDHL API (secret d'API). Après l'enregistrement, les champs clé d'API et secret d'API restent vides et affichent Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API key and API secret : affiché uniquement pour la MyDHL API 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 d'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 de 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.

Adresse d'expédition

L'adresse à partir de laquelle DHL prend les colis. Le tarif en dépend. OpenCart conserve l'adresse de la boutique sous forme de texte libre ; l'origine est donc toujours saisie ici. La note de cette section affiche le pays de votre boutique.

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 code postal (par exemple le Kenya, le Nigeria, le Ghana).

Tarifs

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 aucun service pour le trajet, le prix du pays est utilisé, puis le coût de secours. Sans l'un ni l'autre, le mode est masqué.

DHL quote currency : DHL établit ses devis 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 devis 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 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 de pays. Laissez-le vide pour masquer le mode dans ce cas.

Country prices : un prix de secours 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 (par défaut) 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 du pays et au coût de secours. Le tarif DHL en temps réel porte toujours sur le colis entier.

Free shipping from : le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel ce mode est gratuit. DHL n'est pas interrogé. Laissez vide pour ne jamais offrir la livraison.

Conditions

Minimum weight (kg) : masque le mode en dessous de ce poids de panier. 0 signifie aucune limite (par défaut). Il ne peut pas être supérieur à Maximum weight (kg).

Maximum weight (kg) : masque le mode au-dessus de ce poids de panier. Par défaut : 70 (utilisé aussi lorsque le champ est vide). 0 signifie aucune limite.

Minimum subtotal : affiche le mode uniquement si le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Disponibilité

Geo zone : proposer DHL Express 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é avec Ignore shipping zones.

Ignore shipping zones : proposer le mode pour les pays ci-dessous (ou pour tous les pays si la liste est vide), quelle que soit la zone géographique sélectionnée.

Countries : les pays de destination pour ce mode. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_dhla_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_dhla_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs DHL sont toujours journalisées, même lorsque cette option est désactivée. Les identifiants, le numéro de compte et les adresses des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_dhla_debug.old.log.php et un nouveau journal commence.

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 : si activé, la désinstallation de l'extension supprime les réglages, les devis DHL en cache et le journal. Si désactivé (par défaut), tout est conservé pour une réinstallation. Les produits DHL des commandes passées sont toujours conservés.

Importation / Exportation

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé d'API, le secret d'API et le mot de passe XML ne sont pas exportés.

Import : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Les identifiants enregistrés sont conservés.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix DHL Express. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, DHL Express n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. L'extension vérifie ensuite les conditions : les pays de Ignore shipping zones, le poids du panier et le sous-total minimal. Le sous-total est le prix des produits nécessitant une livraison, après remise du coupon et avant taxes. Les cartes-cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 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 à partir des classes de poids des produits (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 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 en 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, selon le fuseau horaire de la boutique, 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 secours s'appliquent.

Le produit DHL Express le moins cher est affiché sous forme d'un prix unique portant le titre de votre mode. Le client ne voit pas le produit DHL. Le prix est calculé dans votre devise par défaut, arrondi selon ses décimales, et affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Chaque devis 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'attente de l'API est de 12 secondes. Si DHL renvoie une erreur, n'a aucun service ou répond dans une devise inutilisable, le client ne voit aucune erreur : le prix de secours est utilisé ou le mode est masqué. La raison est écrite dans le journal de débogage.

L'extension ne calcule que des tarifs. Elle ne crée pas d'expéditions 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 regroupe pas plusieurs cartons, n'ajoute pas d'assurance et ne calcule pas les droits et taxes. Le devis ne concerne que l'expédition. Les droits de douane et les taxes à l'importation sont à la charge du destinataire.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit DHL Express dans la fenêtre Shipping method options. Le mode fonctionne de la même manière que sur OpenCart 3.

Commandes

Lorsque la commande est passée, l'extension conserve le tarif calculé pour son panier. Ouvrez la commande dans Sales > Orders : le panneau DHL Express Africa au-dessus de l'historique de la commande indique ce qu'il faut 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.

Le produit DHL n'est pas affiché au client dans les e-mails ni sur sa page de commande. La commande affiche le titre du mode et le coût de livraison comme pour tout autre mode de livraison OpenCart.

Sur OpenCart 4, le paiement conserve une seule commande et la met à jour chaque fois que le client confirme à nouveau. Le panneau affiche alors le dernier tarif du paiement. Si le client passe à un autre mode de livraison, le panneau n'est plus affiché pour cette commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DHL Africa est le premier bloc de Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit, 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) et 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-dhl-africa et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation de modification pour l'extension peuvent changer 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, le mode de livraison DHL Express n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active, le mode 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 affecté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 après 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 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é. Vérifiez Geo zone (ou activez Ignore shipping zones et vérifiez Countries), les limites de poids et le Minimum subtotal. Sans tarif en temps réel, le mode n'apparaît que si un prix de pays ou un coût de secours est défini. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page de l'extension (identifiants ou origine manquants). Activez Debug log, rechargez le paiement et consultez le champ Log de la page de l'extension. 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 secours 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 Tax class pour que le tarif DHL soit pris sans la taxe 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 de l'extension. Cela vide le cache des devis DHL.

La page indique "Warning: You do not have permission to modify VibeFox DHL Africa!" : le groupe d'utilisateurs de votre administration n'a peut-être que le droit de consultation. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_dhl_africa (OpenCart 3) ou extension/vfd_dhl_africa/shipping/vfd_dhl_africa (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'extension déclenche les événements OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request et xml_request (même préfixe), qui peuvent modifier l'adresse de l'API, la déclaration douanière, le carton et les requêtes DHL.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox DHL Africa. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable DHL Express Africa, Sort order, Tax class et Geo zone. Les devis DHL en cache et les événements de l'extension sont toujours supprimés. Si Remove data on uninstall est activé, les réglages DHL et le journal de débogage sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation. Les produits DHL des commandes passées ne sont jamais supprimés. Les commandes existantes conservent leur mode de livraison et leur coût.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox DHL Africa dans la liste des extensions installées, puis sur Delete (le bouton poubelle rouge) pour supprimer le paquet téléchargé.

DHL est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à DHL ni approuvée par DHL.