VibeFox NZ Post for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Accesso all'API di NZ Post (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API ShippingOptions di NZ Post. Richiedi l'accesso all'API nel Developer Resource Centre sul sito di NZ Post. NZ Post rilascia un Client ID e un Client Secret, prima per l'ambiente di test (UAT) e poi per la produzione, dopo la sua checklist di go-live. Per le tariffe all'interno della Nuova Zelanda ti serve anche un conto business NZ Post: il numero di conto e il suo auth code (o site code). Se usi solo prezzi fissi, non ti serve l'accesso all'API.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_nz_post in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox NZ Post, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Per le tariffe in tempo reale compila la sezione NZ Post API (live rates). Facoltativamente inserisci i prezzi fissi, che si usano senza tariffe in tempo reale e come alternativa (vedi Configurazione).

6. Aggiungi VibeFox NZ Post a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox NZ Post. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome che i clienti vedono per questa zona. Lascialo vuoto per usare il Method title generale.

Ogni volta che salvi le impostazioni, vengono cancellate le tariffe NZ Post e i token di accesso in cache. Se le tariffe in tempo reale non possono funzionare con i valori salvati (solo uno tra Client ID e Client Secret, nessun tasso di cambio NZD, dati incompleti per le tariffe nazionali), compare un avviso sopra le impostazioni.

General

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Una zona può sostituirlo. Predefinito: NZ Post.

Tax status: Taxable aggiunge l'imposta WooCommerce al costo di spedizione, None non la aggiunge. Vedi anche API prices più sotto.

NZ Post API (tariffe in tempo reale) (lascia vuoto il Client ID per usare solo i prezzi fissi)

Environment: Production (api.nzpost.co.nz) (predefinito) oppure Testing / UAT (api.uat.nzpost.co.nz). Usa l'ambiente per cui è stato emesso il tuo Client ID.

Client ID: l'ID client OAuth2 della tua applicazione API di NZ Post.

Client Secret: il client secret OAuth2. Viene scambiato con un token di accesso, che viene memorizzato fino alla scadenza.

Account number: il numero del tuo conto business (di fatturazione) NZ Post. È obbligatorio per le tariffe all'interno della Nuova Zelanda. Per le tariffe internazionali è facoltativo; con esso NZ Post restituisce le tue tariffe contrattuali.

Auth code: l'auth code del conto per le tariffe nazionali. Non serve se inserisci un site code.

Site code: l'alternativa all'auth code: il codice del tuo punto di ritiro NZ Post.

Ship-from suburb: il sobborgo dell'indirizzo da cui partono i pacchi, per esempio Petone. Serve per le tariffe nazionali.

Ship-from city: la località o la città da cui partono i pacchi, per esempio Lower Hutt. Serve per le tariffe nazionali.

Ship-from postcode: il CAP neozelandese a 4 cifre da cui partono i pacchi, per esempio 5012. Serve per le tariffe nazionali.

Services: codici di servizio NZ Post facoltativi, separati da virgole, per esempio CPOLP, ICOU. Vengono valutati solo questi servizi. Lascialo vuoto per usare il servizio più economico restituito da NZ Post per il pacco.

API prices: Including GST (predefinito) oppure Excluding GST. I prezzi nazionali di NZ Post includono il 15% di GST; la spedizione internazionale è ad aliquota zero. Scegli Excluding GST quando Tax status è Taxable, così la GST non viene addebitata due volte.

NZD → (store currency) rate: i prezzi di NZ Post sono in NZD. Se la valuta del tuo negozio non è NZD, indica quante unità della tua valuta vale un NZD, per esempio 0.55. Senza questo valore le tariffe in tempo reale non vengono usate. Lo stesso tasso converte l'importo dell'ordine inviato nelle richieste internazionali. Se la valuta del tuo negozio è NZD, lascialo vuoto.

Pacco per le tariffe in tempo reale

Il carrello viene inviato a NZ Post come un unico pacco. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del tuo negozio in kg e cm. Il pacco prende la lunghezza e la larghezza maggiori tra i prodotti, e la sua altezza cresce finché non contiene il volume di tutti gli articoli. I valori sotto vengono usati per i prodotti senza peso o dimensioni.

Default product weight (kg): usato per ogni prodotto senza peso. Predefinito: 0.5.

Default parcel length (cm): usato quando nessun prodotto nel carrello ha delle dimensioni. Predefinito: 30.

Default parcel width (cm): usato quando nessun prodotto nel carrello ha delle dimensioni. Predefinito: 20.

Default parcel height (cm): usato quando nessun prodotto nel carrello ha delle dimensioni. Predefinito: 10.

Prezzi fissi (usati quando le tariffe in tempo reale non sono configurate o NZ Post non restituisce una tariffa)

I prezzi sono nella valuta del negozio.

Country prices: una riga per paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverla. Scegli * Default per una riga che copre tutti gli altri paesi. Ogni riga ha un prezzo Any weight e colonne di peso facoltative: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg e > 5 kg (peso del carrello). Una colonna di peso compilata sostituisce Any weight; una colonna vuota o a 0 usa Any weight. Un prezzo Any weight di 0 significa spedizione gratuita verso quel paese. Sono accettati sia "9.99" sia "9,99". Le righe senza alcun prezzo, i codici paese non validi e i prezzi negativi vengono rimossi al salvataggio. Viene mantenuta una sola riga per paese.

Fallback cost: usato quando né l'API né la tabella dei paesi danno un prezzo. Lascialo vuoto per nascondere il metodo in questo caso.

Fixed price per: Order addebita il prezzo una volta. Item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Si applica solo ai prezzi fissi e al costo di riserva. Le tariffe in tempo reale sono sempre calcolate per l'intero pacco.

