VibeFox Canada Post for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Canada Post Developer Program (solo per le tariffe in tempo reale): le tariffe in tempo reale usano la Canada Post Rating API. 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: acquistata 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_canada_post-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_canada_post.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_canada_post-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer puoi copiare il contenuto della cartella upload del pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Canada Post e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

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

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 predefinita del negozio non è CAD, inserisci il tasso in CAD. Compila Country prices se vuoi prezzi fissi o un prezzo di riserva (vedi Configurazione). Attiva Enable Canada Post e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_canada_post.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. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo Shipping. Trova VibeFox Canada Post, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable Canada Post e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni che avevi conservato.

Configurazione

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

Se un valore è errato, la pagina mostra un errore e non salva nulla: un campo numerico o un prezzo in Country prices che non è un numero pari o superiore a 0 (per esempio -1 o 12abc), un tasso CAD pari a 0, Min cart weight (kg) maggiore di Max cart weight (kg), un Method title più lungo di 64 caratteri o con i caratteri < > ; = # { }, un Sort order che non è un numero intero, oppure una classe fiscale o una zona geografica sconosciute. Se il negozio non ha una classe di peso con l'unità "kg" né una classe di lunghezza con l'unità "cm", la pagina avvisa che pesi e dimensioni vengono convertiti in base al nome dell'unità della loro classe (kg, g, lb, oz; cm, mm, m, in), e che le altre unità vengono lette come kg o cm.

Dopo il salvataggio, la pagina mostra un avviso quando le impostazioni non possono funzionare come previsto: è compilato solo uno tra nome utente e password 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: si usano i prezzi fissi per paese, oppure il metodo viene nascosto al checkout quando la tabella Country prices è vuota.

Generali

Le impostazioni si applicano a ogni zona geografica. Il prezzo proviene sempre da questa estensione: una tariffa Canada Post in tempo reale oppure i prezzi fissi per paese.

Enable Canada Post: mostra o nasconde Canada Post al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Canada Post, anche se il campo è vuoto. Massimo 64 caratteri.

Tax class: la classe fiscale che OpenCart aggiunge al costo di spedizione, oppure No tax (non imponibile).

Sort order: la posizione di Canada Post tra i metodi di spedizione al checkout.

API Canada Post (tariffe in tempo reale)

Con nome utente e password API compilati, il prezzo proviene dalla Canada Post Rating API. Se l'API non restituisce alcuna 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. La sezione rimanda al Canada Post Developer Program, dove trovi le chiavi API e il tuo numero cliente. I dettagli degli errori vanno nel log, 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 su un negozio reale.

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 API username and save to remove both. Inserisci un nuovo valore solo per modificarla. La password viene salvata esattamente come digitata e non viene mai scritta nel log.

Customer number: con un numero cliente, Canada Post restituisce le tariffe commerciali (scontate) del tuo account. Lascialo vuoto per le tariffe da banco (al dettaglio). 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 test con la chiave API di sviluppo. I prezzi sono dati di prova. Disattivalo su un negozio reale. Predefinito: disattivato.

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

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

Service to the USA: il più economico disponibile (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: il più economico disponibile (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, si usa il più economico disponibile.

Use Canada Post prices without GST/HST/PST: per gli indirizzi canadesi il prezzo di Canada Post include queste tasse. Attivalo quando OpenCart aggiunge da solo la tassa sulla spedizione (Tax class sopra), così la tassa non viene addebitata due volte.

CAD to … rate: il nome del campo mostra la valuta predefinita del tuo negozio, per esempio CAD to USD rate. I prezzi di Canada Post sono in CAD. Se la valuta predefinita 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 predefinita è CAD, lascialo vuoto. Il tasso deve essere maggiore di 0.

Default product weight (kg): inviato a Canada Post per ogni prodotto senza peso. Predefinito: 0.5. Pesi e dimensioni dei prodotti vengono convertiti dalle loro classi di peso e di lunghezza, e il carrello viene calcolato come un unico pacco (fino a 30 kg).

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

Country prices: una tabella di paesi con un prezzo Base e prezzi in base al peso del carrello, nella valuta predefinita del negozio e senza tasse: 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 0 usa il prezzo Base. Clicca su Add country per aggiungere una riga. La riga * All other countries imposta i prezzi per tutti i paesi senza 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 (predefinito) 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 vengono sempre calcolate per l'intero pacco.

Condizioni

Min cart weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).

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

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, senza tasse) 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 dei prodotti che richiedono spedizione (dopo il coupon, senza tasse) a partire dal quale la spedizione è gratuita. In quel caso non viene inviata alcuna richiesta all'API. Usato solo quando Free shipping è attivo.

