VibeFox Purolator 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. L'extension SOAP de PHP n'est pas nécessaire.

Purolator E-Ship Web Services (uniquement pour les tarifs en direct) : inscrivez-vous à E-Ship Web Services dans le Purolator E-Ship Resource Centre sur le site de Purolator. Purolator fournit des clés et des mots de passe distincts pour les environnements de développement et de production. Vous avez aussi besoin de votre numéro de compte de facturation Purolator et du code postal canadien depuis lequel vous expédiez. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de clés 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 des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_purolator-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_purolator.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_purolator-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD, vous n'avez donc pas besoin de rafraîchir 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 Purolator 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. Collez 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. Pour les tarifs en direct, renseignez la section Purolator API (live rates) : clé API, mot de passe, numéro de compte de facturation, code postal canadien d'expédition et, si la devise de votre boutique n'est pas le CAD, le taux CAD. Pour tester, activez Development environment avec la clé de développement. Renseignez les Country prices ou le Fallback price si vous voulez des tarifs fixes ou un secours (voir Configuration). Activez Enable Purolator puis cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_purolator.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é.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Purolator, 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 des 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 Purolator et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages Purolator 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 Purolator > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi les tarifs Purolator mis en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Si les tarifs en direct ne peuvent pas fonctionner avec les valeurs enregistrées (clé, mot de passe ou compte de facturation manquant, pas de code postal canadien d'expédition, pas de taux CAD), ou s'il n'y a ni identifiants API ni tarifs fixes, un avertissement apparaît dans la section General. Il indique aussi si les tarifs fixes sont utilisés en attendant ou si le mode est masqué. Un avertissement apparaît également si l'unité de poids de la boutique n'est pas reconnue par l'extension. Les poids des produits sont alors lus en kg ; ajoutez une classe de poids avec l'unité kg dans System > Localisation > Weight Classes.

Un champ numérique qui ne contient pas un nombre supérieur ou égal à 0 n'est pas enregistré. Un message affiché après Save indique le champ et la valeur. Le champ reste vide, ou prend sa valeur par défaut pour les champs de poids. Une valeur erronée dans Country prices est enregistrée comme 0, et le message indique le pays et la colonne. Rien n'est enregistré et une erreur s'affiche si le titre du mode est vide ou dépasse 64 caractères, si Min cart weight (kg) est supérieur à Max cart weight (kg), si l'ordre de tri n'est pas un nombre entier, ou si la classe de taxe ou la zone géographique n'est pas valide.

Général

Le client voit un seul tarif Purolator. Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode à une zone géographique ou à des pays dans Availability.

Enable Purolator : affiche ou masque Purolator au moment du paiement. Par défaut : désactivé.

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

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Elle détermine si la boutique ajoute une taxe en plus. Pour les adresses canadiennes, le total Purolator inclut déjà la TPS, la TVH, la TVP et la TVQ (GST/HST/PST/QST). Voir plus bas Canadian sales taxes.

Sort order : la position de Purolator parmi les modes de livraison lors du paiement. Un nombre entier.

API Purolator (tarifs en direct)

Lorsque la clé API, le mot de passe et le compte de facturation sont renseignés, le tarif provient du service web Purolator E-Ship Estimating (Quick Estimate, selon le poids total du panier). Si Purolator ne renvoie aucun tarif, le tarif fixe est utilisé, ou le mode est masqué s'il n'y en a pas. La section contient un lien vers le Purolator E-Ship Resource Centre, où vous vous inscrivez et obtenez les clés. Les détails des erreurs vont dans le journal, jamais au client.

API key : votre clé E-Ship Web Services pour l'environnement sélectionné. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

API password : le mot de passe associé à la clé. Comme la clé, il n'est plus affiché après l'enregistrement.

Billing account number : votre numéro de compte Purolator. Les estimations utilisent les tarifs de ce compte. L'environnement de développement accepte le compte de test de la documentation Purolator. Vider ce champ supprime aussi la clé API et le mot de passe enregistrés.

Development environment : utilise l'environnement de développement de Purolator (devwebservices) avec la clé de développement. Les prix sont des données de test. Désactivez-le sur une boutique en production.

Ship-from postal code : le code postal canadien depuis lequel les colis sont expédiés, par exemple L4W 5M8. OpenCart n'a pas de code postal de boutique, il n'est donc pas repris de l'adresse de la boutique : saisissez-le ici.

Service in Canada : Cheapest available (par défaut), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM ou Purolator Express Evening.

Service to the USA : Cheapest available (par défaut), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM ou Purolator Express U.S. 12:00.

