VibeFox Australia Post for PrestaShop — Guida
Requisiti
PrestaShop: dalla 8.0 alla 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
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 sul Developer Centre di Australia Post (developers.auspost.com.au). La pagina del modulo rimanda 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: 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 cerca in seguito VibeFox Australia Post nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Configure e clicca su Activate (vedi Chiave di licenza).
4. Scegli il Rate source. Per le tariffe in tempo reale, inserisci la chiave PAC API, il tuo codice postale di partenza e, se la valuta predefinita del negozio non è AUD, il tasso di conversione in AUD (vedi Configurazione). Fai clic su Save.
All'installazione il modulo crea il corriere Australia Post con il testo dei tempi di consegna Australia Post parcel delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Zone, gruppi di clienti, tempi di consegna, logo, limiti di dimensione e regola fiscale si possono modificare in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Australia Post > Configure. Si applicano a tutte le zone. In cima alla pagina compaiono il nome e l'ID del corriere in Shipping > Carriers. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota anche la cache delle tariffe di Australia Post.
Se è scelta una fonte di tariffe in tempo reale ma manca la chiave API, un codice postale di partenza a 4 cifre o il tasso di conversione in AUD, dopo il salvataggio compare un avviso. Indica anche cosa succede finché non correggi: il corriere viene nascosto al checkout oppure, in modalità di riserva, si usano i prezzi fissi per paese.
I campi numerici accettano un punto o una virgola come separatore decimale. Un valore che non è un numero o è negativo non viene salvato: un avviso indica il campo e resta il valore precedente. La pagina avvisa anche se l'unità di peso o di dimensione del negozio (International > Localization) non è riconosciuta dal modulo. In quel caso i pesi dei prodotti vengono letti come kg e le dimensioni come cm.
Generali
Enable Australia Post: disattiva il corriere in tutte le zone contemporaneamente. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Method title: il nome del corriere mostrato al cliente al checkout. È anche il nome del corriere in Shipping > Carriers, e rinominare il corriere lì aggiorna questo campo. Predefinito: Australia Post. Massimo 64 caratteri: un titolo più lungo viene rifiutato e non si salva nulla. Se il campo è vuoto o contiene caratteri che PrestaShop non ammette in un nome di corriere, compare un avviso e viene usato Australia Post.
Tax status: come viene applicata l'imposta al costo della spedizione.
Rate source: come viene calcolato il prezzo.
I dettagli degli errori finiscono nel log, mai al cliente.
Australia Post API (live rates) (non necessaria per i prezzi fissi)
PAC API key: la tua chiave gratuita PAC API 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 valore nuovo solo se vuoi cambiarlo.
Remove the saved API key: attiva e salva per eliminare la chiave salvata. Le tariffe in tempo reale smettono 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 all'interno dell'Australia (fino a 22 kg, 105 cm per lato): Parcel Post (predefinito) oppure Express Post.
International service: usato per le consegne al di fuori dell'Australia (fino a 20 kg): International Standard (predefinito), International Express oppure 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 PrestaShop aggiunge da sé l'imposta alla spedizione (Tax status = Taxable con una regola fiscale sul corriere), così la GST non viene addebitata due volte. Il servizio postale internazionale è esente da GST e non viene mai modificato.
AUD → (your currency) rate: l'etichetta mostra la valuta predefinita del negozio. I prezzi di Australia Post sono in AUD. Se la valuta predefinita non è 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 valuta predefinita è AUD, la pagina indica che non serve alcuna conversione: lascia il campo vuoto. Sono accettati sia il punto sia la virgola come separatore decimale.
Pacco per le tariffe in tempo reale
Il carrello viene inviato come un unico pacco. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del negozio in kg e cm. I valori seguenti si usano 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 loro, 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 delle tariffe in tempo reale)
Country prices: una tabella di codici paese a 2 lettere (AU, NZ, US e così via) e di prezzi nella valuta predefinita del negozio, IVA esclusa. Fai clic su Add row per aggiungere un paese e sul link × per rimuoverne uno. Usa * per tutti gli altri paesi. Un paese senza prezzo (e senza riga *) non ha una tariffa fissa, quindi per esso il corriere viene nascosto. Le righe con un codice paese non valido o senza prezzo vengono eliminate al salvataggio. La tabella è vuota finché non aggiungi dei prezzi.
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. Le tariffe in tempo reale vengono sempre calcolate per l'intero pacco.
Condizioni
Min cart weight (kg): nasconde il corriere se il peso del carrello è inferiore a questo valore. 0 significa nessun limite.
Max cart weight (kg): nasconde il corriere se il peso del carrello è superiore a questo valore. 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 corriere non verrebbe mai mostrato: compare un avviso e i due pesi mantengono i valori precedenti.
Minimum order amount: mostra il corriere solo quando il subtotale dei prodotti (dopo gli sconti, IVA esclusa) raggiunge questo importo, nella valuta predefinita del negozio. Lascia il campo vuoto per mostrarlo sempre.
Free shipping: attiva la spedizione gratuita a partire dall'importo indicato sotto.
Free shipping from: il subtotale dei prodotti (dopo gli sconti, IVA esclusa) da cui la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta all'API. Si usa solo quando Free shipping è attivo.
Disponibilità senza zone di spedizione
Di norma il corriere viene offerto nelle zone selezionate per lui in Shipping > Carriers.
Ignore shipping zones: offre il corriere per i paesi indicati sotto, qualunque zona corrisponda. Al salvataggio il corriere viene collegato a tutte le zone, e le zone create in seguito vengono collegate automaticamente. Disattivando l'opzione tornano le zone che il corriere aveva prima.
Countries: i paesi di destinazione per questa modalità. Lascia il campo vuoto per consentire tutti i paesi attivi. Tieni premuto Ctrl (Cmd su Mac) e fai clic per selezionarne più di uno. Si usa solo con Ignore shipping zones.
Avanzate
Debug log: registra i calcoli delle tariffe in modules/vfd_australia_post/logs/vfd_ap.log.php. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati. La chiave API e i codici postali 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, la disinstallazione del modulo elimina le impostazioni, le tariffe in cache e il log. Il corriere viene sempre rimosso alla disinstallazione. Reinstallando, viene ripristinato se i dati sono stati conservati.
Come funziona al checkout
Al passaggio di spedizione PrestaShop chiede al modulo il prezzo di Australia Post. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non rientrano nell'importo dell'ordine. Il modulo controlla prima le condizioni: l'elenco Countries (con Ignore shipping zones), il peso del carrello e il Minimum order amount. 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à di tariffe in tempo reale il modulo invia ad Australia Post il peso del pacco e, per le consegne in Australia, i codici postali di partenza e di destinazione e le dimensioni del pacco; per le consegne internazionali, il paese di destinazione. Una tariffa nazionale in tempo reale viene richiesta solo quando l'indirizzo di consegna ha un codice postale a 4 cifre. Non viene inviata alcuna richiesta quando 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, se Remove GST è attivo, la GST viene tolta dai prezzi nazionali. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.
Ogni risposta riuscita viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita viene memorizzata nella cache per 10 minuti, così il checkout non aspetta Australia Post a ogni aggiornamento. Il timeout dell'API è di 10 secondi. Gli errori dell'API non vengono mai mostrati al cliente: il corriere viene nascosto oppure, in modalità di riserva, si usa il prezzo fisso. 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, spedizioni o distinte eParcel o MyPost Business, non traccia i pacchi e non consente ai clienti di scegliere armadietti automatici o uffici postali. Il carrello viene sempre tariffato come un unico pacco. Lettere, buste e tariffe contrattuali (eParcel) non sono incluse.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Australia Post è il primo blocco di Modules > Module Manager > VibeFox Australia Post > Configure, sopra le impostazioni. Inserisci 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 compaiono la riga Product: presta-shipping-australia-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 o License expired on seguito da una data. Dopo una modifica dell'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, clicca 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, il corriere Australia Post non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront 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 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 supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a 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
Australia Post non compare al checkout: controlla che la licenza sia attiva e che Enable Australia Post sia attivo (il corriere è attivo in Shipping > Carriers). In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e che il paese sia consentito in Countries). Controlla i limiti di peso del carrello e il Minimum order amount. In modalità prezzi fissi controlla che il paese o * abbia un prezzo. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Mostra il motivo: manca la chiave API o il codice postale di partenza, non c'è ancora un codice postale di consegna a 4 cifre, il pacco supera i limiti, manca il tasso di conversione in AUD oppure compare il messaggio di errore di Australia Post. Con Live rates, fixed price if the API gives no rate, i clienti vedono comunque il prezzo fisso mentre tu risolvi il problema.
Il mio negozio non usa AUD: inserisci il tasso di conversione (quante unità della valuta predefinita valgono un AUD) nel campo AUD → (your currency) rate. I prezzi fissi sono sempre nella valuta predefinita.
La GST sulla spedizione viene addebitata due volte: i prezzi nazionali di Australia Post includono il 10% di GST. Se Tax status è Taxable e il corriere ha una regola fiscale, attiva Remove GST oppure imposta Tax status su None.
Alla spedizione non viene aggiunta alcuna imposta: con Tax status = Taxable l'imposta viene dalla regola fiscale del corriere. Selezionala in Shipping > Carriers. La pagina del modulo mostra un avviso finché il corriere non ha una regola fiscale.
Il prezzo è troppo alto o troppo basso: controlla i pesi e le dimensioni dei prodotti e i valori predefiniti in Pacco per le tariffe in tempo reale. Con Item (price × quantity) i prezzi fissi vengono moltiplicati per il numero di articoli.
Le tariffe sembrano non aggiornate dopo una modifica: fai clic su Save nella pagina del modulo. Così si svuota la cache delle tariffe di Australia Post.
La pagina indica che il corriere Australia Post è stato eliminato: il corriere è stato eliminato in Shipping > Carriers. Fai clic su Save nella pagina del modulo per ricrearlo, oppure ripristina il modulo in Modules > Module Manager.
Disinstallazione
Vai in Modules > Module Manager, apri il menu accanto a VibeFox Australia Post e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Il corriere viene sempre rimosso (gli ordini conservano lo storico) e la cache delle tariffe viene svuotata. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni, la tabella della cache delle tariffe e il log. Se è disattivo, le impostazioni vengono conservate e reinstallando il modulo si ripristina il corriere con le sue zone, i gruppi e il logo.
Australia Post è un marchio registrato del suo titolare. Questo modulo non è affiliato ad Australia Post né da essa approvato.