VibeFox Canada Post for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec 3.0.5.0) ou 4.0.2 et ultérieur (testé avec 4.1.0.3).

PHP : 8.0 ou ultérieur.

Canada Post Developer Program (pour les tarifs en direct uniquement) : les tarifs en direct utilisent la Canada Post Rating API. Inscrivez-vous au Canada Post Developer Program sur le site de Canada Post et copiez votre clé API et votre numéro client. La clé 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'où vous expédiez. Si vous n'utilisez que des prix 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 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_canada_post-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_canada_post.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_canada_post-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 copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Canada Post 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. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir License key).

5. Pour les tarifs en direct, saisissez le nom d'utilisateur et le mot de passe de l'API, votre numéro client et le code postal d'expédition. Si la devise par défaut de votre boutique n'est pas CAD, saisissez le taux en CAD. Remplissez Country prices si vous voulez des prix fixes ou un prix de secours (voir Configuration). Activez Enable Canada Post, puis cliquez sur Save.

OpenCart 4

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

3. Allez dans Extensions > Extensions et choisissez le type Shipping. Repérez VibeFox Canada Post, 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 de réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode de livraison reste désactivé tant que vous n'avez pas activé Enable Canada Post et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Canada Post > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des tarifs Canada Post. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Si une valeur est incorrecte, la page affiche une erreur et rien n'est enregistré : un champ numérique ou un prix de Country prices qui n'est pas un nombre égal ou supérieur à 0 (par exemple -1 ou 12abc), un taux CAD égal à 0, un Min cart weight (kg) supérieur à Max cart weight (kg), un Method title de plus de 64 caractères ou contenant les caractères < > ; = # { }, un Sort order qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue. Si la boutique n'a pas de classe de poids avec l'unité « kg » ni de classe de longueur avec l'unité « cm », la page avertit que les poids et dimensions sont convertis selon le nom d'unité de leur classe (kg, g, lb, oz ; cm, mm, m, in), et que les autres unités sont lues comme kg ou cm.

Après l'enregistrement, la page affiche un avertissement lorsque les réglages ne peuvent pas fonctionner comme prévu : un seul 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 API ni prix fixes. L'avertissement indique aussi ce qui se passe entre-temps : les prix fixes par pays sont utilisés, ou le mode de livraison est masqué au paiement lorsque le tableau Country prices est vide.

Général

Les réglages s'appliquent à toutes les zones géographiques. Le prix provient toujours de cette extension : un tarif en direct de Canada Post ou les prix fixes par pays.

Enable Canada Post: affiche ou masque Canada Post au paiement. Par défaut : désactivé.

Method title: le nom du mode de livraison affiché au client au paiement. Par défaut : Canada Post, également si le champ est laissé vide. 64 caractères au maximum.

Tax class: la classe de taxe qu'OpenCart ajoute au coût de livraison, ou No tax (non imposable).

Sort order: la position de Canada Post parmi les modes de livraison au paiement.

API de Canada Post (tarifs en direct)

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

API username: la partie de la clé API placée 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é API placée après les deux-points. Après l'enregistrement, le champ reste vide et affiche A password is saved. Leave empty to keep it; clear the API 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 client, Canada Post renvoie les tarifs commerciaux (remisés) de votre compte. Laissez-le vide pour les tarifs de guichet (au détail). Les espaces sont supprimés.

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

Sandbox: utilise l'environnement de développement de Canada Post, pour les tests avec la clé API de développement. Les prix sont des données de test. Désactivez-le sur une boutique réelle. Par défaut : désactivé.

Ship-from postal code: le code postal canadien d'où les colis sont expédiés, par exemple K1A 0B1. Les tarifs en direct en ont besoin.

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

