VibeFox NZ Post for OpenCart — Aide

Prérequis

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

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 du 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, il vous faut aussi un compte professionnel NZ Post : le numéro de compte et son code d'autorisation (auth code) ou code de site (site code). Si vous utilisez uniquement 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

Le téléchargement est un fichier zip unique contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_nz_post-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_nz_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_nz_post-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas à 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 NZ 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 le champ License key du bloc de licence, en haut de la page Edit, puis cliquez sur Activate (voir Clé de licence).

5. Pour les tarifs en temps réel, remplissez la section NZ Post API (live rates). Vous pouvez éventuellement saisir des prix fixes, utilisés sans tarifs en temps réel et en secours (voir Configuration). Activez Enable NZ Post puis cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_nz_post.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 NZ 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, la méthode reste désactivée tant que vous n'avez pas activé Enable NZ Post et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages NZ Post que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox NZ Post > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les tarifs NZ Post et les jetons d'accès mis en cache. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Rien n'est enregistré et une erreur s'affiche lorsque Method title est vide, dépasse 64 caractères ou contient < > ; = # { }, lorsqu'un champ numérique contient du texte ou un nombre négatif, lorsque le taux NZD vaut 0, lorsque Min cart weight (kg) est supérieur à Max cart weight (kg), ou lorsque Sort order n'est pas un nombre entier. 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, Client ID ou Client Secret, aucun taux de conversion NZD, ou des données incomplètes pour les tarifs nationaux. Un avertissement apparaît aussi si la boutique ne dispose d'aucune classe de poids en kg ni d'aucune classe de longueur en cm : les poids et les dimensions sont alors convertis selon le nom d'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 la méthode à une zone géographique, ou à des pays, dans Availability.

Enable NZ Post : active ou désactive la méthode au moment du paiement. Par défaut : désactivé.

Method title : le nom de la méthode de livraison affiché au client dans le panier et lors du paiement. Par défaut : NZ Post. Obligatoire, 64 caractères maximum.

Tax class : la classe de taxe des frais de livraison, ou No tax (par défaut ; les frais de livraison ne sont pas taxés). Si la boutique ajoute la GST sur la livraison, réglez API prices ci-dessous sur Excluding GST pour éviter une double facturation de la GST.

Sort order : la position de NZ Post parmi les méthodes de livraison au moment du paiement. Un nombre entier.

API NZ Post (tarifs en temps réel) (laissez le Client ID vide pour n'utiliser que les 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. Le vider efface aussi le Client Secret enregistré.

Client Secret : le secret client 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 : votre numéro de compte professionnel (de facturation) NZ Post. Il est 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 le code d'autorisation enregistré.

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

Site code : l'alternative au code d'autorisation : votre code de site de collecte NZ Post.

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

Ship-from city : la ville ou l'agglomération 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 que NZ Post renvoie pour le colis.

API prices : Including GST (par défaut) ou Excluding GST. Les tarifs nationaux NZ Post incluent la GST de 15 % ; l'affranchissement international est exonéré. Choisissez Excluding GST lorsque la méthode a une classe de taxe (General), afin 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, saisissez combien d'unités de votre devise vaut un NZD, par exemple 0.55. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés. Ce même taux convertit la valeur de commande transmise avec les demandes internationales. Le taux doit être supérieur à 0. 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 les dimensions des produits sont convertis depuis leurs classes de poids et de longueur en kg et en cm (mm pour les demandes internationales). 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 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 le bouton × 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 aucun 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 fournissent de prix. Laissez vide pour masquer la méthode dans ce cas.

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 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 la méthode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).

