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

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 gli ambienti di sviluppo (sandbox) e 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: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova in seguito VibeFox Canada Post nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Per le tariffe in tempo reale, inserisci nome utente e password dell'API, il tuo numero cliente e il codice postale di spedizione. Se la valuta predefinita del tuo negozio non è il CAD, inserisci il tasso CAD. Compila Country prices se vuoi prezzi fissi o un'alternativa (vedi Configurazione). Clicca su Save.

All'installazione il modulo crea il corriere Canada Post con il testo del tempo di transito Canada Post parcel delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempo di transito, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

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

Se un valore non è corretto, la pagina mostra un errore e non salva nulla: un campo numerico o un prezzo in Country prices che non sia un numero uguale o superiore a 0 (ad esempio -1 o 12abc), un tasso CAD di 0, Min cart weight (kg) maggiore di Max cart weight (kg), oppure un Method title più lungo di 64 caratteri. Se l'unità di peso o di dimensione del tuo negozio non è tra quelle note al modulo, la pagina avvisa che i pesi vengono letti in kg (le dimensioni in cm). Imposta kg, g, lb o oz (cm, mm, m o in) in International > Localization, sezione Local units.

Dopo il salvataggio, la pagina mostra un avviso quando le impostazioni non possono funzionare come previsto: è compilato solo uno dei campi nome utente e password dell'API, il codice postale di spedizione non è un codice postale canadese (formato A1A 1A1), manca il tasso CAD per un negozio in un'altra valuta, oppure non ci sono né credenziali API né prezzi fissi. L'avviso indica anche cosa succede nel frattempo: vengono usati i prezzi fissi per paese, oppure il corriere viene nascosto al checkout quando la tabella Country prices è vuota.

Generali

Enable Canada Post: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato al cliente al checkout. Predefinito: Canada Post, anche quando il campo è lasciato vuoto. Fino a 64 caratteri, senza i caratteri che PrestaShop non consente nei nomi dei corrieri.

Tax: la regola fiscale che PrestaShop aggiunge al costo di spedizione, oppure No tax (non imponibile).

API Canada Post (tariffe in tempo reale)

Con nome utente e password dell'API compilati, il prezzo proviene 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 corriere viene nascosto se non ce n'è uno. La sezione rimanda al Canada Post Developer Program, dove trovi le chiavi API e il tuo numero cliente. I dettagli degli errori vanno nel registro, mai al cliente.

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

API password: la parte della chiave API dopo i due punti. Dopo il salvataggio il campo resta vuoto e mostra A password is saved. Leave empty to keep it; clear the username and save to remove both. Inserisci un nuovo valore solo se vuoi cambiarlo. La password viene salvata esattamente come inserita e non viene mai scritta nel registro.

Customer number: con un numero cliente, Canada Post restituisce le tariffe commerciali (scontate) del tuo account. Lascia vuoto per le tariffe al banco (retail). Gli spazi vengono rimossi.

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 fare test con la chiave API di sviluppo. I prezzi sono dati di prova. Disattivalo in un negozio attivo.

Ship-from postal code: il codice postale canadese da cui vengono spediti i pacchi, ad esempio K1A 0B1. Le tariffe in tempo reale lo richiedono.

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

Service to the USA: Cheapest available (predefinito), Expedited Parcel USA (USA.EP), Tracked Packet USA (USA.TP), Small Packet USA Air (USA.SP.AIR), Xpresspost USA (USA.XP) o Priority Worldwide parcel USA (USA.PW.PARCEL).

International service: Cheapest available (predefinito), International Parcel Surface (INT.IP.SURF), International Parcel Air (INT.IP.AIR), Tracked Packet International (INT.TP), Small Packet International Surface (INT.SP.SURF), Small Packet International Air (INT.SP.AIR), Xpresspost International (INT.XP) o Priority Worldwide parcel International (INT.PW.PARCEL).

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

Use Canada Post prices without GST/HST/PST: per gli indirizzi canadesi il prezzo di Canada Post include queste imposte. Attivalo quando PrestaShop aggiunge da sé l'imposta sulla spedizione (Tax sopra), così l'imposta non viene addebitata due volte.