International service : Cheapest available (par défaut), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM ou Purolator Express International 12:00.

Si le service choisi n'est pas proposé pour l'adresse, le moins cher disponible est utilisé.

Canadian sales taxes : utilise les tarifs Purolator sans GST/HST/PST/QST. Pour les adresses canadiennes, le total Purolator inclut ces taxes. Activez cette option lorsque la boutique ajoute elle-même une taxe sur la livraison (une classe de taxe dans General), afin que la taxe ne soit pas facturée deux fois. Par défaut : désactivé.

CAD → (store currency) rate : les tarifs Purolator sont en CAD. Si la devise par défaut de votre boutique n'est pas le CAD, indiquez combien d'unités de votre devise vaut un CAD, par exemple 0.68. Sans cette valeur, les tarifs en direct ne sont pas utilisés. Si votre devise par défaut est le CAD, laissez le champ vide.

Default product weight (kg) : utilisé pour chaque produit sans poids. Par défaut : 0.5. Les poids sont convertis à partir de la classe de poids du produit et envoyés à Purolator comme poids total en livres entières, arrondi au supérieur.

Tarifs fixes (utilisés sans identifiants API, et comme secours lorsque l'API ne renvoie aucun tarif)

Country prices : un tarif par pays et par poids du panier, dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add country pour ajouter une ligne et sur le bouton × pour en supprimer une. Choisissez * Default (all other countries) pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne comporte un tarif Base et des colonnes de taille : XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg et XL au-delà de 5 kg. Un tarif de taille vide ou égal à zéro utilise Base. Un Base de 0, ou un Base vide, signifie livraison gratuite pour les poids sans tarif de taille propre. Les formats 9.99 et 9,99 sont acceptés. Les lignes sans aucun tarif ne sont pas enregistrées, et une seule ligne par pays est conservée.

Fallback price : le tarif pour un pays qui n'a ni ligne dans Country prices ni ligne *. Laissez-le vide pour masquer le mode pour ces pays.

Fixed price per : Order (par défaut) facture le tarif une seule fois. Item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne concerne que les tarifs fixes. Les tarifs en direct sont toujours calculés pour l'envoi complet.

Conditions

Min cart weight (kg) : masque le mode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).

Max cart weight (kg) : masque le mode lorsque le panier pèse davantage. Par défaut : 30. Si vous laissez le champ vide, 30 kg sont utilisés. 0 signifie aucune limite.

Minimum order amount : n'affiche le mode que lorsque le sous-total des produits à expédier (après le coupon, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total des produits à expédier (après le coupon, avant taxes) à partir duquel la livraison est gratuite. Aucune demande n'est alors envoyée à Purolator. Laissez vide pour ne jamais proposer la livraison gratuite.

Disponibilité

Geo zone : propose Purolator uniquement pour les adresses situées 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. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé.

Ignore shipping zones : propose le mode pour les pays indiqués ci-dessous, quelle que soit la zone géographique sélectionnée.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays activés dans votre boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_prlr_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_prlr_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même lorsque le journal de débogage est désactivé. Les clés API, le compte de facturation et les codes postaux des clients ne sont pas journalisés. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_prlr_debug.old.log.php et un nouveau journal est démarré.

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'il est activé, la désinstallation de l'extension supprime les réglages Purolator et le journal. Lorsqu'il est désactivé, ils sont conservés pour une réinstallation. Les tarifs mis en cache sont toujours supprimés. Le service Purolator des commandes passées est toujours conservé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé API et le mot de passe 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. La clé API et le mot de passe enregistrés sont conservés.

Fonctionnement lors du paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le tarif Purolator. Si une Geo zone est définie et que l'adresse se trouve en dehors, Purolator n'est pas proposé (sauf si Ignore shipping zones est activé). Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent ni poids ni montant de commande. L'extension vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Le montant de commande est le prix des produits à expédier, après la remise du coupon et avant taxes. Les cartes-cadeaux, les points de fidélité et les avoirs de boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le tarif est de 0 et aucune demande n'est envoyée à Purolator. Sinon, l'extension cherche un tarif : d'abord le tarif en direct de Purolator, puis le tableau par pays, puis le tarif de secours. S'il n'y a pas de tarif, le mode est masqué.

