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

Clé d'API PAC 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é d'API PAC sur le Developer Centre d'Australia Post (developers.auspost.com.au). La page du module renvoie vers la page d'inscription. Vous avez aussi besoin du 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é 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 Australia Post dans la liste des modules et cliquez sur Configure.

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

4. Choisissez la Rate source. Pour les tarifs en temps réel, saisissez la clé d'API PAC, votre 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). Cliquez sur Save.

À l'installation, le module crée le transporteur Australia Post avec le texte de délai de livraison Australia Post parcel delivery. Le transporteur est associé à 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, les limites de taille et la règle de taxe 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 Australia Post > Configure. Ils s'appliquent à toutes les zones. En haut de la page, vous voyez le nom et l'ID du transporteur dans Shipping > Carriers. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs Australia Post.

Si une source de tarifs en temps réel est choisie mais que la clé d'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 tant que le problème n'est pas corrigé : le transporteur est masqué au moment du paiement, ou les prix fixes par pays sont utilisés en mode de repli.

Les champs numériques acceptent un point ou une virgule comme séparateur décimal. Une valeur qui n'est pas un nombre ou qui est négative n'est pas enregistrée : un avertissement indique le champ, et la valeur précédente est conservée. La page avertit aussi si l'unité de poids ou de dimensions de la boutique (International > Localization) n'est pas reconnue par le module. Les poids des produits sont alors lus en kg et les dimensions en cm.

Général

Enable Australia Post : désactive le transporteur dans toutes les zones à la fois. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché au client au moment du paiement. C'est aussi le nom du transporteur dans Shipping > Carriers : renommer le transporteur à cet endroit met ce champ à jour. Par défaut : Australia Post. 64 caractères maximum : un titre plus long est refusé et rien n'est enregistré. Si le champ est vide ou contient des caractères que PrestaShop n'autorise pas dans un nom de transporteur, un avertissement s'affiche et Australia Post est utilisé.

Tax status : la manière dont la taxe est appliquée au coût de livraison.

Rate source : la manière dont le prix est calculé.

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

Australia Post API (live rates) (non nécessaire pour les prix fixes)

PAC API key : votre clé d'API PAC Australia Post gratuite. 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 et enregistrez pour supprimer la clé enregistrée. Les tarifs en temps réel cessent alors de fonctionner.

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 les prix nationaux de l'API par 1,1. Les prix nationaux d'Australia Post incluent 10% de GST. Activez cette option lorsque PrestaShop ajoute lui-même la taxe sur la livraison (Tax status = Taxable avec une règle de taxe sur le transporteur), afin que la GST ne soit pas facturée deux fois. Les frais d'affranchissement internationaux sont exonérés de GST 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 taux, les tarifs en temps réel ne sont pas utilisés. Si votre devise par défaut est l'AUD, la page indique qu'aucune conversion n'est nécessaire : laissez le champ vide. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Colis pour les tarifs en temps réel

Le panier est envoyé comme un seul colis. Les poids et dimensions des produits sont convertis des unités de votre boutique en kg et en 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 envoyée à 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 des produits ont des dimensions, le colis prend la plus grande longueur et 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 comme repli des tarifs en temps réel)

Country prices : un tableau de codes pays à 2 lettres (AU, NZ, US, etc.) et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add row pour ajouter un pays et sur le lien × pour en supprimer un. Utilisez * pour tous les autres pays. Un pays sans prix (et sans ligne *) n'a pas de tarif fixe, donc le transporteur est masqué pour lui. Les lignes au code pays invalide ou sans prix sont supprimées à l'enregistrement. Le tableau est vide tant que vous n'ajoutez pas de prix.

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 le colis entier.

Conditions

Min cart weight (kg) : masque le transporteur si le poids du panier est inférieur à cette valeur. 0 signifie aucune limite.

Max cart weight (kg) : masque le transporteur si le poids du panier est supérieur à cette valeur. 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 transporteur ne serait jamais affiché : un avertissement apparaît et les deux poids gardent leurs valeurs précédentes.

