VibeFox DPD Pickup 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.

Identifiants DPD Baltic (Lituanie, Lettonie, Estonie) : la liste des points relais provient du service web DPD Baltic. Vous avez besoin du nom d'utilisateur et du mot de passe de l'API que DPD fournit à ses clients professionnels. Demandez à votre gestionnaire de compte DPD ou au service client DPD de votre pays. Un compte DPD Baltic liste les points relais de Lituanie, de Lettonie et d'Estonie.

DPD Slovaquie : la recherche publique de points relais DPD Slovaquie ne nécessite aucun identifiant.

Classe de poids : les poids des produits sont convertis en kg. Votre boutique a besoin d'une classe de poids avec l'unité kg dans System > Localisation > Weight Classes (OpenCart en propose une par défaut).

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 OpenCart 3 vfd_dpd_pickup-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_dpd_pickup.ocmod.zip. N'installez que 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_dpd_pickup-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 aussi 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 DPD Pickup et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton 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. Choisissez votre API DPD. Pour DPD Lituanie, Lettonie ou Estonie, saisissez le nom d'utilisateur et le mot de passe de l'API. Vérifiez les tarifs par pays, activez Enable/Disable et cliquez sur Save. Cliquez ensuite sur Refresh pickup points pour vérifier la connexion (voir Configuration).

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_dpd_pickup.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 DPD Pickup, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton 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, la méthode reste désactivée tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi les listes de points relais en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages, actualiser les points relais ou vider le journal.

Des avertissements en haut de la page signalent que le nom d'utilisateur ou le mot de passe DPD Baltic est vide, ou qu'aucun tarif n'est défini (dans les deux cas, la méthode n'est pas affichée au paiement), ainsi que l'absence d'une classe de poids avec l'unité kg dans la boutique (les poids des produits sont alors lus d'après le nom de leur unité, les unités inconnues étant traitées comme des kg). Certaines valeurs empêchent l'enregistrement, et rien n'est alors enregistré : un Name vide ou de plus de 64 caractères, un Sort order qui n'est pas un nombre entier, et un Min weight (kg) supérieur au Max weight (kg). Une valeur qui n'est pas un nombre, ou un nombre négatif, dans un champ de montant ou de poids n'est pas enregistrée : le champ devient vide et un avertissement le signale, tandis que les autres réglages sont enregistrés. Les lignes de Country prices qui ne sont pas au format CC:PRICE sont listées dans un avertissement et ignorées.

Général

La méthode est proposée dans la zone géographique définie dans Availability (toutes les zones si aucune n'est choisie), ou avec Ignore shipping zones dans les pays choisis ici.

Enable/Disable : affiche ou masque DPD Pickup au paiement. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client au paiement. Par défaut : DPD Pickup Point. Obligatoire, 64 caractères au maximum.

Tax class : la classe de taxe appliquée au prix de livraison, ou None (par défaut) pour aucune taxe.

Sort order : la position de la méthode dans la liste des modes de livraison. Un nombre entier.

Liste des points relais DPD

Les points relais sont chargés depuis DPD et mis en cache (voir Fonctionnement au paiement).

DPD API : l'entreprise DPD auprès de laquelle vous avez un compte. Les comptes Baltic utilisent le service web de leur propre pays.

API username (Baltic) : votre nom d'utilisateur du service web DPD Baltic. Non nécessaire pour DPD Slovaquie. Le vider efface aussi le mot de passe enregistré.

API password (Baltic) : votre mot de passe du service web DPD Baltic. Non nécessaire pour DPD Slovaquie. 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.

Pickup points : le bouton Refresh pickup points vide le cache et charge maintenant les points relais depuis DPD : Lituanie, Lettonie et Estonie pour l'API Baltic, et une recherche test à Bratislava pour DPD Slovaquie. Il affiche le nombre de points relais ou l'erreur par pays. Enregistrez d'abord les réglages.

Tarifs

Les tarifs de livraison sont fixes par pays, dans la devise par défaut de votre boutique, hors taxes. Les tarifs DPD ne sont pas demandés à l'API.

Country prices : une ligne par pays : CC:prix, par exemple EE:3.50. Une virgule décimale est acceptée. Par défaut : SK:3.50, LT:4.00, LV:4.00, EE:4.00.

Fallback cost : le prix pour les pays absents de Country prices. Par défaut : 5.00. Laissez-le vide pour ne proposer la méthode que dans les pays listés.

Calculation type : 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 : la livraison est gratuite lorsque le sous-total de la commande (après remises, avant taxes) atteint ce montant. Laissez vide pour la désactiver.

Disponibilité

La méthode est aussi masquée lorsque DPD ne renvoie aucun point relais pour l'adresse du client ou lorsque l'API DPD est injoignable, car une commande ne peut pas être livrée sans point relais.

Min weight (kg) : le poids minimal du panier. Les poids des produits sont convertis depuis leur classe de poids. Vide ou 0 signifie aucune limite.

Max weight (kg) : les paniers plus lourds ne voient pas la méthode. Par défaut : 31.5. Vide ou 0 signifie aucune limite. Vérifiez les limites de poids des colis des points relais et consignes DPD Pickup de votre pays.

Minimum subtotal : n'affiche la méthode que si le sous-total de la commande (après remises, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Geo zone : propose la méthode 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 utilisé avec Ignore shipping zones.

Ignore shipping zones : lorsqu'elle est activée, la zone géographique n'est pas vérifiée et la méthode est proposée dans les pays indiqués ci-dessous. Désactivée (par défaut), seule la zone géographique ci-dessus est utilisée.

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

Sélecteur de point relais

City order : affiche d'abord les grandes villes (Tallinn, Riga, Vilnius, Bratislava et d'autres). Activé par défaut.

