VibeFox Canada Post for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Canada Post Developer Program (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API Rating de Canada Post. Inscrivez-vous au Canada Post Developer Program sur le site de Canada Post, puis copiez votre clé d'API et votre numéro de client. La clé d'API a la forme identifiant:mot de passe, 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'où vous expédiez. 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_canada_post dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Canada Post, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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 de votre boutique n'est pas le CAD, saisissez le taux CAD. Remplissez Country prices si vous voulez des prix fixes ou un prix de secours (voir Configuration).

6. Ajoutez VibeFox Canada Post à vos zones de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez des pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Canada Post. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone): le nom affiché au client pour cette zone. Laissez-le vide pour utiliser le Method title global.

Chaque fois que vous enregistrez les réglages, les tarifs Canada Post en cache sont effacés. La page affiche aussi une erreur lorsque les réglages ne peuvent pas fonctionner : un seul des 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, le taux CAD manque pour une boutique dans une autre devise, ou il n'y a ni clés d'API ni prix fixes.

Général

Enable/Disable: active ou désactive la méthode dans toutes les zones à la fois.

Method title: le nom de la méthode de livraison affiché dans le panier et au paiement. Par défaut : Canada Post. Une zone peut utiliser son propre titre.

Tax status: Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas.

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 l'API Rating 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 la méthode est masquée s'il n'y en a pas.

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 réelle.

API password: la partie de la clé d'API après les deux-points. Elle n'est jamais écrite dans le journal.

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

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 réelle.

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 (par défaut), Expedited Parcel, Xpresspost ou Priority.

Service to the USA: Cheapest available (par défaut), Expedited Parcel USA, Tracked Packet USA, Small Packet USA Air, Xpresspost USA ou Priority Worldwide parcel USA.

International service: Cheapest available (par défaut), International Parcel Surface, International Parcel Air, Tracked Packet International, Small Packet International Surface, Small Packet International Air, Xpresspost International ou Priority Worldwide parcel International.

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

Canadian sales taxes: utilise les prix de Canada Post sans GST/HST/PST. Pour les adresses canadiennes, le prix de Canada Post inclut ces taxes. Activez cette option lorsque WooCommerce ajoute lui-même la taxe sur la livraison (Tax status = Taxable), pour ne pas facturer la taxe deux fois.

CAD → store currency rate: le nom du champ indique la devise de votre boutique. Les prix de Canada Post sont en CAD. Si la devise de votre boutique n'est pas le CAD, saisissez le nombre d'unités de votre devise pour un CAD, par exemple 0.68. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés. Si la devise de votre boutique est le CAD, laissez le champ vide. 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 et dimensions des produits sont convertis depuis les unités de votre boutique, et le panier est calculé comme un seul colis.

Prix fixes (utilisés sans identifiants d'API, et comme 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 de votre boutique : 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) fixe 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.

Fixed price per: Order facture le prix une seule fois. Item (price × 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 la méthode en dessous de ce poids de panier. 0 signifie sans limite.

Max cart weight (kg): masque la méthode au-dessus de ce poids de panier. Par défaut : 25. 0 signifie sans limite. Les colis Canada Post peuvent peser jusqu'à 30 kg.

Minimum order amount: affiche la méthode seulement lorsque le sous-total du panier atteint ce montant. Laissez vide pour l'afficher toujours.

Excluded shipping classes: masque la méthode si un article du panier appartient à l'une de ces classes de livraison WooCommerce.

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

Free shipping from: le sous-total du panier à partir duquel la livraison est gratuite. Dans ce cas, aucune requête n'est envoyée à l'API.

Disponibilité sans zones de livraison

Ignore shipping zones: propose la méthode pour les pays indiqués ci-dessous, quelle que soit la zone correspondante.

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

Avancé

Debug log: consigne les calculs de tarifs dans WooCommerce > Status > Logs, source vfd-canada-post. Les erreurs de l'API sont toujours consigné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 consignés.

Remove data on uninstall: lorsque l'option est activée, la suppression de l'extension efface ses réglages, les méthodes des zones et les tarifs en cache. La désactivation de l'extension ne supprime jamais rien.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, montant minimum de commande et classes de livraison exclues. Si la livraison gratuite s'applique, le client obtient un tarif gratuit et aucune requête n'est envoyée à Canada Post.

Avec des clés d'API, l'extension envoie à Canada Post le code postal d'expédition, la destination, le poids du colis et, lorsque tous les produits ont 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 les autres pays, seulement le pays. Un tarif en temps réel n'est demandé que lorsqu'une adresse canadienne ou américaine a un code postal ou ZIP valide. Canada Post renvoie tous les services pour le colis ; l'extension retient le service choisi pour le groupe de destination ou le moins cher, retire les taxes de vente canadiennes si Canadian sales taxes est activé, et convertit le prix en CAD avec votre taux. Le nom du service est enregistré avec la commande et affiché sur l'écran de commande de l'administration sous Canada Post service.

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, pour 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 la méthode est masquée s'il n'existe pas de prix fixe. Le client ne voit jamais les détails des erreurs de l'API ; ils sont consignés dans le journal WooCommerce.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

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

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Canada Post. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Canada Post n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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 en arrière-plan.

Dépannage

Canada Post n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids, Minimum order amount et Excluded shipping classes. Il faut un tarif : avec des clés d'API, l'adresse doit avoir un code postal valide (Canada) ou un code ZIP (États-Unis) ; sinon, un prix fixe doit exister pour le pays ou pour *.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd-canada-post. Le journal 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 reçoivent le prix fixe s'il existe.

Le tarif diffère du site web 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 Canadian sales taxes, ou réglez Tax status sur None.

Testez les prix sur une boutique réelle : désactivez Sandbox et utilisez la clé d'API de production.

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs Canada Post en cache.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes ne sont jamais touchées.

Canada Post est une marque de commerce de son titulaire respectif. Cette extension n'est ni affiliée à Canada Post ni approuvée par Canada Post.