VibeFox NZ 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 versions de PHP antérieures.

Accès à l'API NZ Post (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent l'API ShippingOptions de NZ Post. Demandez l'accès à l'API dans le Developer Resource Centre de NZ Post, sur le site de NZ Post. NZ Post vous fournit un Client ID et un Client Secret, d'abord pour l'environnement de test (UAT), puis pour la production après sa liste de contrôle de mise en service. Pour les tarifs en Nouvelle-Zélande, vous avez aussi besoin d'un compte professionnel NZ Post : le numéro de compte et son auth code ou son site code. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin d'accès à l'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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox NZ 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, remplissez la section NZ Post API (live rates). Vous pouvez aussi saisir des prix fixes, utilisés sans tarifs en temps réel et en secours (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur NZ Post avec le texte de délai de livraison NZ 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 livraison, le logo et les limites de taille dans Shipping > Carriers. N'y définissez pas de prix : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox NZ Post > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement efface aussi les tarifs NZ Post en cache et les jetons d'accès.

Des avertissements apparaissent au-dessus des réglages lorsque les tarifs en temps réel ne peuvent pas fonctionner avec les valeurs enregistrées : seulement l'un des deux champs Client ID et Client Secret, pas de taux de conversion NZD, ou des données incomplètes pour les tarifs nationaux. Un avertissement apparaît aussi si l'unité de poids ou de dimension de la boutique n'est pas reconnue par le module (les poids sont alors pris en kg et les dimensions en cm). Réglez les unités dans International > Localization (Local units). Les champs numériques doivent contenir 0 ou un nombre positif ; sinon, la page affiche une erreur et rien n'est enregistré.

General

