VibeFox Australia Post for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Chiave PAC API di Australia Post (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API Postage Assessment Calculator (PAC) di Australia Post. La chiave è gratuita: registrati per ottenere una chiave PAC API sull'Australia Post Developer Centre (developers.auspost.com.au). La pagina delle impostazioni contiene un collegamento alla pagina di registrazione. Ti serve anche il codice postale australiano a 4 cifre da cui spedisci. Se usi solo prezzi fissi per paese, non ti serve una chiave 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_australia_post-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_australia_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_australia_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 Australia Post e clicca su Install (il pulsante verde +).

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

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

5. Scegli la Rate source (fonte delle tariffe). Per i prezzi fissi, aggiungi righe in Country prices. Per le tariffe in tempo reale, inserisci la chiave PAC API, il codice postale di partenza e, se la valuta predefinita del tuo negozio non è l'AUD, il tasso di conversione in AUD (vedi Configurazione). Attiva Enable Australia Post e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_australia_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. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Australia Post, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

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

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

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Australia Post > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe di Australia Post in cache. Possono salvare le impostazioni solo gli utenti amministratori con il permesso di modifica per questa estensione.

Alcuni errori impediscono il salvataggio, e in tal caso non viene salvato nulla: un Method title di più di 64 caratteri, un Sort order che non è un numero intero, oppure una classe d'imposta o una zona geografica sconosciuta. Altri problemi vengono mostrati come avvisi sopra il pannello, e il resto delle impostazioni viene salvato. Un campo numerico con un valore che non è un numero o è negativo mantiene il valore precedente, e l'avviso indica il campo. I campi numerici accettano il punto o la virgola come separatore decimale.

Se è scelta una fonte di tariffe in tempo reale ma manca la chiave API, il codice postale di partenza a 4 cifre o il tasso di conversione in AUD, dopo il salvataggio viene mostrato un avviso. Indica anche cosa succede finché non lo correggi: il metodo viene nascosto al checkout, oppure in modalità di riserva vengono usati i prezzi fissi per paese. La pagina avvisa anche se il tuo negozio non ha una classe di peso con unità kg né una classe di lunghezza con unità cm. In tal caso pesi e dimensioni dei prodotti vengono convertiti secondo l'unità della loro classe (kg, g, lb, oz; cm, mm, m, in), e le altre unità vengono lette come kg e cm.

Generale

Le impostazioni valgono per tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Conditions, oppure a un elenco di paesi in Availability without shipping zones.

Enable Australia Post: mostra o nasconde Australia Post al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione che il cliente vede nel carrello e al checkout. Predefinito: Australia Post. Al massimo 64 caratteri: un titolo più lungo viene rifiutato e non viene salvato nulla. Se il campo è vuoto, viene mostrato un avviso e si usa Australia Post.

Rate source: come viene calcolato il prezzo.

I dettagli degli errori vanno nel registro, mai al cliente.

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

API Australia Post (tariffe in tempo reale) (non necessaria per i prezzi fissi)

PAC API key: la tua chiave PAC API gratuita di Australia Post. Viene inviata ad Australia Post nell'intestazione AUTH-KEY. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Remove the saved API key: attiva e salva per eliminare la chiave salvata. Le tariffe in tempo reale smettono allora di funzionare.

Ship-from postcode: il codice postale australiano a 4 cifre da cui vengono spediti i pacchi, per esempio 2000.

Domestic service: usato per le consegne in Australia (fino a 22 kg, 105 cm per lato): Parcel Post (predefinito) o Express Post.

International service: usato per le consegne fuori dall'Australia (fino a 20 kg): International Standard (predefinito), International Express o International Courier.

Remove GST: divide per 1,1 i prezzi nazionali dell'API. I prezzi nazionali di Australia Post includono il 10% di GST. Attivalo quando OpenCart aggiunge l'imposta alla spedizione da solo (è selezionata una Tax class), così il GST non viene addebitato due volte. La spedizione internazionale è esente da GST e non viene mai modificata.

AUD → (your currency) rate: l'etichetta mostra la valuta predefinita del tuo negozio. I prezzi di Australia Post sono in AUD. Se la tua valuta predefinita non è l'AUD, inserisci quante unità della tua valuta vale un AUD, per esempio 0,61. Il tasso deve essere maggiore di 0. Senza di esso le tariffe in tempo reale non vengono usate. Se la tua valuta predefinita è l'AUD, il campo indica che non serve alcuna conversione: lascialo vuoto.

Pacco per le tariffe in tempo reale

Il carrello viene inviato come un unico pacco. Pesi e dimensioni dei prodotti vengono convertiti dalle classi di peso e di lunghezza di OpenCart in kg e cm. I valori seguenti vengono usati per i prodotti senza peso o dimensioni.

Default product weight (kg): usato per ogni prodotto senza peso, nella richiesta ad Australia Post e nel controllo di Min cart weight (kg) / Max cart weight (kg). Predefinito: 1.

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

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

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

Quando i prodotti hanno dimensioni, il pacco prende la lunghezza e la larghezza maggiori tra di essi, e l'altezza cresce finché il pacco non contiene il volume di tutti gli articoli.

Prezzi fissi (usati con i prezzi fissi e come riserva per le tariffe in tempo reale)

Country prices: un elenco di paesi e prezzi nella valuta predefinita del tuo negozio, IVA esclusa. Clicca su Add row per aggiungere una riga e sul pulsante × per rimuoverne una. Scegli * All other countries per un prezzo usato per ogni paese senza una riga propria. Un paese senza prezzo (e senza una riga *) non ha una tariffa fissa, quindi il metodo viene nascosto per lui. Le righe senza prezzo vengono eliminate al salvataggio. La tabella è vuota finché non aggiungi dei prezzi.

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

Condizioni

Min cart weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).

