VibeFox Canada Post 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.

Canada Post Developer Program (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent la Rating API de Canada Post. Inscrivez-vous au Canada Post Developer Program sur le site de Canada Post et copiez votre clé d'API et votre numéro de client. La clé d'API a la forme username:password, et Canada Post fournit des clés distinctes pour les environnements de développement (sandbox) et de production. Vous avez aussi besoin du 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 Canada Post 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, saisissez le nom d'utilisateur et le mot de passe de l'API, votre numéro de client et le code postal d'expédition. Si la devise par défaut de votre boutique n'est pas le CAD, saisissez le taux CAD. Remplissez Country prices si vous voulez des prix fixes ou une solution de secours (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur Canada Post avec le texte de délai de transit Canada Post parcel delivery. 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 transit, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Canada Post > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs Canada Post. L'enregistrement nécessite l'autorisation de configuration du module.

Si une valeur est incorrecte, la page affiche une erreur et rien n'est enregistré : un champ numérique ou un prix dans Country prices qui n'est pas un nombre égal ou supérieur à 0 (par exemple -1 ou 12abc), un taux CAD de 0, Min cart weight (kg) supérieur à Max cart weight (kg), ou un Method title de plus de 64 caractères. Si l'unité de poids ou de dimension de votre boutique n'est pas connue du module, la page avertit que les poids sont lus en kg (les dimensions en cm). Réglez kg, g, lb ou oz (cm, mm, m ou in) dans International > Localization, section Local units.

Après l'enregistrement, la page affiche un avertissement lorsque les réglages ne peuvent pas fonctionner comme prévu : seul l'un des deux champs nom d'utilisateur et mot de passe de l'API est rempli, le code postal d'expédition n'est pas un code postal canadien (format A1A 1A1), le taux CAD manque pour une boutique dans une autre devise, ou il n'y a ni identifiants d'API ni prix fixes. L'avertissement indique aussi ce qui se passe entre-temps : les prix fixes par pays sont utilisés, ou le transporteur est masqué au paiement lorsque le tableau Country prices est vide.

Général

Enable Canada Post : 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é au client lors du paiement. Par défaut : Canada Post, même si le champ est laissé vide. Jusqu'à 64 caractères, sans les caractères que PrestaShop n'autorise pas dans les noms de transporteurs.

Tax : la règle de taxe que PrestaShop ajoute au coût de livraison, ou No tax (non imposable).

API Canada Post (tarifs en temps réel)

Lorsque le nom d'utilisateur et le mot de passe de l'API sont renseignés, le prix provient de la Rating API de Canada Post. Si l'API ne renvoie aucun tarif (API indisponible, code postal incorrect, service non disponible), le prix fixe de Country prices est utilisé, ou le transporteur est masqué s'il n'y en a pas. La section renvoie vers le Canada Post Developer Program, où vous trouvez les clés d'API et votre numéro de client. Les détails d'erreur vont dans le journal, jamais au client.

API username : la partie de la clé d'API avant les deux-points. Utilisez la clé de développement avec Sandbox et la clé de production sur une boutique en production.

API password : la partie de la clé d'API après les deux-points. Après l'enregistrement, le champ reste vide et indique A password is saved. Leave empty to keep it; clear the username and save to remove both. Ne saisissez une nouvelle valeur que pour la modifier. Le mot de passe est enregistré exactement tel que saisi et n'est jamais écrit dans le journal.

Customer number : avec un numéro de client, Canada Post renvoie les tarifs commerciaux (remisés) de votre compte. Laissez vide pour les tarifs au guichet. Les espaces sont supprimés.

Contract number : facultatif, pour les clients sous contrat. Il n'est utilisé qu'avec le numéro de client.

Sandbox : utilise l'environnement de développement de Canada Post, pour tester avec la clé d'API 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ù les colis sont expédiés, par exemple K1A 0B1. Les tarifs en temps réel en ont besoin.

Service in Canada : le service pour les adresses canadiennes : Cheapest available, Regular Parcel (DOM.RP, par défaut), Expedited Parcel (DOM.EP), Xpresspost (DOM.XP) ou Priority (DOM.PC).

Service to the USA : Cheapest available (par défaut), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) ou Priority Worldwide parcel USA (USA.PW.PARCEL).

International service : Cheapest available (par défaut), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) ou Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST : pour les adresses canadiennes, le prix de Canada Post inclut ces taxes. Activez-le lorsque PrestaShop ajoute lui-même une taxe sur la livraison (Tax ci-dessus), afin que la taxe ne soit pas facturée deux fois.