Geo zone: offre Canada Post solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa ovunque. Non usato quando Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Disponibilità senza zone di spedizione

Normalmente il metodo viene offerto nella zona geografica selezionata in Conditions.

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

Countries: i paesi di destinazione per quella modalità. Lascia vuoto per consentire tutti i paesi attivi del negozio. Usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_canada_post.log.php. Il file non può essere letto dal web. Quando raggiunge 5 MB viene spostato in vfd_canada_post.old.log.php e ne viene avviato uno nuovo. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Chiavi API, numeri cliente e codici postali dei clienti non vengono registrati.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni, i servizi salvati degli ordini, le tariffe in cache e il log. Se disattivo (predefinito), vengono conservati per una reinstallazione. Gli ordini non vengono mai toccati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La password API non viene esportata.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un salvataggio normale. La password API salvata viene mantenuta finché il nome utente API resta compilato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Canada Post. Se è impostata una Geo zone (e Ignore shipping zones è disattivo) e l'indirizzo è fuori da essa, Canada Post non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nell'importo dell'ordine. L'estensione controlla 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 spedizione, dopo lo sconto del coupon e prima delle tasse. Buoni regalo, punti premio e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Canada Post.

Con le credenziali API, l'estensione 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. L'estensione sceglie il servizio selezionato per il gruppo di destinazione oppure il più economico, rimuove le tasse sulle vendite canadesi se Use Canada Post prices without GST/HST/PST è attivo, e converte il prezzo da CAD con il tuo tasso. Il prezzo viene calcolato nella valuta predefinita, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con la tassa della Tax class selezionata.

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 alcuna tariffa, si usa il prezzo fisso, oppure il metodo viene nascosto se non c'è un prezzo fisso. Il cliente non vede mai i dettagli degli errori API; vanno nel log.

L'estensione 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.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione nella pagina del checkout e sceglie Canada Post nella finestra Shipping method options, per esempio Canada Post - $12.50. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con Canada Post, l'estensione salva come è stato calcolato il suo prezzo. Nella pagina dell'ordine nel pannello di amministrazione (Sales > 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, per esempio Regular Parcel (DOM.RP).

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

Su OpenCart 4 il blocco compare sopra History. Il checkout conserva un solo ordine: quando il cliente conferma di nuovo l'ordine, il servizio e la fonte del prezzo salvati vengono sostituiti, e vengono rimossi se il cliente ha scelto un altro metodo di spedizione.

Il servizio non viene aggiunto alle email degli ordini né alla pagina ordini del cliente; queste mostrano il nome del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Canada Post è il primo blocco di Extensions > Extensions > Shipping > VibeFox Canada Post > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, 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: opencart-shipping-canada-post 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 questa estensione possono cambiare la chiave. I testi del blocco seguono la lingua del pannello di 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 o License expired on con una data. Dopo aver cambiato l'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, 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, Canada Post non viene mostrato ai clienti al checkout e non viene 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 come (unlicensed — visible to admins only), così puoi configurare e testare 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 supporto 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 nei 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

Canada Post non compare al checkout: verifica che la licenza sia attiva e che Enable Canada Post sia attivo. Controlla la Geo zone, oppure che Ignore shipping zones sia attivo e il paese sia consentito. Controlla i limiti di peso e il Minimum order amount, e che i prodotti abbiano Requires Shipping impostato su Yes. Deve esserci una tariffa: con le credenziali API l'indirizzo richiede 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 guarda il campo Log nella pagina dell'estensione. 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 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 da banco (al dettaglio). Per gli indirizzi canadesi il prezzo di Canada Post include GST/HST/PST. I prezzi vengono convertiti con il tuo tasso CAD.

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

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

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota la cache delle tariffe Canada Post.

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

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Canada Post. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Canada Post, 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, i servizi salvati degli ordini e il log. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla reinstallazione dell'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Canada Post nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Canada Post è un marchio del rispettivo proprietario. Questa estensione non è affiliata né approvata da Canada Post.