VibeFox DHL Packstation 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). Le sélecteur de points de retrait fonctionne avec le paiement standard d'OpenCart.

PHP : 8.0 ou ultérieur.

Clé d'API DHL : la liste des points provient de l'API gratuite DHL Location Finder. Inscrivez-vous sur le portail développeurs de DHL (developer.dhl.com), créez une application, ajoutez l'API « Location Finder - Unified » et copiez la clé d'API de l'application. Aucun contrat commercial avec DHL n'est nécessaire pour cette API. Sans la clé, le mode est masqué au paiement. Tenez compte de la limite de requêtes de votre application DHL : chaque nouvelle recherche de code postal ou de ville correspond à une requête d'API.

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_dhl_packstation-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_dhl_packstation.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_packstation-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 Packstation 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 License key, dans le bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Collez la clé d'API DHL, cliquez sur Save, puis sur Test API key. Choisissez les types de points de retrait et saisissez les prix par pays (voir Configuration). Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_dhl_packstation.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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 DHL Packstation, 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/Disable et n'enregistrez pas. La grille tarifaire par défaut contient des prix pour l'Allemagne et l'Autriche, et un prix pour les autres pays. Si vous réinstallez l'extension après une désinstallation, les réglages 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 Packstation > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide le cache des points de retrait. Si un champ comporte une erreur (un nom non valide ou de plus de 64 caractères, un rayon ou un nombre de résultats qui n'est pas un nombre entier, un nombre invalide ou négatif, Min weight (kg) supérieur à Max weight (kg), un ordre de tri qui n'est pas un nombre entier, une classe de taxe ou une zone géographique inconnue), rien n'est enregistré et l'erreur s'affiche. 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 la clé d'API DHL est vide, quand aucun type de point de retrait n'est activé (dans les deux cas le mode n'est pas affiché au paiement), quand les entrées de prix par pays ne sont pas au format CC:PRICE (ces entrées sont ignorées), et quand il n'existe aucune classe de poids avec l'unité kg dans System > Localisation > Weight Classes (les poids des produits sont alors lus selon le nom de l'unité de leur classe : kg, g, lb ou oz, les unités inconnues étant traitées comme des kg).

Général

Les réglages s'appliquent à toutes les zones géographiques.

Enable/Disable : active DHL Packstation au paiement. Par défaut : off.

Name : le nom du mode de livraison affiché au client. Par défaut : DHL Packstation. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

Tax Class : la classe de taxe du coût de livraison, ou --- None --- (par défaut). OpenCart ajoute cette taxe aux prix ci-dessous. Avec --- None ---, les prix sont définitifs.

Sort Order : la position de DHL Packstation parmi les modes de livraison. Un nombre entier.

API DHL Location Finder

DHL API key : la « API Key » de votre application sur developer.dhl.com. Sans elle, le mode est masqué au paiement. 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 the saved API key : affiché lorsqu'une clé est enregistrée. Cochez cette case et enregistrez pour supprimer la clé stockée.

Connection test : le bouton Test API key recherche les points proches de 53113 Bonn avec la clé enregistrée et vide le cache des points de retrait. Enregistrez d'abord les réglages. Il indique combien de points ont été trouvés (Connected: … DHL locations found near 53113 Bonn.), que DHL a rejeté la clé (401/403), ou que l'API n'a pas répondu correctement (détails dans le journal de débogage).

Points de retrait

Au paiement, le client voit les points proches de son code postal de livraison et peut rechercher un autre code postal ou une autre ville.

Location types : les points DHL que le client peut choisir : Packstation (parcel locker), Post Office (Postfiliale) et DHL Parcel Shop (Paketshop). Les trois sont activés par défaut. Si aucun n'est sélectionné, le mode est masqué. Pour une Packstation, le client doit saisir son DHL Postnummer.

Search radius (meters) : le rayon autour du code postal ou de la ville recherché. Par défaut : 5000. Un nombre entier ; les valeurs inférieures à 100 ou supérieures à 25000 m (le maximum de DHL) sont ramenées à cette limite.

Max results : le nombre maximal de points affichés par recherche. Par défaut : 20. Un nombre entier ; DHL autorise jusqu'à 50, les valeurs supérieures sont ramenées à 50.

Shipping address : utilise le point choisi comme adresse de livraison de la commande. Activé par défaut. La ligne 1 de l'adresse devient par exemple « Packstation 105 » (ou « Postfiliale 502 » pour un bureau de poste ou un DHL Parcel Shop), la ligne 2 « Postnummer » avec le numéro, ainsi que le code postal, la ville et le pays du point, afin que les étiquettes imprimées depuis la commande aillent au bon endroit. Le nom, l'entreprise et le téléphone proviennent de l'adresse du client. La région est vidée. Le carnet d'adresses du client n'est pas modifié.

