VibeFox NZ Post for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la 3.0.5.0) o 4.0.2 e successivi (testato con la 4.1.0.3).

PHP: 8.0 o successivo.

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

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

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_nz_post-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_nz_post.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_nz_post-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox NZ Post e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco di licenza, in cima alla pagina Edit, e clicca su Activate (vedi Chiave di licenza).

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

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_nz_post.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate, nella stessa pagina. Fai clic su Install (il pulsante verde +) accanto a esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox NZ Post, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali nelle due versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable NZ Post e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni NZ Post che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox NZ Post > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe NZ Post e i token di accesso memorizzati nella cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Non viene salvato nulla e compare un errore quando Method title è vuoto, supera 64 caratteri o contiene < > ; = # { }, quando un campo numerico contiene testo o un numero negativo, quando il tasso NZD è 0, quando Min cart weight (kg) è maggiore di Max cart weight (kg) o quando Sort order non è un numero intero. 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 in NZD o dati incompleti per le tariffe nazionali. Compare un avviso anche se il negozio non ha una classe di peso con unità kg o una classe di lunghezza con unità cm: pesi e dimensioni vengono allora convertiti in base al nome dell'unità della loro classe (kg, g, lb, oz; cm, mm, m, in), mentre le altre unità vengono lette come kg e cm.

Generali

Le impostazioni si applicano a tutte le zone geografiche. Puoi limitare il metodo a una zona geografica, o a dei paesi, in Availability.

Enable NZ Post: attiva o disattiva il metodo al checkout. Predefinito: disattivato.

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

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito; il costo di spedizione non è tassato). Se il negozio aggiunge la GST alla spedizione, imposta API prices qui sotto su Excluding GST per non applicarla due volte.

Sort order: la posizione di NZ Post tra i metodi di spedizione al checkout. Un numero intero.