CAD to … rate: il nome del campo mostra la valuta predefinita del tuo negozio, ad esempio CAD to USD rate. I prezzi di Canada Post sono in CAD. Se la valuta predefinita non è il CAD, inserisci quante unità della tua valuta valgono un CAD, ad esempio 0.68. Senza questo valore non vengono usate le tariffe in tempo reale. Se la valuta predefinita è il CAD, lascia il campo vuoto. Il tasso deve essere maggiore di 0. 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. I pesi dei prodotti (nell'unità di peso del tuo negozio) e le dimensioni vengono convertiti, 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 predefinita del tuo negozio, imposte escluse: 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 pari a zero usa il prezzo Base. Clicca su Add country per aggiungere una riga e sulla croce 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 riceve un prezzo fisso. Un prezzo base di 0 significa spedizione gratuita per quel paese. Una riga senza alcun prezzo non viene salvata.

Fixed price per: Order addebita il prezzo una sola volta. Item (price x 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 sotto questo peso del carrello. 0 significa nessun limite.

Max cart weight (kg): nasconde il corriere sopra questo peso del carrello. Predefinito: 25, anche quando il campo è vuoto. 0 significa nessun limite. I pacchi Canada Post possono pesare fino a 30 kg. Non può essere inferiore a Min cart weight (kg).

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti dopo gli sconti, imposte escluse) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

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

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

Disponibilità senza zone di spedizione

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

Ignore shipping zones: offre il corriere per i paesi sotto indicati, qualunque zona corrisponda. Al salvataggio il corriere viene aggiunto a tutte le zone, e anche alle zone che creerai in seguito. Quando disattivi l'opzione e salvi, le zone aggiunte dal modulo vengono rimosse e il corriere mantiene le proprie zone.

Countries: i paesi di destinazione per questa modalità. Tieni premuto Ctrl (Cmd) per selezionarne più di uno. Lascia vuoto per consentire tutti i paesi attivi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra i calcoli delle tariffe in var/logs/vfd_canada_post.log.php. Il file non può essere aperto dal web ed è ruotato a 5 MB. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi API, numeri cliente e codici postali dei clienti non vengono registrati.

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni, i servizi salvati degli ordini, le tariffe in cache e il registro. Il corriere viene sempre rimosso dal checkout alla disinstallazione. Gli ordini non vengono mai modificati.

Log: il pannello sotto le impostazioni mostra il nome del file e le ultime 50 voci. Clicca su Clear log per eliminarlo.

Come funziona al checkout

Al passaggio di spedizione PrestaShop chiede al modulo il prezzo di Canada Post. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica 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 nessuna richiesta a Canada Post.

Con le credenziali API, il modulo 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 modulo sceglie il servizio selezionato per il gruppo di destinazione oppure quello più economico, rimuove le imposte sulle vendite canadesi (GST/HST/PST) se Use Canada Post prices without GST/HST/PST è attivo, e converte il prezzo in CAD con il tuo tasso. Il prezzo viene calcolato nella valuta predefinita del tuo negozio e poi mostrato nella valuta del carrello del cliente.

Ogni risposta viene memorizzata nella cache per 1 ora, così lo stesso carrello e lo stesso indirizzo non generano una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache 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 corriere viene nascosto quando non c'è un prezzo fisso. Il cliente non vede mai i dettagli degli errori dell'API; vanno nel registro.

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

Il modulo 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, opzioni di assicurazione o firma. Il carrello viene sempre calcolato come un unico pacco, e i tassi di cambio non vengono aggiornati automaticamente.

Ordini

Quando un ordine viene effettuato con il corriere Canada Post, il modulo salva come è stato calcolato il suo prezzo. Nella pagina dell'ordine nel back office (Orders > Orders, apri un ordine) un blocco Canada Post mostra:

Canada Post service: il nome e il codice del servizio di una tariffa in tempo reale, ad esempio Regular Parcel (DOM.RP).

Price source: Live rate (Canada Post Rating API), Fixed price oppure Free shipping.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Canada Post è il primo blocco di Modules > Module Manager > VibeFox Canada Post > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (ad 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-canada-post e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione di configurazione del 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, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di 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: 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 Canada Post non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il corriere viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Canada Post non compare al checkout: controlla che la licenza sia attiva e che Enable Canada Post sia attivo. 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 il paese sia consentito). Controlla i limiti di peso e Minimum order amount. Ci deve essere una tariffa: con le credenziali 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 *. Inoltre, i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il pannello Log nella pagina del modulo. Mostra il motivo: nome utente o password API mancante, 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 presente.

La tariffa è diversa da quella sul 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 di Canada Post include GST/HST/PST. I prezzi vengono convertiti con il tuo tasso CAD.

L'imposta sulla spedizione viene addebitata due volte: attiva Use Canada Post prices without GST/HST/PST, oppure imposta Tax su No tax.

Verificare i prezzi in un negozio attivo: disattiva Sandbox e usa la chiave API di produzione.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le tariffe Canada Post in cache.

La pagina indica che manca il corriere Canada Post: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per crearlo di nuovo.

Non hai l'autorizzazione per configurare questo modulo: il tuo profilo dipendente può aprire la pagina del modulo ma non salvarla. Chiedi a un amministratore di dare al tuo profilo l'autorizzazione di configurazione del modulo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Canada Post e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Il corriere viene sempre rimosso dal checkout (gli ordini conservano il loro corriere e la cronologia). Se Remove data on uninstall è attivo, vengono eliminati le impostazioni, i servizi salvati degli ordini, le tariffe in cache e il registro. Se è disattivo, vengono rimosse solo le tariffe in cache e tutte le impostazioni vengono mantenute. Reinstallare il modulo (o usare Reset) ripristina il corriere precedente con il suo stato precedente: un corriere che avevi disattivato resta disattivato.

Canada Post è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da Canada Post.