Condizioni

Min cart weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite.

Max cart weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 25 (i pacchi corrieri NZ Post arrivano fino a 25 kg). 0 significa nessun limite.

Minimum order amount: mostra il metodo solo quando il subtotale del carrello raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una qualsiasi di queste classi di spedizione WooCommerce.

Free shipping from: il subtotale del carrello da cui la spedizione con NZ Post è gratuita. Vale solo quando il metodo ha un prezzo: un prezzo per paese o il costo di riserva (in tal caso non viene inviata alcuna richiesta a NZ Post), oppure una tariffa in tempo reale. Lascialo vuoto per non offrire mai la spedizione gratuita.

Per queste condizioni il peso del carrello conta i prodotti senza peso come 0.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre NZ Post per i paesi indicati qui sotto, anche se il metodo non è aggiunto a nessuna zona di spedizione.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Questo campo si usa solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in WooCommerce > Status > Logs (origine "vfd-nz-post"). Gli errori dell'API vengono sempre registrati, anche con il log di debug disattivato. Credenziali, token e indirizzi dei clienti non vengono registrati. Disattiva il log quando hai finito.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni, i metodi delle zone e le tariffe in cache. Disattivare il plugin non cancella mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Poi cerca un prezzo: la tariffa NZ Post in tempo reale, quindi la tabella dei paesi e infine il costo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi.

Con le tariffe in tempo reale configurate, il plugin ottiene un token di accesso con il tuo Client ID e il tuo Client Secret e chiede a NZ Post un prezzo. Per un indirizzo in Nuova Zelanda invia i dati del tuo conto, l'indirizzo di partenza, il sobborgo, la città e il CAP del cliente, oltre al peso e alle dimensioni del pacco. WooCommerce non ha un campo per il sobborgo: il plugin usa Address line 2 quando contiene il nome di un sobborgo, altrimenti la località o la città. Una tariffa nazionale viene richiesta solo dopo che il cliente ha inserito una città e un CAP a 4 cifre. Per gli altri paesi invia il paese di destinazione, il peso e le dimensioni del pacco e l'importo dell'ordine in NZD.

Viene usato il servizio consentito più economico con un prezzo, inclusi supplementi e costi aggiuntivi obbligatori. Il prezzo viene convertito da NZD nella valuta del tuo negozio. Il servizio con prezzo viene salvato con l'ordine come NZ Post service ed è visibile nella schermata dell'ordine. Ogni risposta viene memorizzata per 1 ora. Una richiesta non riuscita viene memorizzata per 10 minuti, così il checkout non attende NZ Post a ogni aggiornamento. Il timeout dell'API è di 10 secondi. Un token di accesso scaduto viene rinnovato automaticamente.

Se NZ Post non restituisce una tariffa (API non configurata, errore, indirizzo incompleto, servizio non disponibile, nessun tasso NZD), il cliente non vede alcun errore. Si usa il prezzo della tabella dei paesi, poi il costo di riserva. Se non c'è un prezzo fisso, il metodo viene nascosto. Il motivo viene scritto nel log.

Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin calcola solo le tariffe. Non crea etichette di spedizione, non prenota ritiri, non genera distinte, non traccia i pacchi, non convalida indirizzi e non permette ai clienti di scegliere un punto di ritiro, una casella postale (PO Box) o un armadietto per pacchi (parcel locker). Il carrello viene valutato come un unico pacco e il cliente vede un'unica tariffa NZ Post, non un elenco di servizi.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox NZ Post. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per ricontrollare lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, NZ Post non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

NZ Post non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Controlla i limiti di peso, Minimum order amount ed Excluded shipping classes. Se NZ Post non restituisce una tariffa, il metodo viene mostrato solo con un prezzo per paese o con un Fallback cost.

Le tariffe in tempo reale non compaiono: apri WooCommerce > Status > Logs, origine "vfd-nz-post". Gli errori dell'API sono sempre lì. Attiva Debug log per i dettagli. Il log mostra il motivo: Client ID o Client Secret mancanti, token rifiutato, dati del conto o dell'indirizzo di partenza mancanti, città o CAP del cliente non ancora disponibili, nessun tasso NZD o nessun servizio con prezzo. Nel frattempo si usano i prezzi fissi.

La richiesta del token non riesce: controlla il Client ID, il Client Secret e l'Environment. Le credenziali UAT non funzionano in produzione, e viceversa.

Mancano le tariffe nazionali, quelle internazionali funzionano: le tariffe all'interno della Nuova Zelanda richiedono il Account number, l'Auth code o il Site code, e l'indirizzo di partenza completo con un CAP a 4 cifre. Il cliente deve inserire una città e un CAP a 4 cifre. Gli sviluppatori possono cambiare il sobborgo inviato per l'indirizzo di consegna con il filtro vfd_nzpt_delivery_suburb.

Il mio negozio non è in NZD: inserisci il NZD → (store currency) rate. I prezzi fissi sono sempre nella valuta del negozio.

La GST viene addebitata due volte sulla spedizione: i prezzi nazionali di NZ Post includono il 15% di GST. Se Tax status è Taxable, imposta API prices su Excluding GST.

Dopo una modifica le tariffe sembrano obsolete: salva la pagina delle impostazioni. Così vengono cancellate le tariffe NZ Post e i token in cache.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona, tariffe in cache e token di accesso vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione futura. Gli ordini esistenti conservano le loro righe di spedizione.

NZ Post è un marchio del suo rispettivo proprietario. Questo plugin non è affiliato né approvato da NZ Post.