City list width : la largeur CSS de la liste des villes, par exemple 100% ou 300px. Par défaut : 100%.

Pickup point list width : la largeur CSS de la liste des points relais, par exemple 100% ou 400px. Par défaut : 100%.

Avancé

Debug log : écrit les requêtes API et les étapes du paiement dans storage/logs/vfd_dpd_debug.log.php (sous OpenCart 4, dans system/storage/logs/vfd_dpd_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées, même lorsque cette option est désactivée. Les identifiants ne sont jamais enregistrés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_dpd_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 : lorsqu'elle est activée, la désinstallation de l'extension supprime ses réglages, le journal et les choix des paiements non terminés. Le point relais enregistré dans les commandes est toujours conservé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le mot de passe de l'API n'est pas exporté.

Import : collez un 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. Le mot de passe de l'API enregistré est conservé.

Fonctionnement au paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix de DPD Pickup. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve hors de cette zone, la méthode n'est pas proposée. 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 les pays (avec Ignore shipping zones), le poids du panier et le sous-total minimal, prend le prix du pays (ou le coût de repli) et applique la livraison gratuite si le sous-total est assez élevé. Le sous-total est le prix des produits à expédier, après la remise du coupon et avant taxes.

Elle charge ensuite les points relais DPD pour l'adresse. Si DPD n'en renvoie aucun, ne répond pas ou si les identifiants Baltic manquent, la méthode est masquée. Avec DPD Slovaquie, la méthode est affichée tant que la ville ou le code postal manque, et les points apparaissent une fois l'adresse complète. Le prix est calculé dans la devise par défaut et affiché au client dans sa devise avec la taxe de la Tax class choisie.

Une liste de points relais est mise en cache jusqu'à 24 heures, une liste vide jusqu'à 1 heure, mais jamais au-delà de la durée de vie du cache d'OpenCart (1 heure par défaut). Une requête échouée est mémorisée pendant 5 minutes, de sorte qu'une panne de DPD ne ralentit jamais le paiement. Le délai d'attente de l'API est de 15 secondes.

L'extension ne demande pas les tarifs DPD, ne crée pas d'envois DPD, n'imprime pas d'étiquettes, ne crée pas de bordereaux, ne commande pas d'enlèvements de coursiers, ne suit pas les colis et n'affiche pas de carte. Seuls le service web DPD Baltic et la recherche de points relais DPD Slovaquie sont pris en charge.

Points relais

Lorsque le client sélectionne DPD Pickup, une liste de villes et une liste de points relais apparaissent sous la méthode. La ville de l'adresse du client est présélectionnée. Le choix est enregistré dès que le client le fait. Avec DPD Slovaquie, le client voit Enter your city and postcode to see the DPD pickup points nearby. tant que l'adresse n'est pas complète, puis les points proches. Si DPD n'a aucun point pour l'adresse, le client voit No DPD pickup points are available for this address right now. Please check the address or choose another shipping method.

Un point relais est obligatoire. Sans lui, le client ne peut pas continuer et voit Please select a DPD pickup point. Lorsque le client clique sur Continue, le serveur vérifie que le point appartient à la liste DPD pour l'adresse du client. Un choix falsifié ou périmé est refusé avec The selected DPD pickup point is not available for this address. Please choose another one. Si la liste DPD ne peut pas être chargée à ce moment-là, le point déjà choisi par le client est accepté, et la commande affiche son ID au lieu du nom.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit DPD Pickup dans la fenêtre Shipping method options. La liste des villes et la liste des points relais apparaissent dans cette fenêtre, sous le mode, et fonctionnent comme décrit ci-dessus. Le bouton Continue de la fenêtre ne permet pas d'aller plus loin sans point relais, avec les mêmes messages.

Le point choisi est ajouté au mode de livraison de la commande, par exemple DPD Pickup Point: name, street, postcode city avec le titre par défaut, ou My title - DPD pickup point: name, street, postcode city avec votre propre titre (128 caractères au maximum). Il apparaît ainsi dans la commande côté administration, dans l'historique des commandes du client, dans les e-mails de commande et sur la facture. Le nom enregistré dans la commande provient de DPD, et non du navigateur.

Sous OpenCart 4, le texte du mode de livraison peut comporter jusqu'à 255 caractères. OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau, et le point relais de la commande est mis à jour avec elle.

Sur la page de commande de l'administration (Sales > Orders), le panneau DPD pickup point au-dessus de l'historique affiche le nom du point, son ID et son pays. Cliquez sur Edit, choisissez une ville et un autre point, puis cliquez sur Save. Le point est vérifié par rapport à la liste DPD pour l'adresse de la commande, et le panneau affiche Pickup point updated. ou Pickup point not found for the order address. Le texte du mode de livraison de la commande est mis à jour, et une note est ajoutée à l'historique de la commande (non envoyée au client) avec l'ancien point, le nouveau point et l'utilisateur administrateur. Modifier le point nécessite l'autorisation de modification des commandes, et non l'accès aux réglages de l'extension. Avec DPD Slovaquie, la commande doit avoir une ville et un code postal de livraison, sinon le panneau affiche Add the shipping city and postcode to change the pickup point. Une commande passée sans point affiche No pickup point was selected for this order., et le journal de débogage contient une erreur pour elle. Le panneau et Edit fonctionnent aussi après la désactivation de l'extension.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DPD Pickup est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox DPD Pickup > Edit, au-dessus des réglages. Collez 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: opencart-shipping-dpd-pickup et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs 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 DPD Pickup n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), ce qui vous permet de configurer et de 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, la méthode est masquée 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