Enable NZ 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é dans le panier et au moment du paiement. Par défaut : NZ Post. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax (le coût de livraison n'est pas taxé). Si la boutique ajoute la GST sur la livraison, réglez API prices plus bas sur Excluding GST pour que la GST ne soit pas facturée deux fois.

NZ Post API (live rates) (laissez le Client ID vide pour n'utiliser que des prix fixes)

Environment : Production (api.nzpost.co.nz) (par défaut) ou Testing / UAT (api.uat.nzpost.co.nz). Utilisez l'environnement pour lequel votre Client ID a été délivré.

Client ID : le client ID OAuth2 de votre application API NZ Post. Le vider efface aussi le Client Secret enregistré.

Client Secret : le client secret OAuth2. Il est échangé contre un jeton d'accès, mis en cache jusqu'à son expiration. 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.

Account number : le numéro de votre compte professionnel (de facturation) NZ Post. Obligatoire pour les tarifs en Nouvelle-Zélande. Pour les tarifs internationaux, il est facultatif ; avec lui, NZ Post renvoie vos tarifs contractuels. Le vider efface aussi l'auth code enregistré.

Auth code : le code d'autorisation du compte pour les tarifs nationaux. Il n'est pas nécessaire si vous saisissez un site code. Comme le Client Secret, il n'est plus affiché après l'enregistrement.

Site code : l'alternative à l'auth code : votre code de site de collecte NZ Post.

Ship-from suburb : la banlieue (suburb) de l'adresse d'où partent les colis, par exemple Petone. Nécessaire pour les tarifs nationaux.

Ship-from city : la ville ou la localité d'où partent les colis, par exemple Lower Hutt. Nécessaire pour les tarifs nationaux.

Ship-from postcode : le code postal néo-zélandais à 4 chiffres d'où partent les colis, par exemple 5012. Nécessaire pour les tarifs nationaux.

Services : codes de service NZ Post facultatifs, séparés par des virgules, par exemple CPOLP, ICOU. Seuls ces services sont tarifés. Laissez vide pour utiliser le service le moins cher renvoyé par NZ Post pour le colis.

API prices : Including GST (par défaut) ou Excluding GST. Les prix nationaux de NZ Post incluent la GST à 15 % ; l'affranchissement international est à taux zéro. Choisissez Excluding GST lorsque le transporteur a une règle de taxe (Tax ci-dessus), pour que la GST ne soit pas facturée deux fois.

Taux NZD → (devise de la boutique) : les prix NZ Post sont en NZD. Si la devise par défaut de votre boutique n'est pas le NZD, indiquez combien d'unités de votre devise vaut un NZD, par exemple 0.55. Sans ce taux, les tarifs en temps réel ne sont pas utilisés. Le même taux convertit le montant de commande envoyé avec les demandes internationales. Le taux doit être supérieur à 0. Si la devise de votre boutique est le NZD, laissez ce champ vide.

Parcel for live rates

Le panier est envoyé à NZ Post sous la forme d'un seul colis. Les poids et dimensions des produits sont convertis des unités de votre boutique en kg et cm. Le colis prend la plus grande longueur et la plus grande largeur des produits, et sa hauteur augmente jusqu'à contenir le volume de tous les articles. Les valeurs ci-dessous sont utilisées pour les produits sans poids ni dimensions.

Default product weight (kg) : utilisé pour chaque produit sans poids. Par défaut : 0.5.

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

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

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

Fixed prices (utilisés lorsque les tarifs en temps réel ne sont pas configurés ou que NZ Post ne renvoie aucun tarif)

Les prix sont exprimés dans la devise par défaut de la boutique, hors taxes.

Country prices : une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Choisissez * Default pour une ligne qui couvre tous les autres pays. Chaque ligne comporte un prix Any weight et des colonnes de poids facultatives : ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg et > 5 kg (poids du panier). Une colonne de poids renseignée remplace Any weight ; une colonne vide ou à 0 utilise Any weight. Un prix Any weight de 0 signifie livraison gratuite vers ce pays. « 9.99 » et « 9,99 » sont tous deux acceptés. Les lignes sans prix et les prix négatifs sont supprimés à l'enregistrement. Une seule ligne par pays est conservée.

Fallback cost : utilisé lorsque ni l'API ni le tableau des pays ne fournit de prix. Laissez-le vide pour masquer le transporteur dans ce cas.

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 et au coût de secours. Les tarifs en temps réel sont toujours calculés pour le colis entier.

Conditions

Min cart weight (kg) : masque le transporteur lorsque le panier pèse moins. 0 signifie aucune limite.

Max cart weight (kg) : masque le transporteur lorsque le panier pèse plus. Par défaut : 25 (les colis courrier de NZ Post vont jusqu'à 25 kg) ; un champ vide signifie aussi 25. 0 signifie aucune limite. Lorsque Ignore shipping zones est activé, un champ vide signifie aucune limite en dehors des zones propres au transporteur. Si Min cart weight est supérieur à Max cart weight, la page affiche une erreur et rien n'est enregistré, car le transporteur ne serait jamais affiché.

Minimum order amount : n'affiche le transporteur que lorsque le sous-total du panier (produits nécessitant une livraison, après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison NZ Post est gratuite. Aucune demande n'est alors envoyée à NZ Post. Laissez vide pour ne jamais proposer la livraison gratuite.

Pour ces conditions, le poids du panier compte les produits sans poids comme 0.

Availability without shipping zones

En règle générale, le transporteur est affiché dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose NZ Post pour les pays indiqués ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones (y compris celles créées plus tard). Désactiver l'option supprime à nouveau les zones ajoutées.

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

Advanced

Debug log : écrit les calculs de tarifs dans logs/vfd_nzpt_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours enregistrées, même lorsque le journal de débogage est désactivé. Les identifiants, les jetons et les adresses des clients ne sont pas enregistrés. Désactivez le journal lorsque vous avez terminé.

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 du module supprime les réglages, le transporteur, les tarifs en cache, les détails de commande enregistrés et les journaux. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix NZ 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 : pays autorisés (avec Ignore shipping zones), poids du panier et montant minimum de commande. Si la livraison gratuite s'applique, le prix est 0 et aucune demande n'est envoyée à NZ Post. Sinon, il recherche un prix : d'abord le tarif NZ Post en temps réel, puis le tableau des pays, et enfin le coût de secours. S'il n'existe aucun prix, le transporteur est masqué.

Lorsque les tarifs en temps réel sont configurés, le module obtient un jeton d'accès avec votre Client ID et votre Client Secret, puis demande un prix à NZ Post. Pour une adresse en Nouvelle-Zélande, il envoie les données de votre compte, l'adresse d'expédition, la banlieue, la ville et le code postal du client, ainsi que le poids et la taille du colis. PrestaShop n'a pas de champ pour la banlieue : le module utilise Address line 2 lorsqu'il contient un nom de banlieue (sans chiffres), sinon la ville. Un tarif national n'est demandé qu'après que le client a saisi une ville et un code postal à 4 chiffres. Pour les autres pays, il envoie le pays de destination, le poids et la taille du colis, ainsi que le montant de la commande en NZD.

Le service autorisé le moins cher ayant un prix est utilisé, surcharges et suppléments obligatoires inclus. Le prix est converti du NZD vers 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. Une demande échouée est mise en cache pendant 10 minutes, afin que le paiement n'attende pas NZ Post à chaque actualisation. Le délai d'attente de l'API est de 10 secondes. Un jeton d'accès expiré est renouvelé automatiquement.

Si NZ Post ne renvoie aucun tarif (API non configurée, erreur, adresse incomplète, service indisponible, pas de taux NZD), le client ne voit aucune erreur. Le prix du tableau des pays est utilisé, puis le coût de secours. S'il n'existe pas de prix fixe, le transporteur est masqué. 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 les tarifs. Il ne crée pas d'étiquettes d'expédition, ne réserve pas d'enlèvements, ne génère pas de manifestes, ne suit pas les colis, ne valide pas les adresses et ne permet pas aux clients de choisir un point de retrait, une boîte postale (PO Box) ou un casier à colis (parcel locker). Le panier est tarifé comme un seul colis, et le client voit un seul tarif NZ Post, et non une liste de services.

Commandes

Lorsqu'une commande avec le transporteur NZ Post est passée, le module enregistre les éléments sur lesquels le prix de livraison était fondé. La page de commande du back-office affiche un bloc NZ Post avec NZ Post service (le service NZ Post tarifé d'un tarif en temps réel) et Price source : Live rate (NZ Post ShippingOptions API), Fixed price ou Free shipping. Le bloc affiche les valeurs au moment de la commande, même si les tarifs ou les réglages changent ensuite.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox NZ Post est le premier bloc de Modules > Module Manager > VibeFox NZ 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) 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-nz-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 : 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur NZ 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, dans 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 l'assistance 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 suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

NZ Post n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable NZ 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 le Minimum order amount. Si NZ Post ne renvoie aucun tarif, le transporteur n'est affiché qu'avec un prix par pays ou un Fallback cost. Des produits peuvent aussi être limités à certains transporteurs sur la page produit.

Les tarifs en temps réel n'apparaissent pas : regardez les avertissements en haut de la page du module. Activez ensuite le Debug log, rechargez le paiement et consultez le champ Log. Les erreurs de l'API y figurent toujours. Le journal indique la raison : Client ID ou Client Secret manquant, jeton refusé, données de compte ou d'expédition manquantes, pas encore de ville ou de code postal du client, pas de taux NZD, ou aucun service tarifé. Les prix fixes sont utilisés pendant que vous corrigez le problème.

La demande de jeton échoue : vérifiez le Client ID, le Client Secret et l'Environment. Les identifiants UAT ne fonctionnent pas en production, et inversement.

Les tarifs nationaux manquent, les tarifs internationaux fonctionnent : les tarifs en Nouvelle-Zélande nécessitent l'Account number, l'Auth code ou le Site code, et l'adresse d'expédition complète avec un code postal à 4 chiffres. Le client doit saisir une ville et un code postal à 4 chiffres. Les développeurs peuvent modifier la banlieue transmise pour l'adresse de livraison avec le hook actionVfdNzptDeliverySuburb.

Ma boutique n'est pas en NZD : saisissez le NZD → (shop currency) rate. Les prix fixes sont toujours exprimés dans la devise par défaut de la boutique.

La GST est facturée deux fois sur la livraison : les prix nationaux NZ Post incluent la GST à 15 %. Si le transporteur a une règle de taxe dans Tax, réglez API prices sur Excluding GST.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs NZ Post et les jetons en cache.

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox NZ Post et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs et jetons en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages, les détails de commande enregistrés et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module, ou effectuer un Reset, rend au transporteur enregistré le statut qu'il avait auparavant (activé ou désactivé).

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