VibeFox Australia 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.

Clé API PAC d'Australia Post (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent l'API Postage Assessment Calculator (PAC) d'Australia Post. La clé est gratuite : inscrivez-vous pour obtenir une clé API PAC sur le Australia Post Developer Centre (developers.auspost.com.au). La page des réglages renvoie vers la page d'inscription. Il vous faut aussi le code postal australien à 4 chiffres depuis lequel vous expédiez. Si vous n'utilisez que des prix fixes par pays, vous n'avez pas besoin de clé 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 pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_australia_post-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_australia_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_australia_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 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 Australia Post et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des réglages.

4. Saisissez 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. Choisissez la Rate source (source des tarifs). Pour des prix fixes, ajoutez des lignes dans Country prices. Pour des tarifs en temps réel, saisissez la clé API PAC, le code postal d'expédition et, si la devise par défaut de votre boutique n'est pas l'AUD, le taux de conversion en AUD (voir Configuration). Activez Enable Australia Post et cliquez sur Save.

OpenCart 4

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

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

Certaines erreurs bloquent l'enregistrement, et rien n'est alors enregistré : un Method title de plus de 64 caractères, un Sort order qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue. Les autres problèmes s'affichent sous forme d'avertissements au-dessus du panneau, et le reste des réglages est enregistré. Un champ numérique dont la valeur n'est pas un nombre ou est négative conserve sa valeur précédente, et l'avertissement indique le champ. Les champs numériques acceptent le point ou la virgule comme séparateur décimal.

Si une source de tarifs en temps réel est choisie mais que la clé API, un code postal d'expédition à 4 chiffres ou le taux de conversion en AUD manque, un avertissement s'affiche après l'enregistrement. Il indique aussi ce qui se passe jusqu'à la correction : le mode est masqué au moment du paiement, ou les prix fixes par pays sont utilisés en mode de secours. La page avertit également si votre boutique n'a pas de classe de poids avec l'unité kg ni de classe de longueur avec l'unité cm. Les poids et dimensions des produits sont alors convertis selon l'unité de leur classe (kg, g, lb, oz ; cm, mm, m, in), et les autres unités sont lues comme des kg et des cm.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode à une zone géographique dans Conditions, ou à une liste de pays dans Availability without shipping zones.

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

Method title: le nom du mode de livraison affiché au client dans le panier et au moment du paiement. Par défaut : Australia Post. 64 caractères au maximum : un titre plus long est refusé et rien n'est enregistré. Si le champ est vide, un avertissement s'affiche et Australia Post est utilisé.

Rate source: mode de calcul du prix.

Les détails des erreurs vont dans le journal, jamais au client.

Sort order: la position d'Australia Post parmi les modes de livraison au moment du paiement. Un nombre entier.

API Australia Post (tarifs en temps réel) (non nécessaire pour les prix fixes)

PAC API key: votre clé API PAC gratuite d'Australia Post. Elle est envoyée à Australia Post dans l'en-tête AUTH-KEY. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API key: activez puis enregistrez pour supprimer la clé enregistrée. Les tarifs en temps réel ne fonctionnent alors plus.

Ship-from postcode: le code postal australien à 4 chiffres depuis lequel les colis sont expédiés, par exemple 2000.

Domestic service: utilisé pour les livraisons en Australie (jusqu'à 22 kg, 105 cm par côté) : Parcel Post (par défaut) ou Express Post.

International service: utilisé pour les livraisons hors d'Australie (jusqu'à 20 kg) : International Standard (par défaut), International Express ou International Courier.

Remove GST: divise par 1,1 les prix nationaux de l'API. Les prix nationaux d'Australia Post incluent 10 % de TPS (GST). Activez cette option lorsque OpenCart ajoute lui-même une taxe à la livraison (une Tax class est sélectionnée), afin que la TPS ne soit pas facturée deux fois. Les frais d'expédition internationaux sont exonérés de TPS et ne sont jamais modifiés.

