VibeFox Canada Post 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.

Canada Post Developer Program (solo per le tariffe in tempo reale): le tariffe in tempo reale usano la Rating API di Canada Post. Iscriviti al Canada Post Developer Program sul sito di Canada Post e copia la tua chiave API e il tuo numero cliente. La chiave API ha la forma username:password, e Canada Post fornisce chiavi separate per l'ambiente di sviluppo (sandbox) e per quello di produzione. Ti serve anche 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_canada_post in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Canada Post, 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 inserisci nome utente e password API, il tuo numero cliente e il codice postale di spedizione. Se la valuta del negozio non è CAD, inserisci il tasso CAD. Compila Country prices se vuoi prezzi fissi o un'alternativa (vedi Configurazione).

6. Aggiungi VibeFox Canada Post alle tue zone 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 Canada Post. 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 mostrato al cliente per questa zona. Lascialo vuoto per usare il Method title globale.

Ogni volta che salvi le impostazioni, le tariffe Canada Post in cache vengono cancellate. La pagina mostra anche un errore quando le impostazioni non possono funzionare: è compilato solo uno tra nome utente e password API, il codice postale di spedizione non è canadese, manca il tasso CAD per un negozio con un'altra valuta, oppure non ci sono né chiavi API né prezzi fissi.

Generale

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

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: Canada Post. Una zona può usare un proprio titolo.

Tax status: Taxable aggiunge l'imposta WooCommerce al costo di spedizione, None non la aggiunge.

API Canada Post (tariffe in tempo reale)

Con nome utente e password API compilati, il prezzo viene dalla Rating API di Canada Post. Se l'API non restituisce una tariffa (API non disponibile, codice postale errato, servizio non disponibile), si usa il prezzo fisso di Country prices, oppure il metodo viene nascosto se non ce n'è uno.

API username: la parte della chiave API prima dei due punti. Usa la chiave di sviluppo con Sandbox e la chiave di produzione su un negozio reale.

API password: la parte della chiave API dopo i due punti. Non viene mai scritta nel registro.

Customer number: con un numero cliente, Canada Post restituisce le tariffe commerciali (scontate) del tuo account. Lascialo vuoto per le tariffe al banco.

Contract number: facoltativo, per i clienti con contratto. Viene usato solo insieme al numero cliente.

Sandbox: usa l'ambiente di sviluppo di Canada Post, per testare con la chiave API 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 K1A 0B1. Le tariffe in tempo reale ne hanno bisogno.

Service in Canada: il servizio per gli indirizzi canadesi: Cheapest available, Regular Parcel (predefinito), Expedited Parcel, Xpresspost o Priority.

Service to the USA: Cheapest available (predefinito), Expedited Parcel USA, Tracked Packet USA, Small Packet USA Air, Xpresspost USA o Priority Worldwide parcel USA.

International service: Cheapest available (predefinito), International Parcel Surface, International Parcel Air, Tracked Packet International, Small Packet International Surface, Small Packet International Air, Xpresspost International o Priority Worldwide parcel International.

Se il servizio scelto non è offerto per l'indirizzo o il pacco, viene usato il servizio disponibile più economico.

Canadian sales taxes: usa i prezzi Canada Post senza GST/HST/PST. Per gli indirizzi canadesi il prezzo Canada Post include queste imposte. Attivalo quando WooCommerce aggiunge l'imposta sulla spedizione (Tax status = Taxable), così l'imposta non viene addebitata due volte.

CAD → store currency rate: il nome del campo mostra la valuta del tuo negozio. I prezzi Canada Post sono in CAD. Se la valuta del negozio non è CAD, inserisci quante unità della tua valuta vale un CAD, per esempio 0.68. Senza questo valore le tariffe in tempo reale non vengono usate. Se la valuta del negozio è CAD, lascia il campo vuoto. Sono accettati sia il punto sia la virgola come separatore decimale.

Default product weight (kg): inviato a Canada Post per ogni prodotto senza peso. Predefinito: 0.5. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del tuo negozio, e il carrello viene calcolato come un unico pacco.

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

Country prices: una tabella di paesi con un prezzo Base e prezzi in base al peso del carrello nella valuta del negozio: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL oltre 5 kg. Un prezzo di taglia vuoto o zero usa il prezzo Base. Fai clic su Add country per aggiungere una riga e sulla × per rimuoverne una. La riga * Default (all other countries) imposta i prezzi per tutti i paesi che non hanno una riga propria. Un paese senza riga (e senza *) non ha un prezzo fisso. Un prezzo base di 0 significa spedizione gratuita per quel paese.