Max cart weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 22. 0 significa nessun limite, un campo vuoto significa 22 kg. Pacchi di Australia Post: 22 kg in Australia, 20 kg internazionali. Se Min cart weight (kg) è maggiore del massimo, il metodo non verrebbe mai mostrato: compare un avviso e entrambi i pesi mantengono i valori precedenti.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti da spedire (dopo il coupon, IVA esclusa, nella valuta predefinita del negozio) raggiunge questo importo. Lascia vuoto il campo per mostrarlo sempre.

Free shipping: attiva la spedizione gratuita dall'importo indicato sotto.

Free shipping from: il subtotale dei prodotti da spedire (dopo il coupon, IVA esclusa) da cui la spedizione è gratuita. In questo caso non viene fatta alcuna richiesta all'API. Usato solo quando Free shipping è attivo.

Tax class: la classe d'imposta del costo di spedizione, oppure No tax (predefinito). I prezzi nazionali di Australia Post includono il GST: con una classe d'imposta, attiva Remove GST.

Geo zone: offri Australia 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. Non viene usato con Ignore shipping zones.

Disponibilità senza zone di spedizione

Normalmente il metodo viene offerto nella zona geografica scelta in Conditions (All zones significa ovunque).

Ignore shipping zones: offri il metodo per i paesi indicati sotto, qualunque sia la zona geografica.

Countries: i paesi di destinazione per quella modalità. Digita per cercare e seleziona più paesi. Lascia vuoto il campo per consentire tutti i paesi attivi del negozio. Usato solo con Ignore shipping zones.

Avanzate

Debug log: registra i calcoli delle tariffe in storage/logs/vfd_ap.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati. La chiave API e i codici postali dei clienti non vengono registrati. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_ap.old.log.php e si avvia un nuovo registro.

Log: mostra la dimensione e le voci più recenti del registro. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminati impostazioni, tariffe in cache e registro. Se disattivo (predefinito), vengono conservati per una reinstallazione.

Importa / esporta

Esporta: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

