VibeFox Purolator for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo, con l'estensione cURL. 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

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_purolator-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_purolator.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. Nell'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_purolator-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Purolator e fai clic su Install (il pulsante verde +).

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

4. Inserisci la chiave di licenza VibeFox in License key, nel blocco di licenza in alto nella pagina Edit, e fai clic su Activate (vedi Chiave di licenza).

5. Per le tariffe in tempo reale compila la sezione Purolator API (live rates): chiave API, password, numero dell'account di fatturazione, codice postale canadese di spedizione e, se la valuta del negozio non è il CAD, il tasso CAD. Per i test attiva Development environment con la chiave di sviluppo. Compila Country prices o Fallback price se vuoi prezzi fissi o un ripiego (vedi Configurazione). Attiva Enable Purolator e fai clic su Save.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_purolator.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 Purolator, 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 è disattivato finché non attivi Enable Purolator e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Purolator che avevi conservato.

Configurazione

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

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, nella sezione General compare un avviso. Indica anche se nel frattempo vengono usati i prezzi fissi o se il metodo è nascosto. Un avviso compare anche se l'unità di peso del negozio non è una che l'estensione conosce. In tal caso i pesi dei prodotti vengono letti come kg; aggiungi una classe di peso con l'unità kg in System > Localisation > Weight Classes.

Un campo numerico che non contiene un numero pari o superiore a 0 non viene salvato. Un messaggio dopo Save indica il campo e il valore. Il campo resta vuoto, oppure assume il valore predefinito nei campi del peso. Un valore errato in Country prices viene salvato come 0, e il messaggio indica il paese e la colonna. Non viene salvato nulla e compare un errore se il titolo del metodo è vuoto o supera i 64 caratteri, se Min cart weight (kg) è maggiore di Max cart weight (kg), se l'ordine di visualizzazione non è un numero intero, o se la classe fiscale o la zona geografica non sono valide.

Generale

Il cliente vede un'unica tariffa Purolator. Le impostazioni valgono per ogni zona geografica. Puoi limitare il metodo a una zona geografica o a paesi in Availability.

Enable Purolator: mostra o nasconde Purolator al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Purolator. Obbligatorio, massimo 64 caratteri.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Decide se il negozio aggiunge un'imposta sopra il prezzo. Per gli indirizzi canadesi il totale Purolator include già GST/HST/PST/QST. Vedi più avanti Canadian sales taxes.

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

API Purolator (tariffe in tempo reale)

Con chiave API, password e account di fatturazione compilati, il prezzo proviene dal servizio web Purolator E-Ship Estimating (Quick Estimate, in base al peso totale del carrello). Se Purolator non restituisce una tariffa, si usa il prezzo fisso, oppure il metodo 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. I dettagli degli errori vanno nel registro, mai al cliente.

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 nuovo valore solo se vuoi cambiarla.

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

Billing account number: il numero del tuo 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 API e la password salvate.

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

Ship-from postal code: il codice postale canadese da cui vengono spediti i pacchi, per esempio L4W 5M8. OpenCart non ha un codice postale del negozio, quindi non viene preso dall'indirizzo del negozio: inseriscilo qui.

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, viene usato 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 negozio aggiunge da sé un'imposta sulla spedizione (una classe fiscale in General), così l'imposta non viene addebitata due volte. Predefinito: disattivato.