Max cart weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 25 (les colis NZ Post vont jusqu'à 25 kg) ; un champ vide signifie aussi 25. 0 signifie aucune limite. Avec Ignore shipping zones activé, un champ vide signifie aucune limite pour les adresses hors de la Geo zone.

Minimum order amount : affiche la méthode uniquement lorsque le sous-total des produits nécessitant une expédition (après le coupon, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

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

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

Disponibilité

En général, la méthode est proposée dans la zone géographique sélectionnée ci-dessous, ou partout si aucune n'est sélectionnée.

Geo zone : proposez NZ Post uniquement pour les adresses situées dans cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : proposez aussi NZ Post en dehors de la zone géographique, pour les pays ci-dessous. Lorsque l'option est activée, seuls ces pays reçoivent la méthode, y compris à l'intérieur de la zone géographique. Par défaut : désactivé.

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

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_nzpt_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_nzpt_debug.log.php). Le fichier n'est pas accessible depuis le web. Les erreurs de l'API sont toujours journalisées, même lorsque le journal de débogage est désactivé. Les identifiants, les jetons, le numéro de compte et les adresses des clients ne sont pas journalisés. Désactivez le journal une fois vos vérifications terminées. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_nzpt_debug.old.log.php et un nouveau journal est démarré.

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 et le journal. Désactivée (par défaut), ils sont conservés pour une réinstallation. Les tarifs en cache sont toujours supprimés. Les données NZ Post des commandes sont toujours conservées.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le Client Secret et le code d'autorisation ne sont pas exportés.

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 Client Secret et le code d'autorisation enregistrés sont conservés tant que leur Client ID et leur numéro de compte restent renseignés.

Fonctionnement lors du paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le prix NZ Post. Si une Geo zone est définie et que l'adresse se trouve en dehors, NZ Post n'est proposé que lorsque Ignore shipping zones est activé et que le pays est autorisé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite les conditions : les pays autorisés (avec Ignore shipping zones), le poids du panier et le montant minimum de commande. Le montant de la commande correspond au prix des produits nécessitant une expédition, après la remise du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à NZ Post. Sinon, elle cherche un prix : d'abord le tarif NZ Post en temps réel, puis le tableau des pays, puis le coût de secours. S'il n'y a aucun prix, la méthode est masquée.

Lorsque les tarifs en temps réel sont configurés, l'extension 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, elle envoie les données de votre compte, l'adresse d'expédition, le quartier, la ville et le code postal du client, ainsi que le poids et les dimensions du colis. OpenCart n'a pas de champ quartier : l'extension utilise Address 2 lorsqu'il contient un nom de quartier (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, elle envoie le pays de destination, le poids et les dimensions du colis, ainsi que la valeur de la commande en NZD.

Le service autorisé le moins cher ayant un prix est utilisé, suppléments et options obligatoires compris. Le prix est converti du NZD vers la devise par défaut de la boutique, 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. Une requête é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. Le jeton d'accès est conservé jusqu'à son expiration, et un jeton refusé 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 aucun prix fixe, la méthode est masquée. La raison est écrite dans le journal.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit une option NZ Post dans la fenêtre Shipping method options. Les tarifs sont les mêmes que sur OpenCart 3.

L'extension calcule uniquement les tarifs. Elle ne crée pas d'étiquettes d'expédition, ne génère pas de manifestes, ne réserve pas d'enlèvements, ne suit pas les colis, ne valide pas les adresses et ne permet pas au client de choisir un point relais, une boîte postale (PO Box) ou un casier à colis. 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 NZ Post est passée, l'extension enregistre les éléments sur lesquels le prix de livraison était fondé. Ouvrez la commande dans Sales > Orders : la page de commande affiche un panneau NZ Post avec NZ Post service (le service NZ Post tarifé d'un tarif en temps réel, avec son code) et Price source : Live rate (NZ Post ShippingOptions API), Fixed price ou Free shipping. Le panneau affiche les valeurs du moment de la commande, même si les tarifs ou les réglages changent ensuite, et même lorsque la méthode est désactivée. Le client ne voit pas le nom du service.

Sur OpenCart 4, le panneau NZ Post s'affiche au-dessus de History. OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau : le service enregistré et la source du prix sont mis à jour avec elle. Si le client fait passer cette commande à un autre mode de livraison, les données NZ Post de la commande sont supprimées.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox NZ Post est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox NZ Post > Edit, au-dessus des réglages. Collez la clé dans License key puis 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: opencart-shipping-nz-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 l'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é une place 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 de la configuration OpenCart. 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, la méthode de livraison NZ Post n'est pas affichée aux clients lors du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (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 la méthode est masquée 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 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 licence.

Dépannage

NZ Post n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable NZ Post est activé. Contrôlez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et Minimum order amount. Si NZ Post ne renvoie aucun tarif, la méthode n'est affichée qu'avec un prix de pays ou un Fallback cost. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page de l'extension. Activez ensuite le Debug log, rechargez la page de 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 pour le 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, 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.

Ma boutique n'est pas en NZD : saisissez le taux NZD (le champ NZD → (votre devise) 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 tarifs nationaux NZ Post incluent la GST de 15 %. Si la méthode a une Tax class, réglez API prices sur Excluding GST.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page de l'extension. Cela efface les tarifs et les jetons NZ Post mis en cache.

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

Pour les développeurs : le quartier envoyé pour une adresse de livraison en Nouvelle-Zélande peut être modifié avec l'événement OpenCart vfd_nz_post/delivery_suburb (déclencheur catalog/vfd_nz_post/delivery_suburb). L'adresse de l'API NZ Post peut être remplacée par le réglage vfd_nzpt_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 NZ Post. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable NZ Post, Sort order, Tax class et Geo zone. Les tarifs et les jetons en cache sont toujours supprimés, et le panneau NZ Post n'est plus affiché sur la page de commande. Si Remove data on uninstall est activé, les réglages NZ Post et le journal de débogage sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les données NZ Post enregistrées des commandes ne sont jamais supprimées et réapparaissent après une réinstallation. Les commandes existantes conservent leur méthode 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 NZ Post dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

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