Importa: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Australia Post. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, Australia Post non viene offerto. Con Ignore shipping zones decide l'elenco Countries. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. Poi l'estensione controlla il peso del carrello e il Minimum order amount. L'importo dell'ordine è il prezzo dei prodotti da spedire, 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 ad Australia Post.

In modalità prezzi fissi il prezzo viene preso dalla tabella. Nelle modalità in tempo reale l'estensione invia ad Australia Post il peso del pacco e, per le consegne in Australia, i codici postali di partenza e di consegna e le dimensioni del pacco; per le spedizioni internazionali, il paese di destinazione. Una tariffa nazionale in tempo reale viene richiesta solo se l'indirizzo di consegna ha un codice postale a 4 cifre. Nessuna richiesta viene inviata se il pacco supera i limiti di Australia Post (22 kg o 105 cm in Australia, 20 kg internazionali). Il prezzo in AUD viene convertito con il tuo tasso, e il GST viene rimosso dai prezzi nazionali se Remove GST è attivo. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta riuscita viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende Australia Post a ogni aggiornamento. Il timeout dell'API è di 10 secondi. Gli errori dell'API non vengono mai mostrati al cliente: il metodo viene nascosto, oppure in modalità di riserva viene usato il prezzo fisso. Il motivo viene scritto nel registro.

L'estensione calcola solo le tariffe. Non crea etichette di spedizione, spedizioni o distinte eParcel o MyPost Business, non traccia i pacchi e non permette ai clienti di scegliere armadietti automatici o uffici postali. Non aggiunge nulla agli ordini: l'ordine mostra il nome del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart. Il carrello viene sempre tariffato come un unico pacco. Lettere, buste e tariffe contrattuali (eParcel) non sono incluse.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Australia Post nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Australia Post è il primo blocco di Extensions > Extensions > Shipping > VibeFox Australia 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 a cui 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 ci sono la riga Product: opencart-shipping-australia-post e il collegamento Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua del pannello (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 o 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, clicca 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 il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Australia Post non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso al pannello nello stesso browser vede ancora il metodo nel negozio, contrassegnato come (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 al pannello, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard del pannello compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard del pannello 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. Disinstallando l'estensione vengono sempre rimossi la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Australia Post non compare al checkout: verifica che la licenza sia attiva e che Enable Australia Post sia attivo. Controlla Geo zone (oppure Ignore shipping zones e Countries), i limiti di peso del carrello e Minimum order amount. In modalità prezzi fissi, verifica che il paese o * All other countries abbia un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Mostra il motivo: chiave API o codice postale di partenza mancanti, nessun codice postale di consegna a 4 cifre ancora, un pacco oltre i limiti, nessun tasso AUD, oppure il messaggio di errore di Australia Post. Con Live rates, fixed price if the API gives no rate i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.

Il mio negozio non è in AUD: inserisci il tasso di conversione (quante unità della valuta predefinita vale un AUD) nel campo AUD → (your currency) rate. I prezzi fissi sono sempre nella valuta predefinita del negozio.

Il GST viene addebitato due volte sulla spedizione: i prezzi nazionali di Australia Post includono il 10% di GST. Se è selezionata una Tax class, attiva Remove GST, oppure imposta Tax class su No tax.

Il prezzo è troppo alto o troppo basso: controlla i pesi e le dimensioni dei prodotti, le loro classi di peso e di lunghezza, e i valori predefiniti in Parcel for live rates. Con Item (price × quantity) i prezzi fissi vengono moltiplicati per il numero di articoli.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota le tariffe di Australia Post in cache.

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

Per gli sviluppatori: l'indirizzo della PAC API può essere sostituito con l'impostazione vfd_ap_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 Australia Post. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Australia Post, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni di Australia Post e il registro. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. 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, clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Australia Post nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Australia Post è un marchio del suo rispettivo titolare. Questa estensione non è affiliata ad Australia Post né approvata da Australia Post.