NZ Post API (tariffe in tempo reale) (lascia il Client ID vuoto 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 rilasciato il tuo Client ID.

Client ID: l'ID client OAuth2 della tua applicazione API NZ Post. Cancellarlo cancella anche il Client Secret salvato.

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

Account number: il numero del tuo account 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. Cancellarlo cancella anche l'auth code salvato.

Auth code: l'auth code dell'account per le tariffe nazionali. Non serve se inserisci un site code. Come il Client Secret, non viene più mostrato dopo il salvataggio.

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

Ship-from suburb: il quartiere dell'indirizzo da cui vengono spediti i pacchi, per esempio Petone. Necessario per le tariffe nazionali.

Ship-from city: la città o il centro da cui vengono spediti i pacchi, per esempio Lower Hutt. Necessaria per le tariffe nazionali.

Ship-from postcode: il codice postale neozelandese di 4 cifre da cui vengono spediti 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. Le tariffe nazionali NZ Post includono la GST del 15%; il francobollo internazionale è a tasso zero. Scegli Excluding GST quando il metodo ha una classe fiscale (General), così la GST non viene applicata due volte.

Tasso NZD → (valuta del negozio): i prezzi NZ Post sono in NZD. Se la valuta predefinita del tuo negozio non è il NZD, inserisci quante unità della tua valuta vale un NZD, per esempio 0.55. Senza questo valore non vengono usate le tariffe in tempo reale. Lo stesso tasso converte il valore dell'ordine inviato nelle richieste internazionali. Il tasso deve essere maggiore di 0. Se la valuta del tuo negozio è il NZD, lascia il campo 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 loro classi di peso e di lunghezza in kg e cm (mm per le richieste internazionali). Il pacco prende la lunghezza e la larghezza maggiori dei prodotti, e la sua altezza cresce fino a contenere il volume di tutti gli articoli. I valori qui 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 del carrello ha dimensioni. Predefinito: 30.

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

Default parcel height (cm): usato quando nessun prodotto del carrello ha 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 predefinita del negozio, IVA esclusa.

Country prices: una riga per paese di destinazione. Clicca su Add country per aggiungere una riga e sul pulsante × 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 alcun prezzo e i prezzi negativi vengono rimossi al salvataggio. Per ogni paese viene mantenuta una sola riga.

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

Fixed price per: Order (predefinito) 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 vengono sempre calcolate per l'intero pacco.

Condizioni

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

Max cart weight (kg): nasconde il metodo 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 per gli indirizzi fuori dalla Geo zone.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale (dopo il coupon, prima delle imposte) a partire dal quale la spedizione con NZ Post è gratuita. In quel caso non viene inviata alcuna richiesta a NZ Post. Lascialo vuoto per non offrire mai la spedizione gratuita.

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

Disponibilità

Di norma il metodo viene offerto nella zona geografica selezionata qui sotto, oppure ovunque se non ne è selezionata nessuna.

Geo zone: offri NZ Post solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: offri NZ Post anche fuori dalla zona geografica, per i paesi indicati sotto. Quando è attivo, solo questi paesi ricevono il metodo, anche all'interno della zona geografica. Predefinito: disattivato.

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

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_nzpt_debug.log.php (su OpenCart 4 system/storage/logs/vfd_nzpt_debug.log.php). Il file non è leggibile dal web. Gli errori dell'API vengono sempre registrati, anche con il log di debug disattivato. Credenziali, token, numero di account e indirizzi dei clienti non vengono registrati. Disattiva il log quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_nzpt_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni e il log. Se disattivato (predefinito), vengono conservati per una reinstallazione. Le tariffe in cache vengono sempre eliminate. I dati NZ Post degli ordini vengono sempre conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il Client Secret e l'auth code non vengono esportati.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. Il Client Secret e l'auth code salvati vengono mantenuti finché sono compilati il Client ID e il numero di account.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di NZ Post. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, NZ Post viene offerto solo quando Ignore shipping zones è attivo e il paese è consentito. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. Poi l'estensione controlla le condizioni: i paesi consentiti (con Ignore shipping zones), il peso del carrello e l'importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. 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, poi il costo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto.

Con le tariffe in tempo reale configurate, l'estensione 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 account, l'indirizzo di spedizione, il quartiere, la città e il codice postale del cliente, oltre al peso e alle dimensioni del pacco. OpenCart non ha un campo quartiere: l'estensione usa Address 2 quando contiene il nome di un quartiere (senza cifre), altrimenti la città. Una tariffa nazionale viene richiesta solo dopo che il cliente ha inserito una città e un codice postale di 4 cifre. Per gli altri paesi invia il paese di destinazione, il peso e le dimensioni del pacco e il valore dell'ordine in NZD.

Viene usato il servizio consentito più economico con un prezzo, inclusi supplementi e opzioni obbligatorie. Il prezzo viene convertito da NZD alla valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata. Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende NZ Post a ogni aggiornamento. Il timeout dell'API è di 10 secondi. Il token di accesso viene mantenuto fino alla scadenza, e un token rifiutato 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. Viene usato 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.

Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie un'opzione NZ Post nella finestra Shipping method options. Le tariffe sono le stesse di OpenCart 3.

L'estensione calcola solo le tariffe. Non crea etichette di spedizione, non genera manifesti, non prenota ritiri, non traccia i pacchi, non convalida gli indirizzi e non permette al cliente di scegliere un punto di ritiro, una casella postale (PO Box) o un armadietto automatico. 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 NZ Post, l'estensione salva su cosa si basava il prezzo di spedizione. Apri l'ordine in Sales > Orders: la pagina dell'ordine mostra un pannello NZ Post con NZ Post service (il servizio NZ Post prezzato di una tariffa in tempo reale, con il suo codice) e Price source: Live rate (NZ Post ShippingOptions API), Fixed price oppure Free shipping. Il pannello mostra i valori del momento dell'ordine, anche se tariffe o impostazioni cambiano in seguito, e anche mentre il metodo è disattivato. Il cliente non vede il nome del servizio.

Su OpenCart 4 il pannello NZ Post viene mostrato sopra History. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo: il servizio salvato e l'origine del prezzo vengono aggiornati insieme ad esso. Se il cliente passa quell'ordine a un altro metodo di spedizione, i dati NZ Post dell'ordine vengono rimossi.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox NZ Post è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox NZ Post > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca 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 compaiono la riga Product: opencart-shipping-nz-post e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono modificare la chiave. I testi del blocco seguono la lingua del pannello di amministrazione (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 con una data. Dopo la modifica dell'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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera lo slot del suo dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, NZ Post non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso al pannello di amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard del pannello di amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard del pannello di amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione 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. Controlla Geo zone (o Ignore shipping zones e Countries), i limiti di peso e Minimum order amount. Se NZ Post non restituisce una tariffa, il metodo viene mostrato solo con un prezzo per paese o un Fallback cost. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina dell'estensione. Poi attiva il Debug log, ricarica il checkout e controlla il campo Log. Gli errori dell'API sono sempre lì. Il log mostra il motivo: Client ID o Client Secret mancante, token rifiutato, dati di account o di spedizione mancanti, nessuna città o codice postale del cliente ancora, nessun tasso NZD o nessun servizio con prezzo. Mentre risolvi il problema vengono usati i prezzi fissi.

La richiesta del token non riesce: controlla il Client ID, il Client Secret e l'Environment. Le credenziali UAT non funzionano con la 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 spedizione completo con un codice postale di 4 cifre. Il cliente deve inserire una città e un codice postale di 4 cifre.

Il mio negozio non è in NZD: inserisci il tasso NZD (il campo NZD → (la tua valuta) rate). I prezzi fissi sono sempre nella valuta predefinita del negozio.

La GST viene applicata due volte sulla spedizione: le tariffe nazionali NZ Post includono la GST del 15%. Se il metodo ha una Tax class, imposta API prices su Excluding GST.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe e i token NZ Post memorizzati nella cache.

La pagina mostra "Warning: You do not have permission to modify VibeFox NZ Post!": il tuo gruppo di utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_nz_post (OpenCart 3) o extension/vfd_nz_post/shipping/vfd_nz_post (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: il quartiere inviato per un indirizzo di consegna in Nuova Zelanda può essere modificato con l'evento OpenCart vfd_nz_post/delivery_suburb (trigger catalog/vfd_nz_post/delivery_suburb). L'indirizzo dell'API NZ Post può essere sostituito con l'impostazione vfd_nzpt_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox NZ Post. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart reimposta sempre Enable NZ Post, Sort order, Tax class e Geo zone. Le tariffe e i token in cache vengono sempre eliminati, e il pannello NZ Post non viene più mostrato nella pagina dell'ordine. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni NZ Post e il log di debug. Se è disattivato, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I dati NZ Post salvati degli ordini non vengono mai eliminati e ricompaiono dopo una reinstallazione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e fai clic su Uninstall (il pulsante arancione −) accanto a VibeFox NZ Post nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

NZ Post è un marchio del rispettivo proprietario. Questa estensione non è affiliata né approvata da NZ Post.