VibeFox NZ Post for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

WooCommerce: 5.0 ou ultérieur, installé et activé. Le plugin ne s'active pas sans lui.

PHP: 8.0 ou ultérieur.

Accès à l'API NZ Post (pour les tarifs en temps réel uniquement): les tarifs en temps réel utilisent l'API ShippingOptions de NZ Post. Demandez l'accès à l'API dans le Developer Resource Centre, sur le site de NZ Post. NZ Post 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 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_nz_post dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox NZ Post, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.

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

5. 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).

6. Ajoutez VibeFox NZ Post à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox NZ 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 que voient les clients pour cette zone. Laissez-le vide pour utiliser le Method title général.

Chaque fois que vous enregistrez les réglages, les tarifs NZ Post et les jetons d'accès en cache sont supprimés. Si les tarifs en temps réel ne peuvent pas fonctionner avec les valeurs enregistrées (un seul des deux, Client ID ou Client Secret, pas de taux de conversion NZD, données incomplètes pour les tarifs nationaux), un avertissement s'affiche au-dessus des réglages.

General

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 moment du paiement. Une zone peut le remplacer. Par défaut : NZ Post.

Tax status: Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas. Voir aussi API prices ci-dessous.

NZ Post API (tarifs en temps réel) (laissez le Client ID vide pour utiliser uniquement 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: l'identifiant client OAuth2 de votre application API NZ Post.

Client Secret: le secret client OAuth2. Il est échangé contre un jeton d'accès, qui est mis en cache jusqu'à son expiration.

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.

Auth code: le code d'autorisation du compte pour les tarifs nationaux. Non nécessaire si vous saisissez un site code.

Site code: l'alternative au auth code : le code de votre point d'enlèvement NZ Post.

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

Ship-from city: la ville 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 NZ Post incluent la GST de 15% ; l'affranchissement international est à taux zéro. Choisissez Excluding GST lorsque Tax status est Taxable, afin que la GST ne soit pas facturée deux fois.

NZD → (store currency) rate: les prix NZ Post sont en NZD. Si la devise 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 la commande envoyé avec les demandes internationales. Si la devise de votre boutique est le NZD, laissez ce champ vide.

Colis pour les tarifs en temps réel

Le panier est envoyé à NZ Post sous 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.

Prix fixes (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 de la boutique.

Country prices: une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * Default pour une ligne qui couvre tous les autres pays. Chaque ligne a 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. Les formats "9.99" et "9,99" sont acceptés. Les lignes sans aucun prix, les codes pays invalides 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 la méthode 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 concerne que les prix fixes et le coût de secours. Les tarifs en temps réel sont toujours calculés pour l'ensemble du colis.

Conditions

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

Max cart weight (kg): masque la méthode lorsque le panier pèse plus. Par défaut : 25 (les colis NZ Post pèsent jusqu'à 25 kg). 0 signifie aucune limite.

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

Excluded shipping classes: masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Free shipping from: le sous-total du panier à partir duquel la livraison NZ Post est gratuite. Cela ne s'applique que lorsque la méthode a un prix : un prix par pays ou le coût de secours (aucune demande n'est alors envoyée à NZ Post), ou un tarif en temps réel. Laissez vide pour ne jamais proposer de livraison gratuite.

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

Disponibilité sans zones de livraison

Ignore shipping zones: propose NZ Post pour les pays indiqués ci-dessous, même si la méthode n'est ajoutée à aucune zone de livraison.

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

Avancé

Debug log: écrit les calculs de tarifs dans WooCommerce > Status > Logs (source «vfd-nz-post»). Les erreurs de l'API sont toujours journalisées, même lorsque le journal de débogage est désactivé. Les identifiants, jetons et adresses des clients ne sont pas journalisés. Désactivez le journal lorsque vous avez terminé.

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

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif au plugin. Le plugin vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimum de commande et classes d'expédition exclues. Il recherche ensuite un prix : le tarif NZ Post en temps réel, puis le tableau des pays, et enfin le coût de secours. Si aucun prix n'est trouvé, la méthode est masquée. Si la livraison gratuite s'applique, le client voit la méthode sans frais.

Lorsque les tarifs en temps réel sont configurés, le plugin 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. WooCommerce ne dispose pas de champ pour la banlieue : le plugin utilise Address line 2 lorsqu'il contient un nom de banlieue, sinon la ville. Un tarif national n'est demandé qu'une fois 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 le moins cher autorisé qui a un prix est utilisé, y compris les surcharges et les suppléments obligatoires. Le prix est converti du NZD vers la devise de votre boutique. Le service tarifé est enregistré avec la commande sous le nom NZ Post service et apparaît sur l'écran de commande. 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, la méthode est masquée. La raison est écrite dans le journal.

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

Le plugin 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 bordereaux, 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.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox NZ 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, ainsi que 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 l'emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, NZ Post n'est pas affiché aux clients au moment du paiement. Les gestionnaires de la boutique connectés le voient toujours, avec la mention (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin 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, le plugin 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

NZ Post n'apparaît pas au moment du 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é). Contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. Si NZ Post ne renvoie aucun tarif, la méthode n'est affichée qu'avec un prix par pays ou un Fallback cost.

Les tarifs en temps réel n'apparaissent pas: ouvrez WooCommerce > Status > Logs, source «vfd-nz-post». Les erreurs de l'API y figurent toujours. Activez Debug log pour plus de détails. Le journal indique la raison : Client ID ou Client Secret manquant, jeton refusé, données de compte ou d'expédition manquantes, ville ou code postal du client pas encore connu, 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, ainsi que 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 filtre vfd_nzpt_delivery_suburb.

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

La GST est facturée deux fois sur la livraison: les prix nationaux NZ Post incluent la GST de 15%. Si Tax status est Taxable, réglez API prices sur Excluding GST.

Les tarifs semblent obsolètes après une modification: enregistrez la page des réglages. Cela supprime les tarifs NZ Post et les jetons 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, puis 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, le plugin continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation du plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages, les méthodes de zone, les tarifs en cache et les jetons d'accès ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs lignes de livraison.

NZ Post est une marque déposée de son propriétaire. Ce plugin n'est ni affilié à NZ Post ni approuvé par NZ Post.