CAD to … rate : le nom du champ indique la devise par défaut de votre boutique, par exemple CAD to USD rate. Les prix de Canada Post sont en CAD. Si votre devise par défaut n'est pas le CAD, saisissez combien d'unités de votre devise vaut un CAD, par exemple 0.68. Sans lui, les tarifs en temps réel ne sont pas utilisés. Si votre devise par défaut est le CAD, laissez le champ vide. Le taux doit être supérieur à 0. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Default product weight (kg) : envoyé à Canada Post pour chaque produit sans poids. Par défaut : 0.5. Les poids des produits (dans l'unité de poids de votre boutique) et les dimensions sont convertis, et le panier est tarifé comme un seul colis.

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

Country prices : un tableau de pays avec un prix Base et des prix selon le poids du panier dans la devise par défaut de votre boutique, hors taxes : XS jusqu'à 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL au-delà de 5 kg. Un prix de taille vide ou nul utilise le prix Base. Cliquez sur Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * Default (all other countries) définit les prix de tous les pays qui n'ont pas leur propre ligne. Un pays sans ligne (et sans *) n'a pas de prix fixe. Un prix de base de 0 signifie livraison gratuite pour ce pays. Une ligne sans aucun prix n'est pas enregistrée.

Fixed price per : Order facture le prix une seule fois. Item (price x quantity) le multiplie par le nombre d'articles du panier. Cela ne s'applique qu'aux prix fixes. Les tarifs en temps réel sont toujours calculés pour le colis entier.

Conditions

Min cart weight (kg) : masque le transporteur en dessous de ce poids de panier. 0 signifie pas de limite.

Max cart weight (kg) : masque le transporteur au-dessus de ce poids de panier. Par défaut : 25, même si le champ est vide. 0 signifie pas de limite. Les colis Canada Post peuvent peser jusqu'à 30 kg. Cette valeur ne peut pas être inférieure à Min cart weight (kg).

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

Free shipping : active la livraison gratuite à partir du montant ci-dessous.

Free shipping from : le sous-total du panier à partir duquel la livraison est gratuite. Aucune requête API n'est alors envoyée. Utilisé uniquement lorsque Free shipping est activé.

Disponibilité sans zones de livraison

Normalement, le transporteur est affiché dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur pour les pays ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones, ainsi qu'aux zones que vous créerez plus tard. Lorsque vous désactivez l'option et enregistrez, les zones ajoutées par le module sont retirées et le transporteur conserve ses propres zones.

Countries : les pays de destination pour ce mode. Maintenez Ctrl (Cmd) enfoncé pour en sélectionner plusieurs. Laissez vide pour autoriser tous les pays actifs. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : enregistre les calculs de tarifs dans var/logs/vfd_canada_post.log.php. Le fichier ne peut pas être ouvert depuis le web et il est archivé à 5 Mo. Les erreurs d'API sont toujours enregistrées, même lorsque cette option est désactivée. Les clés d'API, les numéros de client et les codes postaux des clients ne sont pas enregistrés.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages, les services enregistrés des commandes, les tarifs en cache et le journal. Le transporteur est toujours retiré du paiement à la désinstallation. Les commandes ne sont jamais modifiées.

Log : le panneau sous les réglages affiche le nom du fichier et les 50 dernières entrées. Cliquez sur Clear log pour le supprimer.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix Canada Post. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Canada Post.

Avec des identifiants d'API, le module envoie à Canada Post le code postal d'expédition, la destination, le poids du colis et, lorsque chaque produit a des dimensions, la taille estimée du colis. Pour le Canada, la destination est le code postal ; pour les États-Unis, le code ZIP ; pour tous les autres pays, seulement le pays. Un tarif en temps réel n'est demandé que lorsqu'une adresse canadienne ou américaine comporte un code postal ou ZIP valide. Canada Post renvoie tous les services pour le colis. Le module retient le service choisi du groupe de destination, ou le moins cher, retire les taxes de vente canadiennes (GST/HST/PST) si Use Canada Post prices without GST/HST/PST est activé, et convertit le prix en CAD avec votre taux. 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, afin que le même panier et la même adresse ne déclenchent pas une nouvelle requête. Une requête échouée est mise en cache pendant 10 minutes, afin qu'une panne de Canada Post ne ralentisse pas chaque actualisation du paiement. Le délai d'attente de l'API est de 10 secondes. Les colis de plus de 30 kg ne sont pas envoyés à l'API.

Si l'API ne renvoie aucun tarif, le prix fixe est utilisé, ou le transporteur est masqué lorsqu'il n'existe pas de prix fixe. Le client ne voit jamais les détails d'erreur de l'API ; ils vont dans le journal.

Si vous modifiez le transporteur dans Shipping > Carriers, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module calcule uniquement les tarifs. Il ne crée pas d'envois, n'imprime pas d'étiquettes, ne crée pas de bordereaux ni de retours, et ne suit pas les colis. Les clients ne peuvent pas choisir un bureau de poste ni un point relais. Il affiche un seul tarif Canada Post, sans dates de livraison, options d'assurance ou de signature. Le panier est toujours tarifé comme un seul colis, et les taux de change ne sont pas mis à jour automatiquement.

Commandes

Lorsqu'une commande est passée avec le transporteur Canada Post, le module enregistre la manière dont son prix a été calculé. Sur la page de commande du back-office (Orders > Orders, ouvrez une commande), un bloc Canada Post affiche :

Canada Post service : le nom et le code du service d'un tarif en temps réel, par exemple Regular Parcel (DOM.RP).

Price source : Live rate (Canada Post Rating API), Fixed price ou Free shipping.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Canada Post est le premier bloc de Modules > Module Manager > VibeFox Canada Post > 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-canada-post et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation de configuration du 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-le dans votre compte vibefox.net.

Sans clé active, le transporteur Canada Post n'est pas affiché aux clients au moment du paiement et aucun tarif n'est 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, 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 que vous travaillez 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Canada Post n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Canada Post 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. Il doit y avoir un tarif : avec des identifiants d'API, l'adresse doit comporter un code postal valide (Canada) ou un code ZIP (États-Unis) ; sinon, un prix fixe pour le pays ou pour * doit exister. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le panneau Log sur la page du module. Il indique la raison : nom d'utilisateur ou mot de passe de l'API manquant, code postal d'expédition ou de destination non valide, taux CAD manquant, colis de plus de 30 kg, ou le message d'erreur de Canada Post. Entre-temps, les clients obtiennent le prix fixe s'il en existe un.

Le tarif diffère du site de Canada Post : avec un numéro de client, vous obtenez les tarifs commerciaux (remisés) de votre compte ; sans numéro, les tarifs au guichet. Pour les adresses canadiennes, le prix de Canada Post inclut GST/HST/PST. Les prix sont convertis avec votre taux CAD.

La taxe est facturée deux fois sur la livraison : activez Use Canada Post prices without GST/HST/PST, ou réglez Tax sur No tax.

Tester les prix sur une boutique en production : désactivez Sandbox et utilisez la clé d'API de production.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs Canada Post.

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

Vous n'avez pas l'autorisation de configurer ce module : votre profil employé peut ouvrir la page du module mais pas l'enregistrer. Demandez à un administrateur de donner à votre profil l'autorisation de configuration du module.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Canada Post et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le transporteur est toujours retiré du paiement (les commandes conservent leur transporteur et leur historique). Si Remove data on uninstall est activé, les réglages, les services enregistrés des commandes, les tarifs en cache et le journal sont supprimés. S'il est désactivé, seuls les tarifs en cache sont retirés et tous les réglages sont conservés. Réinstaller le module (ou Reset) restaure le transporteur précédent avec son statut précédent : un transporteur que vous aviez désactivé reste désactivé.

Canada Post est une marque de son propriétaire respectif. Ce module n'est ni affilié à Canada Post ni approuvé par Canada Post.