Avec des identifiants API, l'extension envoie à Purolator une demande Quick Estimate : votre compte de facturation, le code postal d'expédition, la ville, la province ou l'État du client, le pays et le code postal du client, ainsi que le poids total du panier en livres entières. Pour le Canada, un code postal valide est nécessaire ; pour les États-Unis, un code ZIP valide ; les autres pays sont envoyés avec le code postal tel qu'il a été saisi. Les dimensions (poids volumétrique) ne sont pas envoyées. Purolator répond en français lorsque le client consulte la boutique en français, et en anglais dans les autres cas. Purolator renvoie les tarifs de tous les services ; l'extension retient le service choisi ou le moins cher, retire les taxes de vente canadiennes si cela est configuré, et convertit le tarif à partir du CAD. Le tarif 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 réponse est mise en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle demande. Une demande échouée est mise en cache pendant 10 minutes, afin qu'une panne de Purolator ne ralentisse pas chaque mise à jour du paiement. Le délai d'attente de l'API est de 10 secondes.

Si Purolator ne renvoie aucun tarif (API indisponible, identifiants ou code postal erronés, service non disponible, pas de taux CAD), le client ne voit aucune erreur. Le tarif fixe est utilisé, ou le mode est masqué s'il n'existe pas de tarif fixe. La raison est écrite dans le journal.

L'extension ne calcule que des tarifs. Elle ne crée pas d'envois Purolator, n'imprime pas d'étiquettes, ne réserve pas d'enlèvements, ne gère pas les retours et ne suit pas les colis. Elle n'utilise pas la Full Estimate (dimensions, plusieurs colis, options comme la signature ou les marchandises dangereuses), n'affiche pas de dates de livraison, ne présente pas plusieurs services comme options distinctes et ne récupère pas automatiquement les taux de change. Le client ne voit pas le nom du service Purolator, seulement le titre de votre mode de livraison.

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

Commandes

Lorsqu'une commande est passée avec un tarif Purolator en direct, le service est enregistré avec la commande. Dans Sales > Orders, la page de commande affiche un panneau Purolator au-dessus de l'historique, avec le Purolator service (nom et code) et le Live rate (excl. tax). Le panneau reste visible même si le mode est désactivé ensuite. Les commandes tarifées à partir des tarifs fixes ou avec livraison gratuite n'ont pas ce panneau. La commande elle-même affiche le titre du mode et le coût de livraison comme tout autre mode de livraison OpenCart.

OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau. Le service Purolator enregistré est mis à jour avec elle au dernier tarif en direct. Si la commande passe à un autre mode de livraison ou à un tarif sans tarif en direct, le service enregistré est retiré de la commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Purolator est le premier bloc de Extensions > Extensions > Shipping > VibeFox Purolator > 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-purolator 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é une place 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 OpenCart. Supprimer 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 Purolator n'est pas affiché aux clients lors du paiement et aucun tarif n'est demandé ni calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (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 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 licence.

Dépannage

Purolator n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable Purolator est activé. Vérifiez la Geo zone (ou que Ignore shipping zones est activé et que le pays est autorisé), les limites de poids et le Minimum order amount. Si Purolator ne renvoie aucun tarif, le mode n'est affiché qu'avec un tarif par pays, une ligne * ou un Fallback price. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en direct n'apparaissent pas : consultez le champ Log sur la page de l'extension. Les erreurs de l'API y figurent toujours. Activez le Debug log et rechargez la page de paiement pour obtenir des détails. Avec des clés API, l'adresse doit comporter un code postal valide (Canada) ou un code ZIP valide (États-Unis). Vérifiez aussi les avertissements de la section General.

HTTP 401 dans le journal : la clé API ou le mot de passe ne correspond pas à l'environnement sélectionné. Les clés de développement ne fonctionnent que lorsque Development environment est activé, les clés de production seulement lorsqu'il est désactivé.

Le tarif diffère de celui du site Purolator : la Quick Estimate utilise les tarifs de votre compte de facturation et le poids total arrondi au supérieur en livres entières, sans poids volumétrique. Pour les adresses canadiennes, le total inclut les taxes de vente ; utilisez Canadian sales taxes si vous avez défini une Tax class. Les prix sont convertis avec votre CAD → (store currency) rate.

Une valeur a disparu après l'enregistrement : lisez le message affiché après Save. La valeur n'était pas un nombre supérieur ou égal à 0, elle n'a donc pas été enregistrée. Saisissez-la de nouveau sous forme de nombre simple.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs Purolator mis en cache.

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

Pour les développeurs : l'adresse de l'API Purolator peut être remplacée par le réglage vfd_prlr_api_url (pour les tests) ; il n'a pas de champ sur la page de réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Purolator. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Purolator, Sort order, Tax class et Geo zone. Les tarifs mis en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Purolator 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 de l'extension. Les commandes existantes conservent leur mode de livraison et leur coût, et les services Purolator enregistrés des commandes sont toujours conservés.

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

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