AUD → (your currency) rate: l'étiquette affiche la devise par défaut de votre boutique. Les prix d'Australia Post sont en AUD. Si votre devise par défaut n'est pas l'AUD, saisissez combien d'unités de votre devise vaut un AUD, par exemple 0,61. Le taux doit être supérieur à 0. Sans lui, les tarifs en temps réel ne sont pas utilisés. Si votre devise par défaut est l'AUD, le champ indique qu'aucune conversion n'est nécessaire : laissez-le vide.

Colis pour les tarifs en temps réel

Le panier est envoyé comme un seul colis. Les poids et dimensions des produits sont convertis depuis leurs classes de poids et de longueur d'OpenCart vers kg et cm. Les valeurs ci-dessous sont utilisées pour les produits sans poids ni dimensions.

Default product weight (kg): utilisé pour chaque produit sans poids, dans la requête à Australia Post et dans la vérification de Min cart weight (kg) / Max cart weight (kg). Par défaut : 1.

Default parcel length (cm): utilisé lorsqu'aucun produit du panier n'a de dimensions. Par défaut : 22.

Default parcel width (cm): utilisé lorsqu'aucun produit du panier n'a de dimensions. Par défaut : 16.

Default parcel height (cm): utilisé lorsqu'aucun produit du panier n'a de dimensions. Par défaut : 8.

Lorsque les produits ont des dimensions, le colis prend la plus grande longueur et la plus grande largeur parmi eux, et la hauteur augmente jusqu'à ce que le colis contienne le volume de tous les articles.

Prix fixes (utilisés avec les prix fixes et en secours pour les tarifs en temps réel)

Country prices: une liste de pays et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add row pour ajouter une ligne et sur le bouton × pour en retirer une. Choisissez * All other countries pour un prix appliqué à tout pays sans ligne propre. Un pays sans prix (et sans ligne *) n'a pas de tarif fixe : le mode est donc masqué pour lui. Les lignes sans prix sont supprimées à l'enregistrement. Le tableau est vide tant que vous n'ajoutez pas de prix.

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 concerne que les prix fixes. Les tarifs en temps réel 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 aucune limite (par défaut).

Max cart weight (kg): masque le mode au-dessus de ce poids de panier. Par défaut : 22. 0 signifie aucune limite, un champ vide signifie 22 kg. Colis Australia Post : 22 kg en national, 20 kg à l'international. Si Min cart weight (kg) est supérieur au maximum, le mode ne serait jamais affiché : un avertissement apparaît et les deux poids conservent leurs valeurs précédentes.

Minimum order amount: n'afficher le mode que si le sous-total des produits à expédier (après le coupon, hors taxes, dans votre devise par défaut) atteint ce montant. Laissez le champ vide pour l'afficher toujours.

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

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

Tax class: la classe de taxe du coût de livraison, ou No tax (par défaut). Les prix nationaux d'Australia Post incluent la TPS (GST) : avec une classe de taxe, activez Remove GST.

Geo zone: proposer Australia Post uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisé avec Ignore shipping zones.

Disponibilité sans zones de livraison

En règle générale, le mode est proposé dans la zone géographique choisie dans Conditions (All zones signifie partout).

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

Countries: les pays de destination pour ce mode. Tapez pour rechercher et sélectionnez-en plusieurs. Laissez le champ vide pour autoriser tous les pays activés de la boutique. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log: consigne les calculs de tarifs dans storage/logs/vfd_ap.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours consignées. La clé API et les codes postaux des clients ne sont pas journalisés. Désactivez le journal une fois terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_ap.old.log.php et un nouveau journal commence.

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 de l'extension supprime les réglages, les tarifs en cache et le journal. Désactivé (par défaut), ils sont conservés pour une réinstallation.

Importation / exportation

Exporter : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé API n'est pas exportée.

Importer : 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 enregistrée est conservée.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix Australia Post. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Australia Post n'est pas proposé. Avec Ignore shipping zones, c'est la liste Countries qui décide. Seuls les produits dont Requires Shipping est sur Yes comptent : les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite le poids du panier et le Minimum order amount. Le montant de la commande est le prix des produits à expédier, après 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 à Australia Post.