Service to the USA: le moins cher disponible (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: le moins cher disponible (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 cette option lorsque OpenCart ajoute lui-même la taxe sur la livraison (Tax class ci-dessus), afin que la taxe ne soit pas appliqué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 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 cette valeur, les tarifs en direct 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.

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 à partir de leurs classes de poids et de longueur, et le panier est traité comme un seul colis (jusqu'à 30 kg).

Prix fixes (utilisés sans identifiants API, et en 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 égal à 0 utilise le prix Base. Cliquez sur Add country pour ajouter une ligne. La ligne * All other countries définit les prix de tous les pays sans ligne propre. 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 (par défaut) 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 direct sont toujours calculés pour le colis entier.

Conditions

Min cart weight (kg): masque le mode en dessous de ce poids de panier. 0 signifie sans limite (par défaut).

Max cart weight (kg): masque le mode au-dessus de ce poids de panier. Par défaut : 25, également si le champ est vide. 0 signifie sans limite. Les colis Canada Post peuvent peser jusqu'à 30 kg.

Minimum order amount: n'affiche le mode que lorsque le sous-total des produits nécessitant une livraison (après le coupon, hors taxes) atteint ce montant. Laissez le champ vide pour l'afficher toujours.

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

Free shipping from: le sous-total des produits nécessitant une livraison (après le coupon, hors taxes) à partir duquel la livraison est gratuite. Aucune requête API n'est alors envoyée. Utilisé seulement lorsque Free shipping est activé.

Geo zone: ne propose Canada Post qu'aux adresses de cette zone géographique. All zones (par défaut) signifie partout. Non utilisé lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Disponibilité sans zones de livraison

Normalement, le mode est proposé dans la zone géographique choisie dans Conditions.

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

Countries: les pays de destination pour ce mode. Laissez le champ vide pour autoriser tous les pays activés de la boutique. Utilisé seulement lorsque Ignore shipping zones est activé.

Avancé

Debug log: écrit les calculs de tarifs dans storage/logs/vfd_canada_post.log.php. Le fichier ne peut pas être lu depuis le web. Lorsqu'il atteint 5 Mo, il est déplacé vers vfd_canada_post.old.log.php et un nouveau journal est démarré. Les erreurs de l'API sont toujours journalisées, même si cette option est désactivée. Les clés API, les numéros clients et les codes postaux des clients ne sont pas journalisés.

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

Remove data on uninstall: lorsqu'elle est activée, la désinstallation de l'extension supprime les réglages, les services enregistrés des commandes, les tarifs en cache et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les commandes ne sont jamais modifiées.

Import / Export

Export: cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le mot de passe 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 API enregistré est conservé tant que le nom d'utilisateur API reste rempli.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Canada Post. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse est hors de cette zone, Canada Post n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent pas de poids et ne sont pas inclus dans le montant de la 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 la commande est le prix des produits nécessitant une livraison, après la réduction du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit de boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Canada Post.

Avec des identifiants API, l'extension 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 les autres pays, seulement le pays. Un tarif en direct n'est demandé que lorsqu'une adresse canadienne ou américaine a un code postal ou un code 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 Use Canada Post prices without GST/HST/PST est activé, et convertit le prix en CAD avec votre taux. Le prix est calculé dans votre devise par défaut, arrondi à 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 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 mode est masqué lorsqu'il n'y a pas de prix fixe. Le client ne voit jamais les détails d'erreur de l'API ; ils vont dans le journal.

L'extension ne calcule que 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 de bureau de poste ni de point de retrait. Elle affiche un seul tarif Canada Post, sans dates de livraison, options d'assurance ou de signature. Le panier est toujours traité comme un seul colis, et les taux de change ne sont pas mis à jour automatiquement.

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

Commandes

Lorsqu'une commande est passée avec Canada Post, l'extension enregistre la manière dont son prix a été calculé. Sur la page de commande de l'administration (Sales > Orders, ouvrez une commande), un bloc Canada Post affiche :

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

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

Sur OpenCart 4, le bloc s'affiche au-dessus de History. Le paiement conserve une seule commande : lorsque le client confirme de nouveau la commande, le service et la source de prix enregistrés sont remplacés, et ils sont supprimés si le client a choisi un autre mode de livraison.

Le service n'est pas ajouté aux e-mails de commande ni à la page de commandes du client ; ils affichent le nom du mode et le coût de livraison comme tout autre mode de livraison OpenCart.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Canada Post est le premier bloc de Extensions > Extensions > Shipping > VibeFox Canada Post > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous se trouvent la ligne Product: opencart-shipping-canada-post 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 cette 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 état connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration OpenCart. 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, Canada Post 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 le mode dans la boutique, marqué (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 le mode est masqué 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 concernées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. L'état est vérifié automatiquement à nouveau 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 l'état 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é. Vérifiez la Geo zone, ou que Ignore shipping zones est activé et que le pays est autorisé. Vérifiez les limites de poids et le Minimum order amount, et que les produits ont Requires Shipping réglé sur Yes. Il faut un tarif : avec des identifiants API, l'adresse doit avoir un code postal valide (Canada) ou un code ZIP (États-Unis) ; sinon, un prix fixe pour le pays ou pour * doit exister.

Les tarifs en direct n'apparaissent pas : activez Debug log, rechargez le paiement et regardez le champ Log sur la page de l'extension. Il indique la raison : nom d'utilisateur ou mot de passe 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. En attendant, les clients obtiennent le prix fixe s'il existe.

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

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

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

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela vide le cache des tarifs Canada Post.

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

Pour les développeurs : l'adresse de l'API Canada Post peut être remplacée par le réglage vfd_cp_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 Canada Post. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Canada Post, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages, les services enregistrés des commandes et le journal sont aussi supprimés. Sinon, les autres réglages sont conservés et réutilisés lors d'une réinstallation. Les commandes existantes conservent leur mode de livraison et leur coût.

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

Canada Post est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Canada Post ni approuvée par elle.