VibeFox DHL Packstation for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x. Les thèmes Classic et Hummingbird sont pris en charge.

PHP : 8.0 ou ultérieur. Le module refuse l'installation sur les versions antérieures de PHP.

DHL API key : la liste des points provient de l'API gratuite DHL Location Finder. Inscrivez-vous sur le portail développeurs DHL (developer.dhl.com), créez une application, ajoutez l'API « Location Finder - Unified » et copiez la clé API de l'application. Cette API ne nécessite aucun contrat professionnel avec DHL. Sans la clé, le transporteur est masqué au tunnel de commande. Tenez compte de la limite de requêtes de votre application DHL : chaque nouvelle recherche par code postal ou par ville compte comme une requête API.

VibeFox license key : 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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox DHL Packstation 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. Collez la clé API DHL, cliquez sur Save, puis sur Test API key. Choisissez les types de points et saisissez les prix par pays (voir Configuration).

À l'installation, le module crée le transporteur DHL Packstation avec le texte de délai de livraison Delivery to a DHL Packstation or post office. Le transporteur est activé, attribué à tous les groupes de clients et aux zones d'Allemagne et d'Autriche (les pays de la grille tarifaire par défaut). Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de prix ici : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox DHL Packstation > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Si un champ comporte une erreur (un nombre non valide ou négatif, Min weight (kg) supérieur à Max weight (kg), un nom de plus de 64 caractères), rien n'est enregistré et l'erreur s'affiche en haut. Chaque enregistrement vide le cache des points.

Les avertissements affichés au-dessus des réglages indiquent : que le transporteur est introuvable ; que l'unité de poids de la boutique (International > Localization, Local units) n'est pas reconnue par le module (les poids sont alors lus en kg ; utilisez kg, g, lb ou oz) ; que la clé API DHL est vide ; qu'aucun type de point n'est activé ; et que des entrées de prix par pays ne sont pas au format CC:PRICE (ces entrées sont ignorées).

Général

Les groupes de clients, les zones et les limites de taille du transporteur se règlent dans Shipping > Carriers. Les réglages ci-dessous s'appliquent à toutes les zones.

Enable/Disable : 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. Par défaut : DHL Packstation. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax. PrestaShop ajoute cette taxe aux prix ci-dessous. Avec No tax, les prix sont définitifs.

DHL Location Finder API

DHL API key : la « API Key » de votre application sur developer.dhl.com. Sans elle, le transporteur est masqué au tunnel de commande. Après l'enregistrement, le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved API key : cochez cette case et enregistrez pour supprimer la clé enregistré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. Enregistrez d'abord les réglages. Il indique le nombre de points trouvés, si DHL a refusé la clé (401/403), ou si l'API n'a pas répondu correctement (détails dans le journal de débogage).

Points de retrait

Au tunnel de commande, 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 transporteur 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. Nombre entier ; les valeurs inférieures à 100 ou supérieures à 25000 m (le maximum DHL) sont ramenées à cette limite.

Max results : le nombre maximum de points affichés par recherche. Par défaut : 20. 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 d'adresse 1 devient par exemple « Packstation 105 » (ou « Postfiliale 502 » pour un Post Office ou un 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 nouvelle adresse n'est utilisée que par la commande et n'apparaît pas dans le carnet d'adresses du client.

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

Country prices : le prix par pays de destination, dans la devise par défaut de la 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 transporteur pour ces pays.

Calculation : Per order 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 du panier (produits nécessitant une livraison, après remises, avant taxes) à partir duquel cette livraison est gratuite. Laissez vide pour qu'elle ne soit jamais gratuite.

Disponibilité

Min weight (kg) : le poids minimum du panier. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie aucune limite.

Max weight (kg) : le transporteur est masqué au-delà de ce poids de panier. Par défaut : 31.5, car une Packstation accepte des colis jusqu'à 31,5 kg. 0 signifie aucune limite.

Minimum subtotal : n'afficher le transporteur que si le sous-total du panier (produits nécessitant une livraison, après remises, avant taxes) atteint au moins cette valeur. Laissez vide pour l'afficher toujours.

Ignore shipping zones : lorsqu'elle est activée, le transporteur est lié à toutes les zones actives (y compris celles créées plus tard) et proposé pour les pays ci-dessous, ou pour tous les pays si la liste est vide. Quand vous la désactivez, le transporteur retrouve les zones qu'il avait auparavant.

