VibeFox Purolator 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. L'estensione SOAP di PHP non è richiesta.

Purolator E-Ship Web Services (solo per le tariffe in tempo reale): registrati a E-Ship Web Services nel Purolator E-Ship Resource Centre sul sito di Purolator. Purolator fornisce chiavi e password separate per gli ambienti di sviluppo e di produzione. Ti servono anche il numero del tuo account di fatturazione Purolator e il codice postale canadese da cui spedisci. Se usi solo prezzi fissi, non servono chiavi 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 Purolator 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 Purolator API (live rates). Per i test, attiva Development environment con la chiave di sviluppo. Compila Country prices o Fallback price se vuoi prezzi fissi o un prezzo di riserva (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere Purolator con il testo dei tempi di consegna Purolator courier. Il corriere è 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 arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Purolator > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Purolator in cache.

Se le tariffe in tempo reale non possono funzionare con i valori salvati (chiave, password o account di fatturazione mancanti, nessun codice postale canadese di spedizione, nessun tasso CAD), oppure se non ci sono né credenziali API né prezzi fissi, sopra le impostazioni compare un avviso. Un avviso compare anche se l'unità di peso del negozio non è tra quelle note al modulo (kg, g, lb, oz e simili). In tal caso i pesi dei prodotti vengono considerati in kg. Imposta l'unità di peso in International > Localization (Local units).

Un campo numerico che non contiene un numero pari o superiore a 0 non viene salvato. Un avviso indica il campo e il valore. Il campo resta vuoto oppure, per i campi di peso, riceve il valore predefinito. Un valore errato in Country prices viene salvato come 0 e l'avviso indica il paese e la colonna. Se Min cart weight è maggiore di Max cart weight, non viene salvato nulla e compare un errore.

Generale

Enable Purolator: 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 nel checkout. Predefinito: Purolator. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Stabilisce se il negozio aggiunge l'imposta sul costo della spedizione. Per gli indirizzi canadesi il totale Purolator include già GST/HST/PST/QST. Vedi Canadian sales taxes più sotto.

API Purolator (tariffe in tempo reale)

Con chiave API, password e account di fatturazione compilati, il prezzo arriva dal web service Purolator E-Ship Estimating. Se Purolator non fornisce una tariffa, si usa il prezzo fisso, oppure il corriere viene nascosto se non ce n'è uno. La sezione contiene un link al Purolator E-Ship Resource Centre, dove ti registri e ottieni le chiavi.

API key: la tua chiave E-Ship Web Services per l'ambiente selezionato. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo se vuoi cambiarla.

API password: la password associata alla chiave. Come la chiave, non viene più mostrata dopo il salvataggio.

Billing account number: il tuo numero di account Purolator. Le stime usano le tariffe di questo account. L'ambiente di sviluppo accetta l'account di prova della documentazione Purolator. Svuotare questo campo rimuove anche la chiave e la password API salvate.

Development environment: usa l'ambiente di sviluppo di Purolator (devwebservices.purolator.com) con la chiave di sviluppo. I prezzi sono dati di prova. Disattivalo su un negozio attivo.

Ship-from postal code: il codice postale canadese da cui vengono spediti i pacchi, per esempio L4W 5M8.

Service in Canada: Cheapest available (predefinito), Purolator Ground, Purolator Ground 9AM, Purolator Ground 10:30AM, Purolator Ground Evening, Purolator Express, Purolator Express 9AM, Purolator Express 10:30AM, Purolator Express 12PM o Purolator Express Evening.

Service to the USA: Cheapest available (predefinito), Purolator Ground U.S., Purolator Express U.S., Purolator Express U.S. 9AM, Purolator Express U.S. 10:30AM o Purolator Express U.S. 12:00.

International service: Cheapest available (predefinito), Purolator Express International, Purolator Express International 9AM, Purolator Express International 10:30AM o Purolator Express International 12:00.

Se il servizio scelto non è offerto per l'indirizzo, si usa il più economico disponibile.

Canadian sales taxes: usa i prezzi Purolator senza GST/HST/PST/QST. Per gli indirizzi canadesi il totale Purolator include queste imposte. Attivalo quando il corriere ha una regola fiscale in Tax, così l'imposta non viene addebitata due volte.

CAD → (shop currency) rate: i prezzi Purolator sono in CAD. Se la valuta predefinita del negozio non è il CAD, indica quante unità della tua valuta valgono un CAD, per esempio 0.68. Senza questo valore le tariffe in tempo reale non vengono usate. Se la valuta predefinita è il CAD, lascia il campo vuoto.

Default product weight: in kg, usato per ogni prodotto senza peso. Predefinito: 0.5. I pesi vengono convertiti dall'unità di peso del negozio e inviati a Purolator come peso totale in libbre intere, arrotondato per eccesso.

Prezzi fissi (usati senza credenziali API e come alternativa quando l'API non fornisce una tariffa)

Country prices: un prezzo per paese e peso del carrello, nella valuta predefinita del negozio, tasse escluse. Fai clic su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. Scegli * Default (all other countries) per una riga che copre tutti i paesi senza una riga propria. Ogni riga ha un prezzo Base e colonne di dimensione: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL oltre 5 kg. Un prezzo di dimensione vuoto o pari a zero usa Base. Un Base pari a 0, o un Base vuoto, significa spedizione gratuita per i pesi senza un prezzo di dimensione proprio. Sono accettati sia 9.99 sia 9,99. Le righe senza alcun prezzo non vengono salvate, e per ogni paese resta una sola riga.

Fallback price: il prezzo per un paese che non ha una riga in Country prices né una riga *. Lascialo vuoto per nascondere il corriere per questi paesi.

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 sono sempre calcolate per l'intera spedizione.

Condizioni

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

Max cart weight: in kg, nasconde il corriere quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite.

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

Free shipping from: il subtotale del carrello (dopo sconti, prima delle tasse) da cui la consegna è gratuita. In quel caso non viene inviata alcuna richiesta a Purolator. Lascia 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

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

Ignore shipping zones: offre Purolator per i paesi indicati sotto, indipendentemente dalla zona corrispondente. Al salvataggio il corriere viene aggiunto a tutte le zone, e vengono aggiunte anche le zone create in seguito. Disattivando l'opzione, quelle zone 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.

Avanzate

Debug log: scrive i calcoli delle tariffe in logs/vfd_prlr_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori delle API vengono sempre registrati, anche con il log di debug disattivato. Chiavi API, account di fatturazione e 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 impostazioni, corriere, tariffe in cache e log. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona nel checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Purolator. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Prima che il cliente inserisca un indirizzo, il prezzo viene stimato per il paese che il negozio usa per le stime. 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 Purolator. Poi cerca un prezzo: prima la tariffa Purolator in tempo reale, poi la tabella per paese, poi il prezzo di riserva. Se non c'è alcun prezzo, il corriere viene nascosto.

Con le credenziali API il modulo invia a Purolator una richiesta Quick Estimate: il tuo account di fatturazione, il codice postale di spedizione, la città, la provincia o lo stato del cliente, il paese e il codice postale, e il peso totale del carrello in libbre intere. Per il Canada serve un codice postale valido; per gli Stati Uniti un codice ZIP valido; gli altri paesi vengono inviati con il codice postale così come inserito. Le dimensioni (peso volumetrico) non vengono inviate. Purolator risponde in francese o in inglese, secondo la lingua del cliente. Purolator restituisce i prezzi di tutti i servizi; il modulo prende il servizio scelto o il più economico, rimuove le imposte di vendita canadesi se impostato, e converte il prezzo da CAD. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.

Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata per 10 minuti, così un'interruzione di Purolator non rallenta ogni aggiornamento del checkout. Il timeout delle API è di 10 secondi.

Se Purolator non fornisce una tariffa (API non disponibile, credenziali o codice postale errati, servizio non disponibile, nessun tasso CAD), il cliente non vede alcun errore. Si usa il prezzo fisso, oppure il corriere viene nascosto se non c'è un prezzo fisso. Il motivo viene scritto nel log.

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

Il modulo calcola solo le tariffe. Non crea spedizioni Purolator, non stampa etichette, non prenota ritiri, non gestisce resi e non traccia i pacchi. Non usa la Full Estimate (dimensioni, più colli, opzioni come firma o merci pericolose), non mostra date di consegna, non mostra più servizi come corrieri separati e non recupera automaticamente i tassi di cambio.

Ordini

Quando un ordine viene effettuato con una tariffa Purolator in tempo reale, il servizio viene salvato con l'ordine. I successivi ricalcoli del carrello non lo modificano. Nella pagina dell'ordine nel back office (Orders > Orders, apri l'ordine) un blocco Purolator mostra il Purolator service (nome e codice) e il Live rate (excl. tax). Gli ordini con prezzi fissi o con spedizione gratuita non hanno questo blocco.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Purolator è il primo blocco nella pagina Modules > Module Manager > VibeFox Purolator > 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 ci sono la riga Product: presta-shipping-purolator 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 cambiare 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 che l'indirizzo del negozio cambia, o dopo che liberi 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 Purolator non viene mostrato ai clienti nel checkout e non viene richiesta né 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 provarlo 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 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

Purolator non compare nel checkout: verifica che la licenza sia attiva e che Enable Purolator 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 Minimum order amount. Se Purolator non fornisce una tariffa, il corriere viene mostrato solo con un prezzo per paese, una riga * o un Fallback price. I prodotti possono anche essere limitati a certi corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: guarda il campo Log nella pagina del modulo. Gli errori delle API ci sono sempre. Attiva il Debug log e ricarica il checkout per i dettagli. Con le chiavi API l'indirizzo deve avere un codice postale valido (Canada) o un codice ZIP (Stati Uniti). Controlla anche gli avvisi sopra le impostazioni.

HTTP 401 nel log: la chiave o la password API non corrisponde all'ambiente selezionato. Le chiavi di sviluppo funzionano solo con Development environment attivo, quelle di produzione solo con l'opzione disattivata.

La tariffa è diversa dal sito Purolator: Quick Estimate usa le tariffe del tuo account di fatturazione e il peso totale arrotondato per eccesso a libbre intere, senza peso volumetrico. Per gli indirizzi canadesi il totale include le imposte di vendita; usa Canadian sales taxes se il corriere ha una regola fiscale. I prezzi vengono convertiti con il tuo CAD → (shop currency) rate.

Un valore è scomparso dopo il salvataggio: leggi l'avviso mostrato dopo Save. Il valore non era un numero pari o superiore a 0, quindi non è stato salvato. Inseriscilo di nuovo come numero semplice.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo svuota le tariffe Purolator in cache.

La pagina dice che il corriere Purolator 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 Purolator e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono la cronologia), e vengono rimossi le impostazioni, i servizi Purolator salvati negli ordini e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate; gli ordini effettuati mantengono il loro servizio Purolator. Reinstallando il modulo oppure con un Reset, il corriere torna allo stato che aveva prima.

Purolator è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Purolator né approvato da Purolator.