DPD Pickup n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et de sous-total, et que le pays a un prix (ou un coût de repli). Consultez les avertissements en haut de la page de l'extension et cliquez sur Refresh pickup points. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Une erreur après Refresh pickup points : le résultat affiche l'erreur DPD par pays. Par exemple, « Login failed » signifie que DPD a rejeté les identifiants Baltic, de sorte qu'aucun point relais ne peut être chargé. Vérifiez le nom d'utilisateur et le mot de passe de l'API auprès de DPD.

DPD Slovaquie n'affiche aucun point : les points apparaissent une fois que le client a saisi la ville et le code postal. DPD ne liste que les points situés à moins de 50 km de cette adresse.

Pour trouver la cause : activez Debug log, rechargez la page de paiement et consultez le champ Log de la page de l'extension. Les erreurs de l'API sont toujours enregistrées. Les noms d'utilisateur et mots de passe de l'API ne sont jamais écrits dans le journal.

Les points relais semblent obsolètes après une modification : cliquez sur Save ou Refresh pickup points sur la page de l'extension. Les deux actions vident les listes en cache.

La page affiche « Warning: You do not have permission to modify VibeFox DPD Pickup! » : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_dpd_pickup (OpenCart 3) ou extension/vfd_dpd_pickup/shipping/vfd_dpd_pickup (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : le rayon de recherche de DPD Slovaquie peut être modifié par une autre extension avec l'événement OpenCart vfd_dpd_pickup/sk_search_radius.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox DPD Pickup. 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. L'extension supprime toujours ses événements et les listes de points relais en cache. Si Remove data on uninstall est activé, les autres réglages, le journal de débogage et les choix des paiements non terminés sont également supprimés. S'il est désactivé, les réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Le point relais enregistré dans les commandes n'est jamais supprimé, et les commandes existantes conservent leur mode de livraison et leur coût.

Sous 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 DPD Pickup dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléversé.

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