VibeFox NZ Post for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

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. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox NZ Post nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).

4. Per le tariffe in tempo reale, compila la sezione NZ Post API (live rates). Facoltativamente, inserisci i prezzi fissi, che vengono usati senza tariffe in tempo reale e come alternativa (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere NZ Post con il testo dei tempi di consegna NZ Post parcel delivery. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox NZ Post > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe NZ Post memorizzate e i token di accesso.

Sopra le impostazioni compaiono avvisi quando le tariffe in tempo reale non possono funzionare con i valori salvati: solo uno tra Client ID e Client Secret, nessun tasso di conversione NZD o dati incompleti per le tariffe nazionali. Compare un avviso anche se l'unità di peso o di dimensione del negozio non è riconosciuta dal modulo (i pesi vengono allora considerati in kg e le dimensioni in cm). Imposta le unità in International > Localization (Local units). I campi numerici devono contenere 0 o un numero positivo; altrimenti la pagina mostra un errore e non salva nulla.

General

Enable NZ Post: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: NZ Post. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax (il costo di spedizione non è tassato). Se il negozio aggiunge la GST alla spedizione, imposta più sotto API prices su Excluding GST così la GST non viene addebitata due volte.

NZ Post API (live rates) (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: il client ID OAuth2 della tua applicazione API di NZ Post. Svuotarlo cancella anche il Client Secret salvato.

Client Secret: il client secret OAuth2. Viene scambiato con un token di accesso, memorizzato fino alla scadenza. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

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 il numero, NZ Post restituisce le tue tariffe contrattuali. Svuotarlo cancella anche l'auth code salvato.

Auth code: il codice di autorizzazione del conto per le tariffe nazionali. Non serve se inserisci un site code. Come il Client Secret, dopo il salvataggio non viene più mostrato.

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

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

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

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

Services: codici di servizio NZ Post facoltativi, separati da virgole, per esempio CPOLP, ICOU. Vengono prezzati solo questi servizi. Lascia 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 il corriere ha una regola fiscale (Tax sopra), così la GST non viene addebitata due volte.

NZD → (shop currency) rate: i prezzi di NZ Post sono in NZD. Se la valuta predefinita 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. Il tasso deve essere maggiore di 0. Se la valuta del tuo negozio è NZD, lascia il campo vuoto.

Parcel for live rates

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 fino a contenere il volume di tutti gli articoli. I valori seguenti 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 dimensioni. Predefinito: 30.

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

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

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

I prezzi sono nella valuta predefinita del negozio, IVA esclusa.

Country prices: una riga per paese di destinazione. Fai clic su Add country per aggiungere una riga e sull'icona del cestino 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 con 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 prezzo e i prezzi negativi vengono rimossi al salvataggio. Per ogni paese si conserva una sola riga.

Fallback cost: usato quando né l'API né la tabella dei paesi forniscono un prezzo. Lascia vuoto per nascondere il corriere in quel caso.

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

Conditions

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

Max cart weight (kg): nasconde il corriere quando il carrello pesa di più. Predefinito: 25 (i pacchi corriere di NZ Post arrivano fino a 25 kg); anche un campo vuoto significa 25. 0 significa nessun limite. Con Ignore shipping zones attivo, un campo vuoto significa nessun limite al di fuori delle zone proprie del corriere. Se Min cart weight è maggiore di Max cart weight, la pagina mostra un errore e non salva nulla, perché il corriere non verrebbe mai mostrato.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (dopo sconti, prima delle imposte) da cui la spedizione con NZ Post è gratuita. In quel caso non viene inviata alcuna richiesta a NZ Post. Lascia vuoto per non offrire mai la spedizione gratuita.

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

Availability without shipping zones

Normalmente il corriere viene mostrato nelle zone a cui è assegnato in Shipping > Carriers.

Ignore shipping zones: offre NZ Post per i paesi indicati sotto, indipendentemente dalla zona che corrisponde. Al salvataggio il corriere viene aggiunto a tutte le zone (anche a quelle create in seguito). Disattivando l'opzione, le zone aggiunte vengono di nuovo rimosse.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi attivi del negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Advanced

Debug log: scrive i calcoli delle tariffe in logs/vfd_nzpt_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. 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.

Log: mostra la dimensione e le ultime voci del log. Fai clic su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando il modulo vengono cancellate le impostazioni, il corriere, le tariffe memorizzate, i dettagli salvati degli ordini e i log. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nella fase di spedizione PrestaShop chiede al modulo il prezzo di NZ Post. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo controlla prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a NZ Post. Altrimenti cerca un prezzo: prima la tariffa NZ Post in tempo reale, poi la tabella dei paesi e infine il costo di riserva. Se non c'è alcun prezzo, il corriere viene nascosto.

Con le tariffe in tempo reale configurate, il modulo 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 codice postale del cliente, oltre al peso e alle dimensioni del pacco. PrestaShop non ha un campo per il sobborgo: il modulo usa Address line 2 quando contiene il nome di un sobborgo (senza cifre), altrimenti la città. Una tariffa nazionale viene richiesta solo dopo che il cliente ha inserito una città e un codice postale 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, supplementi e costi aggiuntivi obbligatori inclusi. Il prezzo viene convertito da NZD nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente. 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 corriere viene nascosto. Il motivo viene scritto nel log.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo le tariffe. Non crea etichette di spedizione, non prenota ritiri, non genera manifesti, non traccia i pacchi, non convalida gli 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 prezzato come un unico pacco, e il cliente vede una sola tariffa NZ Post, non un elenco di servizi.

Ordini

Quando viene effettuato un ordine con il corriere NZ Post, il modulo salva su cosa si basava il prezzo di spedizione. La pagina dell'ordine nel back office mostra un blocco NZ Post con NZ Post service (il servizio NZ Post prezzato di una tariffa in tempo reale) e Price source: Live rate (NZ Post ShippingOptions API), Fixed price oppure Free shipping. Il blocco mostra i valori del momento dell'ordine, anche se tariffe o impostazioni cambiano in seguito.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox NZ Post è il primo blocco in Modules > Module Manager > VibeFox NZ Post > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: presta-shipping-nz-post e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il corriere NZ Post non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

NZ Post non compare al checkout: verifica che la licenza sia attiva e che Enable NZ Post sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso e il Minimum order amount. Se NZ Post non restituisce una tariffa, il corriere viene mostrato solo con un prezzo per paese o un Fallback cost. I prodotti possono anche essere limitati a certi corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina del modulo. Poi attiva il Debug log, ricarica il checkout e controlla il campo Log. Gli errori dell'API ci sono sempre. Il log indica il motivo: Client ID o Client Secret mancanti, token rifiutato, dati di conto o di spedizione mancanti, ancora nessuna città o codice postale del cliente, nessun tasso NZD o nessun servizio prezzato. Finché correggi il problema vengono usati i prezzi fissi.

La richiesta del token non riesce: controlla Client ID, Client Secret e 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 l'Account number, l'Auth code o il Site code, e l'indirizzo di partenza completo con un codice postale a 4 cifre. Il cliente deve inserire una città e un codice postale a 4 cifre. Gli sviluppatori possono cambiare il sobborgo inviato per l'indirizzo di consegna con l'hook actionVfdNzptDeliverySuburb.

Il mio negozio non usa NZD: inserisci il NZD → (shop currency) rate. I prezzi fissi sono sempre nella valuta predefinita del negozio.

La GST viene addebitata due volte sulla spedizione: i prezzi nazionali di NZ Post includono il 15% di GST. Se il corriere ha una regola fiscale in Tax, imposta API prices su Excluding GST.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe NZ Post e i token memorizzati.

La pagina dice che il corriere NZ Post non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox NZ Post e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe e i token memorizzati vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimossi impostazioni, dettagli salvati degli ordini e log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, o con un Reset, il corriere salvato riacquista lo stato che aveva prima (attivo o disattivo).

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