Prix (le titre de la section affiche la devise par défaut de votre boutique)

Country prices : le prix par pays de destination, dans la devise par défaut de votre boutique, hors taxes, au format CC:PRICE, séparés par des virgules ou des retours à la ligne. Par défaut : DE:4.99, AT:5.99. La virgule décimale fonctionne aussi (DE:4,99).

Other countries : le prix pour un pays de destination absent de Country prices. Par défaut : 5.99. Laissez vide pour masquer le mode pour ces pays.

Calculation : Per order (par défaut) facture le prix une seule fois. Per item (price x quantity) le multiplie par le nombre d'articles du panier.

Free shipping from : le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel cette livraison est gratuite. Laissez vide pour ne jamais la proposer gratuitement.

Disponibilité

Min weight (kg) : le poids minimal du panier. Les poids des produits sont convertis à partir de leur classe de poids. 0 signifie aucune limite (par défaut).

Max weight (kg) : le mode est masqué au-dessus de ce poids de panier. Par défaut : 31.5, car une Packstation accepte les colis jusqu'à 31,5 kg. 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 cette valeur. Laissez vide pour toujours l'afficher.

Geo Zone : propose le mode uniquement dans 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 utilisé avec Ignore shipping zones.

Ignore shipping zones : lorsqu'il est activé, le mode est proposé pour les pays ci-dessous (tous les pays si la liste est vide), quelle que soit la zone géographique de l'adresse.

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

Avancé

Debug log : écrit les requêtes d'API et les étapes du paiement dans storage/logs/vfd_dhlp_debug.log.php (sur OpenCart 4, dans system/storage/logs/vfd_dhlp_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. La clé d'API, le Postnummer et les adresses des clients ne sont jamais écrits. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_dhlp_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 recherches en cache, le journal et les points des paiements inachevés. Les points choisis restent dans les commandes. Si désactivé (par défaut), tout est conservé pour une réinstallation.

Importation / Exportation

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé d'API n'est pas exportée.

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. La clé d'API enregistrée est conservée.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix de DHL Packstation. Si une Geo Zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, le mode 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 qu'une clé d'API et au moins un type de point sont définis, les pays autorisés (avec Ignore shipping zones), le poids du panier et le sous-total minimal. Elle prend ensuite le prix du pays de destination (ou le prix des autres pays) et applique la livraison gratuite si le sous-total est suffisant. Le sous-total est le prix des produits nécessitant une livraison, après remise du coupon et avant taxes. Le prix ne dépend pas du point de retrait, et aucune requête n'est envoyée à DHL pour le calculer. Il est calculé dans votre devise par défaut et affiché au client dans sa devise, avec la taxe de la Tax Class sélectionnée.

L'extension ne crée pas d'expéditions DHL, n'imprime pas d'étiquettes et ne suit pas les colis. Utilisez le portail clients professionnels de DHL ou un outil d'étiquetage : avec Shipping address activé, la commande contient déjà l'adresse de la Packstation et le Postnummer. L'extension ne calcule pas de tarifs DHL en temps réel et n'affiche pas de carte. Il n'existe pas de saisie manuelle d'un numéro de Packstation.

Points de retrait

Lorsque le client sélectionne DHL Packstation à l'étape du mode de livraison, un sélecteur apparaît sous le mode. Les points DHL proches du code postal et de la ville de livraison sont chargés. Le client peut saisir un autre code postal ou une autre ville et cliquer sur Search. Les points sont regroupés par type (Packstation, Post Office, Parcel Shop) et triés par distance. Si rien n'est trouvé, le client voit No DHL locations found near "…". Try another postcode or city.

Pour une Packstation, le client doit saisir le DHL Postnummer, son numéro de client DHL de 6 à 12 chiffres, issu de l'application DHL ou de son compte DHL. Pour les autres points, il est facultatif. Le choix est enregistré dès qu'il est fait. Au clic sur Continue, le serveur le vérifie à nouveau : le point doit figurer parmi les résultats de recherche DHL dans le pays de livraison. Sans point, le client voit Please choose a DHL Packstation or post office for delivery. et ne peut pas continuer. Un Postnummer manquant pour une Packstation affiche Please enter your DHL Postnummer - it is required for delivery to a Packstation., et un Postnummer invalide affiche The DHL Postnummer must consist of 6 to 12 digits.