CAD → (store 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, lascialo vuoto.

Default product weight (kg): usato per ogni prodotto senza peso. Predefinito: 0.5. I pesi vengono convertiti dalla classe di peso del prodotto e inviati a Purolator come peso totale in libbre intere, arrotondato per eccesso.

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

Country prices: un prezzo per paese e peso del carrello nella valuta predefinita del negozio, IVA esclusa. Fai clic su Add country per aggiungere una riga e sul pulsante × per rimuoverla. 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 da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 5 kg e XL oltre 5 kg. Un prezzo di dimensione vuoto o pari a zero usa Base. Un Base di 0, o un Base vuoto, significa spedizione gratuita per i pesi senza un proprio prezzo di dimensione. Sono accettati sia 9.99 sia 9,99. Le righe senza alcun prezzo non vengono salvate, e per ogni paese viene mantenuta 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 metodo in quei paesi.

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

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: 30. Se lo lasci vuoto, vengono usati 30 kg. 0 significa nessun limite.

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

Free shipping from: il subtotale dei prodotti che richiedono la spedizione (dopo il coupon, prima delle imposte) a partire dal quale la consegna è gratuita. In tal caso non viene inviata alcuna richiesta a Purolator. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità

Geo zone: offre Purolator 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 verificata quando Ignore shipping zones è attivo.

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

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

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_prlr_debug.log.php (su OpenCart 4 system/storage/logs/vfd_prlr_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati, anche con il registro di debug disattivato. Chiavi API, account di fatturazione e codici postali dei clienti non vengono registrati. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_prlr_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni Purolator e il registro. Se disattivo, vengono conservati per una reinstallazione. Le tariffe in cache vengono sempre rimosse. Il servizio Purolator degli ordini effettuati viene sempre conservato.

Importazione / Esportazione

Export: fai clic su Download JSON per salvare le impostazioni in un file JSON. Chiave API e password non vengono esportate.

Import: incolla il JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. La chiave API e la password salvate vengono mantenute.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Purolator. Se è impostata una Geo zone e l'indirizzo è al di fuori, Purolator non viene offerto (a meno che Ignore shipping zones sia attivo). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nell'importo dell'ordine. L'estensione verifica prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono la 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 Purolator. Altrimenti cerca un prezzo: prima la tariffa in tempo reale di Purolator, poi la tabella per paese, poi il prezzo di ripiego. Se non c'è alcun prezzo, il metodo viene nascosto.

Con le credenziali API, l'estensione 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 del cliente, 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 quando il cliente visualizza il negozio in francese, altrimenti in inglese. Purolator restituisce i prezzi di tutti i servizi; l'estensione prende il servizio scelto o il più economico, rimuove le imposte sulle vendite canadesi se impostato, e converte il prezzo dai CAD. Il prezzo viene calcolato nella valuta predefinita, arrotondato alle sue decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta 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ì un'interruzione di Purolator non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi.

Se Purolator non restituisce 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 metodo viene nascosto se non c'è un prezzo fisso. Il motivo viene scritto nel registro.

L'estensione 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 presenta più servizi come opzioni separate e non recupera automaticamente i tassi di cambio. Il cliente non vede il nome del servizio Purolator, solo il titolo del tuo metodo.

Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Purolator nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con una tariffa Purolator in tempo reale, il servizio viene salvato con l'ordine. In Sales > Orders la pagina dell'ordine mostra sopra la cronologia un pannello Purolator con il Purolator service (nome e codice) e la Live rate (excl. tax). Il pannello resta visibile anche se il metodo viene disattivato in seguito. Gli ordini prezzati con i prezzi fissi o con spedizione gratuita non hanno questo pannello. L'ordine stesso mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart.

OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo. Il servizio Purolator salvato viene aggiornato insieme ad esso all'ultima tariffa in tempo reale. Se l'ordine passa a un altro metodo di spedizione o a un prezzo senza tariffa in tempo reale, il servizio salvato viene rimosso dall'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Purolator è il primo blocco in Extensions > Extensions > Shipping > VibeFox Purolator > Edit, sopra le impostazioni. Incolla la chiave in License key e fai clic 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-purolator 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 cambiare la chiave. I testi del blocco seguono la lingua dell'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 il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione Purolator non viene mostrato ai clienti al checkout e non viene richiesta né 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

Purolator non compare al checkout: verifica che la licenza sia attiva e che Enable Purolator sia attivo. Controlla la Geo zone (o che Ignore shipping zones sia attivo e il paese consentito), i limiti di peso e il Minimum order amount. Se Purolator non restituisce una tariffa, il metodo viene mostrato solo con un prezzo per paese, una riga * o un Fallback price. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: guarda il campo Log nella pagina dell'estensione. Gli errori dell'API sono sempre lì. 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 valido (Stati Uniti). Controlla anche gli avvisi nella sezione General.

HTTP 401 nel registro: la chiave API o la password non corrispondono all'ambiente selezionato. Le chiavi di sviluppo funzionano solo con Development environment attivo, quelle di produzione solo con esso disattivo.

La tariffa non corrisponde al sito Purolator: la 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 sulle vendite; usa Canadian sales taxes se hai impostato una Tax class. I prezzi vengono convertiti con il tuo CAD → (store currency) rate.

Un valore è scomparso dopo il salvataggio: leggi il messaggio 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 dell'estensione. Questo svuota le tariffe Purolator in cache.

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

Per gli sviluppatori: l'indirizzo dell'API Purolator può essere sostituito con l'impostazione vfd_prlr_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox Purolator. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart reimposta sempre Enable Purolator, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni Purolator e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti conservano il loro metodo di spedizione e il costo, e i servizi Purolator salvati negli ordini vengono sempre conservati.

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 Purolator nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Purolator è un marchio del rispettivo proprietario. Questa estensione non è affiliata a Purolator né approvata da Purolator.