VibeFox Purolator for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP. L'extension SOAP de PHP n'est pas requise.

Purolator E-Ship Web Services (uniquement pour les tarifs en temps réel) : 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. Il vous faut aussi votre numéro de compte de facturation Purolator et le code postal canadien d'expédition. Si vous utilisez uniquement des prix fixes, vous n'avez pas besoin de clés d'API.

Clé de licence VibeFox : 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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Purolator dans la liste des modules et cliquez sur Configure.

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

4. Pour les tarifs en temps réel, remplissez la section Purolator API (live rates). Pour les tests, activez Development environment avec la clé de développement. Remplissez Country prices ou Fallback price si vous voulez des prix fixes ou un prix de secours (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur Purolator avec le texte de délai de livraison Purolator courier. Le transporteur est affecté à toutes les zones et à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. N'y définissez pas de prix : le prix vient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Purolator > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Chaque enregistrement vide aussi le cache des tarifs Purolator.

Si les tarifs en temps réel 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 d'API ni prix fixes, un avertissement s'affiche au-dessus des réglages. Un avertissement s'affiche aussi si l'unité de poids de la boutique n'est pas une unité connue du module (kg, g, lb, oz et similaires). Les poids des produits sont alors considérés en kg. Définissez l'unité de poids dans International > Localization (Local units).

Un champ numérique qui ne contient pas un nombre égal ou supérieur à 0 n'est pas enregistré. Un avertissement indique le champ et la valeur. Le champ reste vide, ou prend sa valeur par défaut pour les champs de poids. Une valeur incorrecte dans Country prices est enregistrée comme 0, et l'avertissement indique le pays et la colonne. Si Min cart weight est supérieur à Max cart weight, rien n'est enregistré et une erreur s'affiche.

Général

Enable Purolator : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et sur la page de paiement. Par défaut : Purolator. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax. Elle détermine si la boutique ajoute une taxe sur le coût de livraison. Pour les adresses canadiennes, le total Purolator inclut déjà la GST/HST/PST/QST. Voir Canadian sales taxes ci-dessous.

API Purolator (tarifs en temps réel)

Lorsque la clé d'API, le mot de passe et le compte de facturation sont renseignés, le prix provient du service web Purolator E-Ship Estimating. Si Purolator ne fournit aucun tarif, le prix fixe est utilisé, ou le transporteur est masqué lorsqu'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.

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é et le mot de passe d'API enregistrés.

Development environment : utilise l'environnement de développement de Purolator (devwebservices.purolator.com) 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 d'où partent les colis, par exemple L4W 5M8.

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 service le moins cher disponible est utilisé.

Canadian sales taxes : utilise les prix Purolator hors GST/HST/PST/QST. Pour les adresses canadiennes, le total Purolator inclut ces taxes. Activez cette option lorsque le transporteur a une règle de taxe dans Tax, afin que la taxe ne soit pas facturée deux fois.

CAD → (shop currency) rate : les prix 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 temps réel ne sont pas utilisés. Si votre devise par défaut est le CAD, laissez le champ vide.

Default product weight : en kg, utilisé pour chaque produit sans poids. Par défaut : 0.5. Les poids sont convertis depuis l'unité de poids de la boutique et envoyés à Purolator comme poids total en livres entières, arrondi au supérieur.

Prix fixes (utilisés sans identifiants d'API, et en secours lorsque l'API ne fournit aucun tarif)

Country prices : un prix 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 l'icône de corbeille pour en supprimer une. Choisissez * Default (all other countries) pour une ligne qui couvre tous les pays sans ligne propre. Chaque ligne a un prix 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 prix de taille vide ou égal à zéro utilise Base. Un Base à 0, ou un Base vide, signifie livraison gratuite pour les poids sans prix de taille propre. Les formats 9.99 et 9,99 sont acceptés. Les lignes sans aucun prix ne sont pas enregistrées, et une seule ligne par pays est conservée.

Fallback price : le prix pour un pays qui n'a pas de ligne dans Country prices ni de ligne *. Laissez-le vide pour masquer le transporteur pour ces pays.

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

Conditions

Min cart weight : en kg, masque le transporteur lorsque le panier pèse moins. 0 signifie aucune limite.

Max cart weight : en kg, masque le transporteur lorsque le panier pèse plus. Par défaut : 30. 0 signifie aucune limite.

Minimum order amount : affiche le transporteur seulement lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Aucune requête n'est alors envoyée à Purolator. Laissez vide pour ne jamais proposer la livraison gratuite.

Pour ces conditions, le poids du panier compte les produits sans poids comme 0.

Disponibilité sans zones d'expédition

Normalement, le transporteur est proposé dans les zones auxquelles il est affecté dans Shipping > Carriers.

Ignore shipping zones : propose Purolator pour les pays indiqués ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones, et les zones créées plus tard y sont aussi ajoutées. Désactiver l'option retire de nouveau ces zones.

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

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_prlr_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque le journal de débogage est désactivé. Les clés d'API, le compte de facturation et les codes postaux des clients ne sont pas journalisés. Désactivez le journal une fois terminé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages, le transporteur, les tarifs en cache et les journaux. Lorsqu'il est désactivé, tout est conservé pour une réinstallation.

Fonctionnement sur la page de paiement

À l'étape de livraison, PrestaShop demande au module le prix Purolator. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Avant que le client saisisse une adresse, le prix est estimé pour le pays que la boutique utilise pour ses estimations. Le module vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimal de commande. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Purolator. Il cherche ensuite un prix : d'abord le tarif Purolator en temps réel, puis le tableau par pays, puis le prix de secours. S'il n'y a aucun prix, le transporteur est masqué.

Avec des identifiants d'API, le module envoie à Purolator une requête 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, et 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 que saisi. Les dimensions (poids volumétrique) ne sont pas envoyées. Purolator répond en français ou en anglais, selon la langue du client. Purolator renvoie les prix de tous les services ; le module retient le service choisi ou le moins cher, retire les taxes de vente canadiennes si configuré, et convertit le prix depuis le CAD. Le prix est calculé dans la devise par défaut de votre boutique, puis affiché dans la devise du panier du client.

Chaque réponse est mise en cache pendant 1 heure. Une requête échouée est mise en cache pendant 10 minutes, afin qu'une panne de Purolator ne ralentisse pas chaque actualisation de la page de paiement. Le délai d'attente de l'API est de 10 secondes.

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

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 calcule que des tarifs. Il 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. Il n'utilise pas le Full Estimate (dimensions, plusieurs colis, options comme la signature ou les marchandises dangereuses), n'affiche pas de dates de livraison, n'affiche pas plusieurs services comme des transporteurs distincts et ne récupère pas automatiquement les taux de change.

Commandes

Lorsqu'une commande est passée avec un tarif Purolator en temps réel, le service est enregistré avec la commande. Les recalculs ultérieurs du panier ne le modifient pas. Sur la page de la commande dans le back office (Orders > Orders, ouvrez la commande), un bloc Purolator affiche le Purolator service (nom et code) et le Live rate (excl. tax). Les commandes dont le prix provient des prix fixes ou qui bénéficient de la livraison gratuite n'ont pas ce bloc.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Purolator est le premier bloc de la page Modules > Module Manager > VibeFox Purolator > 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) 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: presta-shipping-purolator et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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 Purolator n'est pas affiché aux clients sur la page de paiement, et aucun tarif n'est demandé ni calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sur 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 que vous travaillez dans le back-office : une fois par jour pendant les 14 premiers jours suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Purolator n'apparaît pas sur la page de paiement : vérifiez que la licence est active et que Enable Purolator est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids et Minimum order amount. Si Purolator ne fournit aucun tarif, le transporteur n'est affiché qu'avec un prix par pays, une ligne * ou un Fallback price. Les produits peuvent aussi être limités à certains transporteurs depuis la fiche produit.

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

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

Le tarif diffère du site Purolator : 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 le transporteur a une règle de taxe. Les prix sont convertis avec votre CAD → (shop currency) rate.

Une valeur a disparu après l'enregistrement : lisez l'avertissement affiché après Save. La valeur n'était pas un nombre égal ou supérieur à 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 du module. Cela vide le cache des tarifs Purolator.

La page indique que le transporteur Purolator est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Purolator et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), et les réglages, les services Purolator enregistrés sur les commandes et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés ; les commandes passées conservent leur service Purolator. Réinstaller le module, ou effectuer un Reset, redonne au transporteur le statut qu'il avait auparavant.

Purolator est une marque de son propriétaire respectif. Ce module n'est pas affilié à Purolator ni approuvé par la société.