Les résultats de recherche sont mis en cache pendant 12 heures. Une recherche vide ou échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas DHL à chaque actualisation. Avec le cache fichier par défaut d'OpenCart, les entrées vivent au plus aussi longtemps que la durée de vie du cache de la boutique (1 heure par défaut), la liste est donc actualisée une fois par heure. Le délai d'attente de l'API est de 12 secondes. Si l'API DHL est injoignable, le client voit DHL locations cannot be loaded right now. Please try again later or choose another shipping method. Un point déjà choisi par le client reste accepté.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit DHL Packstation dans la fenêtre Shipping method options. Le sélecteur apparaît dans cette fenêtre, sous le mode, et fonctionne comme décrit ci-dessus. Le bouton Continue de la fenêtre ne permet pas de poursuivre sans point valide ou, pour une Packstation, sans le Postnummer, avec les mêmes messages.

Lorsque la commande est passée, le point (ID, type, numéro, nom, adresse) et le Postnummer sont enregistrés avec la commande. Le point est ajouté au mode de livraison de la commande sous les libellés DHL pickup location: et DHL Postnummer:, afin d'apparaître partout où OpenCart affiche le mode de livraison : la page de commande du client, les e-mails de commande et la facture. Si Shipping address est activé, l'adresse de livraison de la commande est remplacée par l'adresse du point.

Sur OpenCart 4, une seule commande est conservée pour le paiement et mise à jour à chaque nouvelle confirmation du client. Le point, le texte du mode de livraison et l'adresse de la commande sont mis à jour avec elle.

Commandes

Ouvrez la commande dans Sales > Orders. Le panneau DHL pickup location au-dessus de l'historique de la commande affiche le point, son type et son ID, ainsi que le Postnummer, même après la désactivation de l'extension. Une commande sans point affiche No DHL location was selected for this order.

Cliquez sur Change, recherchez par code postal ou par ville, choisissez un autre point dans la liste DHL, modifiez le Postnummer si nécessaire et cliquez sur Save location. Vous pouvez aussi modifier uniquement le Postnummer. Le texte du mode de livraison de la commande est mis à jour. Si Shipping address est activé, l'adresse de livraison de la commande est mise à jour elle aussi, en repartant de l'adresse d'origine du client. Chaque modification ajoute à l'historique de la commande une entrée DHL pickup location changed to: …, avec le statut actuel de la commande et sans notifier le client. Modifier le point nécessite l'autorisation de modification des commandes ; l'accès aux réglages de l'extension n'est pas requis.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DHL Packstation est le premier bloc de Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit, au-dessus des réglages. Saisissez la clé dans License key puis 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-dhl-packstation et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify 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, le mode de livraison DHL Packstation 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. Une fois la page Edit ouverte une fois, 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 licence.

Dépannage

DHL Packstation n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo Zone (ou activez Ignore shipping zones et vérifiez Countries (ignore zones)). Vérifiez que la DHL API key est renseignée, qu'au moins un type de point est sélectionné, que le pays de destination a un prix (ou que Other countries est défini), et que les règles de poids et de sous-total ne le masquent pas. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Aucun point n'est affiché : cliquez sur Test API key. Si DHL rejette la clé (401/403), vérifiez la clé et que votre application dispose de l'API « Location Finder - Unified ». Activez Debug log, rechargez le paiement et consultez le champ Log de la page de l'extension. Vérifiez que la limite de requêtes de votre application DHL n'est pas atteinte.

Aucun point près d'une adresse : augmentez le Search radius (meters) ou le Max results, ou laissez le client rechercher un autre code postal ou une autre ville. Une Packstation sans numéro dans les données DHL n'est pas listée.

Le client voit « Enter your postcode or city to see DHL locations near you. » : l'adresse de livraison n'a ni code postal ni ville. Le client peut en saisir un dans le champ de recherche.

Change sur la page de commande de l'administration affiche « Please choose a DHL location of the search - nothing was changed. » : recherchez par code postal ou par ville et choisissez un point dans les résultats. Si la commande n'a pas encore de point, il faut en choisir un avant de pouvoir enregistrer le Postnummer.

Le panneau DHL pickup location est absent de la page de commande : le panneau n'est affiché que pour les commandes expédiées avec DHL Packstation (il reste visible lorsque l'extension est désactivée).

La page indique « Warning: You do not have permission to modify VibeFox DHL Packstation! » : 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_packstation (OpenCart 3) ou extension/vfd_dhl_packstation/shipping/vfd_dhl_packstation (OpenCart 4) dans System > Users > User Groups.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox DHL Packstation. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable/Disable, Sort Order, Tax Class et Geo Zone. Le cache des points et les événements de l'extension sont toujours supprimés. Si Remove data on uninstall est activé, les réglages, le journal et les points des paiements inachevés 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 points choisis restent toujours dans les commandes, et les commandes existantes conservent leur mode de livraison, leur coût et leur adresse.

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 Packstation dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléchargé.

DHL et Packstation sont des marques déposées de leurs propriétaires respectifs. Cette extension n'est ni affiliée à DHL ni approuvée par DHL.