Fixed price per: Order 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.

Max cart weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite. I pacchi Canada Post possono pesare fino a 30 kg.

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 se un articolo del carrello ha una di queste classi di spedizione WooCommerce.

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

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. In quel caso non viene fatta nessuna richiesta all'API.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati sotto, indipendentemente dalla zona corrispondente.

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

Avanzate

Debug log: registra i calcoli delle tariffe in WooCommerce > Status > Logs, origine vfd-canada-post. Gli errori API vengono sempre registrati, anche quando l'opzione è disattivata. Chiavi API, numeri cliente e codici postali dei clienti non vengono registrati.

Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse le sue impostazioni, i metodi delle zone e le tariffe in cache. La disattivazione del plugin non elimina 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: peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente ottiene una tariffa gratuita e non viene inviata nessuna richiesta a Canada Post.

Con le chiavi API, il plugin invia a Canada Post il codice postale di spedizione, la destinazione, il peso del pacco e, quando tutti i prodotti hanno le dimensioni, la dimensione stimata del pacco. Per il Canada la destinazione è il codice postale, per gli Stati Uniti il codice ZIP, per tutti gli altri paesi solo il paese. Una tariffa in tempo reale viene richiesta solo quando un indirizzo canadese o statunitense ha un codice postale o ZIP valido. Canada Post restituisce tutti i servizi per il pacco; il plugin sceglie il servizio selezionato per il gruppo di destinazione o il più economico, rimuove le imposte di vendita canadesi se Canadian sales taxes è attivo, e converte il prezzo in CAD con il tuo tasso. Il nome del servizio viene salvato con l'ordine e mostrato nella schermata dell'ordine in amministrazione come Canada Post service.

Ogni risposta viene memorizzata in cache per 1 ora, così lo stesso carrello e lo stesso indirizzo non generano una nuova richiesta. Una richiesta non riuscita viene memorizzata per 10 minuti, così un'interruzione di Canada Post non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi. I pacchi oltre 30 kg non vengono inviati all'API.

Se l'API non restituisce una tariffa, si usa il prezzo fisso, oppure il metodo viene nascosto quando non c'è un prezzo fisso. Il cliente non vede mai i dettagli degli errori API; finiscono nel registro di WooCommerce.

Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con High-Performance Order Storage (HPOS) di WooCommerce.

Il plugin calcola solo le tariffe. Non crea spedizioni, non stampa etichette, non crea distinte o resi e non traccia i pacchi. I clienti non possono scegliere un ufficio postale o un punto di ritiro. Mostra una sola tariffa Canada Post, senza date di consegna, assicurazione o opzioni di firma. Il carrello viene sempre calcolato come un unico pacco, e i tassi di cambio non vengono aggiornati automaticamente.

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 Canada Post. 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 solo dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Canada Post non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi continuano a vederlo, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

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

Risoluzione dei problemi

Canada Post non compare al checkout: controlla 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 consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. Deve esserci una tariffa: con le chiavi API l'indirizzo deve avere un codice postale valido (Canada) o un codice ZIP (Stati Uniti); altrimenti deve esistere un prezzo fisso per il paese o per *.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-canada-post. Mostra il motivo: nome utente o password API mancanti, codice postale di spedizione o di destinazione non valido, tasso CAD mancante, pacco oltre 30 kg, oppure il messaggio di errore di Canada Post. Nel frattempo i clienti ricevono il prezzo fisso, se esiste.

La tariffa è diversa da quella del sito di Canada Post: con un numero cliente ottieni le tariffe commerciali (scontate) del tuo account; senza, le tariffe al banco. Per gli indirizzi canadesi il prezzo Canada Post include GST/HST/PST. I prezzi vengono convertiti con il tuo tasso CAD.

L'imposta sulla spedizione viene addebitata due volte: attiva Canadian sales taxes, oppure imposta Tax status su None.

Verifica i prezzi su un negozio reale: disattiva Sandbox e usa la chiave API di produzione.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe Canada Post 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 conserva 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 futura reinstallazione. Gli ordini non vengono mai toccati.

Canada Post è un marchio registrato del suo rispettivo proprietario. Questo plugin non è affiliato né approvato da Canada Post.