En mode prix fixes, le prix est pris dans le tableau. Dans les modes en temps réel, l'extension envoie à Australia Post le poids du colis et, pour les livraisons en Australie, les codes postaux d'expédition et de livraison ainsi que la taille du colis ; pour les livraisons internationales, le pays de destination. Un tarif national en temps réel n'est demandé que si l'adresse de livraison comporte un code postal à 4 chiffres. Aucune requête n'est envoyée si le colis dépasse les limites d'Australia Post (22 kg ou 105 cm en national, 20 kg à l'international). Le prix en AUD est converti avec votre taux, et la TPS (GST) est retirée des prix nationaux si Remove GST est activé. Le prix est calculé dans votre devise par défaut, arrondi à ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Chaque réponse réussie est mise en cache pendant 1 heure, afin que le même panier ne déclenche pas une nouvelle requête. Une requête échouée est mise en cache pendant 10 minutes, pour que le paiement n'attende pas Australia Post à chaque actualisation. Le délai d'attente de l'API est de 10 secondes. Les erreurs de l'API ne sont jamais affichées au client : le mode est masqué, ou le prix fixe est utilisé en mode de secours. La raison est écrite dans le journal.

L'extension calcule uniquement les tarifs. Elle ne crée pas d'étiquettes d'expédition, d'envois ou de bordereaux eParcel ou MyPost Business, ne suit pas les colis et ne permet pas aux clients de choisir des casiers automatiques ou des bureaux de poste. Elle n'ajoute rien aux commandes : la commande affiche le nom du mode et le coût de livraison comme pour tout autre mode de livraison OpenCart. Le panier est toujours tarifé comme un seul colis. Les lettres, les enveloppes et les tarifs contractuels (eParcel) ne sont pas inclus.

Sur OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement et choisit Australia Post dans la fenêtre Shipping method options. Le mode fonctionne comme sur OpenCart 3.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Australia Post est le premier bloc de Extensions > Extensions > Shipping > VibeFox Australia 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, le statut (par exemple la date de fin de validité de la licence 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: opencart-shipping-australia-post et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation de modification de l'extension peuvent changer 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 statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique indiquée dans la configuration d'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, Australia Post n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit encore le mode dans la boutique, marqué (unlicensed — visible to admins only), ce qui vous permet de configurer et de 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. Une fois la page Edit ouverte une fois, 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 la licence.

Dépannage

Australia Post n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Australia Post est activé. Contrôlez Geo zone (ou Ignore shipping zones et Countries), les limites de poids du panier et Minimum order amount. En mode prix fixes, vérifiez que le pays ou * All other countries a un prix. Vérifiez que les produits ont Requires Shipping sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Il indique la raison : clé API ou code postal d'expédition manquant, pas encore de code postal de livraison à 4 chiffres, colis hors limites, pas de taux de conversion en AUD, ou le message d'erreur d'Australia Post. Avec Live rates, fixed price if the API gives no rate, les clients obtiennent toujours le prix fixe pendant que vous corrigez le problème.

Ma boutique n'est pas en AUD : saisissez le taux de conversion (combien d'unités de votre devise par défaut vaut un AUD) dans le champ AUD → (your currency) rate. Les prix fixes sont toujours exprimés dans votre devise par défaut.

La TPS (GST) est facturée deux fois sur la livraison : les prix nationaux d'Australia Post incluent 10 % de TPS (GST). Si une Tax class est sélectionnée, activez Remove GST, ou réglez Tax class sur No tax.

Le prix est trop élevé ou trop bas : vérifiez les poids et dimensions des produits, leurs classes de poids et de longueur, ainsi que les valeurs par défaut de Parcel for live rates. Avec Item (price × quantity), les prix fixes sont multipliés par le nombre d'articles.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs Australia Post en cache.

La page affiche "Warning: You do not have permission to modify VibeFox Australia Post!" : votre groupe d'utilisateurs administrateurs ne peut peut-être que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_australia_post (OpenCart 3) ou extension/vfd_australia_post/shipping/vfd_australia_post (OpenCart 4) dans System > Users > User Groups.

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Australia Post. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Australia 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 Australia Post et le journal sont aussi supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle 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 Australia Post dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

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