Countries (ignore zones) : les pays de destination pour ce mode. Ctrl/Cmd + clic pour sélectionner plusieurs pays. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log : enregistre les requêtes API et les étapes du tunnel de commande dans logs/vfd_dhlp_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs API sont toujours journalisées, même lorsque cette option est désactivée. La clé API, le Postnummer et les adresses des clients ne sont jamais écrits.

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 recherches en cache et les journaux. Les points choisis restent dans les commandes. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au tunnel de commande

À l'étape de livraison, PrestaShop demande au module le prix de DHL Packstation. 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 qu'une clé 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 minimum. Il prend ensuite le prix du pays de destination (ou le prix des autres pays) et applique la livraison gratuite si le sous-total est assez élevé. Le prix est calculé dans la devise par défaut de la boutique et affiché dans la devise du panier du client.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne crée pas d'envois DHL, n'imprime pas d'étiquettes et ne suit pas les colis. Utilisez le portail client professionnel DHL ou un outil d'étiquetage : avec Shipping address activé, la commande contient déjà l'adresse de la Packstation et le Postnummer. Le module 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, un sélecteur apparaît sous le transporteur. Les points DHL proches du code postal et de la ville de livraison sont chargés. DHL n'est interrogé que pour le transporteur sélectionné. 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 à 6-12 chiffres, présent dans l'application ou le compte DHL. Pour les autres points, il est facultatif. Le choix est enregistré dans le panier dès qu'il est fait. Au clic sur Continue, le serveur le vérifie à nouveau : le point doit faire partie des 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 ou invalide est signalé de la même manière.

Les résultats de recherche sont mis en cache pendant 12 heures. Une recherche vide ou en échec est mise en cache pendant 10 minutes, afin que le tunnel de commande n'attende pas DHL à chaque actualisation. 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é.

Lorsque la commande est passée, le point (ID, type, numéro, nom, adresse) et le Postnummer sont enregistrés avec la commande. Si Shipping address est activé, l'adresse de livraison de la commande est remplacée par l'adresse du point. Le point est affiché sur la page de confirmation de commande, dans Order history and details du compte client, ainsi que dans l'e-mail de confirmation de commande et dans l'e-mail de nouvelle commande du module Mail alerts ; les libellés DHL pickup location et DHL Postnummer sont alors ajoutés au nom du transporteur.

Sur la page de commande du back-office, le bloc DHL pickup location affiche le point, son type et son ID, ainsi que le Postnummer. Cliquez sur Change, recherchez par code postal ou par ville, choisissez un autre point, modifiez le Postnummer et cliquez sur Save location. Vous pouvez aussi ne modifier que le Postnummer. Chaque modification ajoute un message privé à la commande : DHL pickup location changed to: …. Si Shipping address est activé, l'adresse de livraison de la commande est également mise à jour. Modifier le point nécessite l'autorisation de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Si plusieurs commandes ont été créées à partir d'un même panier, le point n'appartient qu'à la première commande ; Change sur une autre commande de ce panier affiche The DHL location of this cart belongs to another order of the same cart - nothing was changed.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DHL Packstation est le premier bloc de la page Modules > Module Manager > VibeFox DHL Packstation > 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-packstation 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 Packstation n'est pas affiché aux clients au tunnel de commande, 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 tunnel de commande. 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 du module supprime toujours la clé de licence et le statut de la licence. Le Reset de ce module ne supprime aucune donnée : la clé et le statut sont donc conservés.

Dépannage

DHL Packstation n'apparaît pas au tunnel de commande : vérifiez que la licence est active et que Enable/Disable 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 (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. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

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

Aucun point près d'une adresse : augmentez Search radius (meters) ou 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.

Sur la page de commande, Change 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.

La page indique que le transporteur DHL Packstation est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module avec Reset dans Modules > Module Manager pour le recréer. Reset conserve l'état activé/désactivé d'un transporteur existant.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox DHL Packstation et choisissez Uninstall. La clé de licence, le statut de la licence et le cache des points 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, le journal et les points des paniers sans commande. Si cette option est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rétablit le statut du transporteur qu'il avait auparavant. Les points choisis restent toujours dans les commandes.

DHL et Packstation sont des marques de leurs titulaires respectifs. Ce module n'est ni affilié à DHL ni approuvé par DHL.