Minimum order amount : n'affiche le transporteur que lorsque le sous-total des produits (après remises, hors taxes) atteint ce montant, dans la devise par défaut de votre boutique. Laissez le champ vide pour l'afficher toujours.

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

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

Disponibilité sans zones de livraison

En général, le transporteur est proposé dans les zones qui lui sont attribuées dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est lié à toutes les zones, et les zones créées plus tard sont liées automatiquement. Désactiver l'option rend au transporteur les zones qu'il avait auparavant.

Countries : les pays de destination pour ce mode. Laissez le champ vide pour autoriser tous les pays actifs. Maintenez Ctrl (Cmd sur Mac) enfoncé et cliquez pour en sélectionner plusieurs. Utilisé uniquement avec Ignore shipping zones.

Avancé

Debug log : journalise les calculs de tarifs dans modules/vfd_australia_post/logs/vfd_ap.log.php. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours journalisées. La clé d'API et les codes postaux des clients ne sont pas journalisés. Désactivez le journal lorsque vous avez fini.

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

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages, le cache des tarifs et le journal. Le transporteur est toujours supprimé à la désinstallation. Une réinstallation le restaure si les données ont été conservées.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix Australia Post. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : la liste Countries (avec Ignore shipping zones), le poids du panier et le Minimum order amount. 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 tarifs en temps réel, le module 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 lorsque 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 GST est retirée des prix nationaux si Remove GST est activé. 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 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, afin 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 transporteur est masqué, ou le prix fixe est utilisé en mode de repli. 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 calcule uniquement des tarifs. Il ne crée pas d'étiquettes d'expédition, d'envois ou de manifestes eParcel ou MyPost Business, ne suit pas les colis et ne permet pas au client de choisir des casiers automatiques ou des bureaux de poste. Le panier est toujours tarifé comme un seul colis. Les lettres, les pochettes et les tarifs contractuels (eParcel) ne sont pas inclus.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Australia Post est le premier bloc de Modules > Module Manager > VibeFox Australia 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 de fin de validité de la licence et votre domaine) ainsi que 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-australia-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 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 : celui 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 Australia Post n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La vitrine 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 moment du 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é à nouveau automatiquement pendant votre travail 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

Australia Post n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Australia Post est activé (le transporteur est actif dans Shipping > Carriers). 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é dans Countries). Vérifiez les limites de poids du panier et le Minimum order amount. En mode prix fixes, vérifiez que le pays ou * a un prix. Les produits peuvent aussi être limités à certains transporteurs sur la page du produit.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Il indique la raison : pas de clé d'API ni de code postal d'expédition, pas encore de code postal de livraison à 4 chiffres, colis au-delà des 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 voient 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 dans votre devise par défaut.

La GST est facturée deux fois sur la livraison : les prix nationaux d'Australia Post incluent 10% de GST. Si Tax status est Taxable et que le transporteur a une règle de taxe, activez Remove GST ou réglez Tax status sur None.

La taxe n'est pas ajoutée à la livraison : avec Tax status = Taxable, la taxe provient de la règle de taxe du transporteur. Sélectionnez-la dans Shipping > Carriers. La page du module affiche un avertissement tant que le transporteur n'a pas de règle de taxe.

Le prix est trop élevé ou trop bas : vérifiez les poids et dimensions des produits ainsi que les valeurs par défaut de Colis pour les tarifs en temps réel. 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 du module. Cela vide le cache des tarifs Australia Post.

La page indique que le transporteur Australia Post a été supprimé : le transporteur a été supprimé dans Shipping > Carriers. Cliquez sur Save sur la page du module pour le recréer, ou réinitialisez le module dans Modules > Module Manager.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Australia Post et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le transporteur est toujours supprimé (les commandes conservent leur historique), et le cache des tarifs est vidé. Si Remove data on uninstall est activé, les réglages, la table du cache des tarifs et le journal sont également supprimés. Si l'option est désactivée, les réglages sont conservés, et réinstaller le module restaure le transporteur avec ses zones, ses groupes et son logo.

Australia Post est une marque déposée de son titulaire. Ce module n'est ni affilié à Australia Post ni approuvé par elle.