VibeFox Purolator for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo. 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 ti servono chiavi API.

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_purolator in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Purolator, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. 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).

6. Aggiungi VibeFox Purolator a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Purolator. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome che il cliente vede per questa zona. Lascialo vuoto per usare il Method title globale.

Ogni volta che salvi le impostazioni, le tariffe Purolator in cache vengono cancellate. Se le tariffe in tempo reale non possono funzionare con i valori salvati (chiave, password o account 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.

Generali

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Method title: il nome del metodo di spedizione mostrato nel carrello e nel checkout. Una zona può sovrascriverlo. Predefinito: Purolator.

Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non l'aggiunge. Vedi anche Canadian sales taxes più sotto.

API Purolator (tariffe in tempo reale)

Con chiave API, password e account di fatturazione compilati, il prezzo proviene dal web service Purolator E-Ship Estimating. Se Purolator non fornisce una tariffa, si usa il prezzo fisso, oppure il metodo viene nascosto se non ce n'è uno.

API key: la tua chiave E-Ship Web Services per l'ambiente selezionato.

API password: la password associata alla chiave.

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 indicato nella documentazione Purolator.

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 reale.

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, viene usato il più economico disponibile.

Canadian sales taxes: per gli indirizzi canadesi il totale Purolator include GST/HST/PST/QST. Attiva Use Purolator prices without GST/HST/PST/QST quando Tax status è Taxable, così l'imposta non viene addebitata due volte.

CAD → (store currency) rate: i prezzi Purolator sono in CAD. Se la valuta del tuo 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 del negozio è il CAD, lascia vuoto il campo.

Default product weight (kg): usato per ogni prodotto senza peso. Predefinito: 0.5. I pesi vengono convertiti dall'unità 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 del negozio. Fai clic su + Add country per aggiungere una riga e sulla croce 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 di 0, o un Base vuoto, significa spedizione gratuita per i pesi senza un proprio prezzo di dimensione. Le righe senza alcun prezzo e i codici paese non validi vengono rimossi al salvataggio. Viene mantenuta una sola riga per paese.

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

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

Condizioni

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

Max cart weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo quando il subtotale del carrello raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una qualsiasi di queste classi di spedizione di WooCommerce.

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. Vale solo dove il metodo ha un prezzo: un prezzo per paese o il prezzo di riserva (in tal caso non viene inviata alcuna richiesta a Purolator), oppure una tariffa in tempo reale. Lascia vuoto per non offrire mai la spedizione gratuita.

Per queste condizioni il peso del carrello conta i prodotti senza peso come 0. Prezzi e pesi accettano la virgola o il punto come separatore decimale.

Disponibilità senza zone di spedizione

Ignore shipping zones: offri Purolator per i paesi indicati sotto anche se il metodo non è aggiunto a nessuna zona di spedizione.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi in cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in WooCommerce > Status > Logs (origine «vfd-purolator»). Gli errori API vengono sempre registrati, anche con il log di debug disattivato. Le chiavi API, l'account di fatturazione e i codici postali dei clienti non vengono registrati. Disattiva il log quando hai finito.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni, i metodi di zona e le tariffe in cache. Disattivare il plugin non cancella mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Poi cerca un prezzo: la tariffa Purolator in tempo reale, quindi la tabella per paese, infine il prezzo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi.

Con le credenziali API il plugin invia a Purolator una richiesta Quick Estimate: il tuo account di fatturazione, il codice postale di partenza, la città, provincia o 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 restituisce i prezzi di tutti i servizi; il plugin prende il servizio che hai scelto o il più economico, rimuove le imposte sulle vendite canadesi se impostato e converte il prezzo da CAD. Il servizio viene salvato con l'ordine come Purolator service ed è visibile nella schermata dell'ordine nell'amministrazione.

Ogni risposta viene memorizzata nella cache per 1 ora. 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 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 metodo viene nascosto se non c'è un prezzo fisso. Il motivo viene scritto nel log.

Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

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

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Purolator. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Purolator non viene mostrato ai clienti nel checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Purolator non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso, Minimum order amount ed Excluded shipping classes. Se Purolator non fornisce una tariffa, il metodo viene mostrato solo con un prezzo per paese, una riga * o un Fallback price.

Le tariffe in tempo reale non compaiono: apri WooCommerce > Status > Logs, origine «vfd-purolator». Gli errori API ci sono sempre. Attiva Debug log per i dettagli. Con le chiavi API l'indirizzo deve avere un codice postale valido (Canada) o un codice ZIP valido (Stati Uniti).

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 da quella del sito Purolator: il 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; usa Canadian sales taxes se WooCommerce aggiunge l'imposta sulla spedizione. I prezzi vengono convertiti con il tuo CAD → (store currency) rate.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così si cancellano le tariffe Purolator in cache.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione.

Purolator è un marchio del rispettivo titolare. Questo plugin non è affiliato a Purolator né approvato da Purolator.