VibeFox CTT for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) oppure 4.0.2 e successivi (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Account e-commerce CTT (solo per tariffe in tempo reale e punti CTT): le tariffe in tempo reale e la consegna presso un punto CTT usano l'API e-commerce di CTT. Ti serve un account e-commerce CTT su enviosecommerce.ctt.pt (per i clienti con contratto CTT Expresso, oppure chiedi una proposta a CTT). Nella pagina di gestione delle chiavi di quell'account, crea una coppia di chiavi pubblica e privata. L'App ID (X-APPID) viene rilasciato da CTT per la tua integrazione: chiedilo al tuo referente e-commerce CTT. CTT decide anche quali funzioni API (stima dei costi, punti CTT) può usare il tuo App ID. Infine ti serve il Carrier ID di CTT nel tuo account. La pagina delle impostazioni elenca i vettori del tuo account una volta salvate le chiavi. Se usi solo la tabella dei prezzi e la consegna all'indirizzo, non ti servono chiavi API.

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

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Estrailo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_ctt-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_ctt.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, clicca su Upload e scegli il file vfd_ctt-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

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

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

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

5. Compila la tabella dei prezzi (almeno una riga Portugal o * Default), attiva Enable/Disable e/o Enable CTT point option e clicca su Save. Facoltativamente, inserisci le chiavi API di CTT, l'App ID e il Carrier ID e attiva Live rates (vedi Configurazione).

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_ctt.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 di estensione Shipping. Trova VibeFox CTT, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

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

Dopo la prima installazione, entrambe le opzioni di spedizione sono disattivate finché non ne attivi una e salvi. Se reinstalli l'estensione dopo una disinstallazione senza rimuovere i dati, vengono riutilizzate le impostazioni conservate e l'estensione viene riattivata se una delle opzioni era attiva.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox CTT > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. I prezzi e le condizioni si applicano a entrambe le opzioni CTT. Ogni salvataggio cancella le risposte CTT in cache: il token API, i vettori, i prezzi e gli elenchi dei punti CTT. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

In cima alla pagina compaiono avvisi per una tabella dei prezzi vuota, un prezzo mancante per il Portogallo, chiavi API incomplete mentre le tariffe in tempo reale o l'opzione punto CTT sono attive, un Carrier ID mancante, una valuta del negozio diversa da EUR senza tasso di cambio, una connessione all'API CTT non riuscita e un negozio senza una classe di peso con unità kg o una classe di lunghezza con unità cm (le unità dei prodotti vengono quindi convertite in base al nome dell'unità; controlla System > Localisation > Weight Classes e Length Classes). Se un nome è vuoto, non valido o supera 64 caratteri, se Min weight (kg) è maggiore di Max weight (kg), oppure se Sort Order, la classe fiscale o la zona geografica non sono validi, la pagina mostra un errore e non viene salvato nulla. Gli altri valori non validi vengono segnalati come avvisi e il resto viene salvato: un numero non valido non viene salvato, un tasso di cambio pari a 0 o inferiore viene cancellato, una dimensione del prodotto non valida torna al valore predefinito, una destinazione sconosciuta o una riga duplicata nella tabella dei prezzi viene rimossa, un prezzo di tabella non valido resta vuoto.

Generali

L'estensione offre al checkout fino a due opzioni: consegna CTT all'indirizzo del cliente e consegna presso un punto CTT o un armadietto automatico. I prezzi e le condizioni si applicano a entrambe.

Enable/Disable: attiva o disattiva la consegna CTT all'indirizzo del cliente.

Name: il nome del metodo di spedizione mostrato al cliente al checkout, ad esempio "CTT Expresso". Predefinito: CTT. Fino a 64 caratteri.

Tax class: la classe fiscale del costo di spedizione. OpenCart aggiunge questa imposta (ad esempio IVA) sui prezzi. --- None --- significa che i prezzi sono definitivi. Usata da entrambe le opzioni.

Sort Order: la posizione di CTT tra i metodi di spedizione al checkout. Un numero intero.

Consegna presso un punto CTT o un armadietto automatico

La seconda opzione CTT. Il cliente cerca i punti CTT per codice postale o città (l'indirizzo di consegna viene cercato automaticamente) e deve sceglierne uno prima di proseguire. Richiede le chiavi API di CTT e il Carrier ID. Senza di essi è un'opzione senza selezione del punto.

Enable CTT point option: offre la consegna presso un punto CTT o un armadietto automatico. Predefinito: disattivato.

CTT point option name: il nome di questa opzione al checkout. Predefinito: CTT point / parcel locker. Fino a 64 caratteri.

API e-commerce CTT (tariffe in tempo reale, punti CTT) (facoltativa; senza chiavi viene usata la tabella dei prezzi)

Public key: la chiave pubblica dalla pagina di gestione delle chiavi del tuo account e-commerce CTT.

Private key: la chiave segreta usata per firmare ogni richiesta (HMAC-SHA256). Non viene mai inviata a CTT né scritta nel log.

Entrambe le chiavi non vengono più mostrate dopo il salvataggio. La descrizione del campo dice allora Saved - leave empty to keep it. Inserisci un nuovo valore solo per modificarlo. Seleziona Remove the saved public and private key e salva per eliminare entrambe. Quando non è salvato nulla, la sezione mostra No keys saved.

App ID (X-APPID): la chiave applicativa rilasciata da CTT, inviata nell'intestazione X-APPID.

Carrier ID: l'ID del vettore CTT nel tuo account, usato per le tariffe in tempo reale e la ricerca dei punti CTT. Dopo aver salvato le chiavi e l'App ID, i vettori del tuo account vengono elencati sotto il campo (Carriers of your CTT account:), con quelli che supportano i punti CTT contrassegnati con CTT points. Solo numeri.

Live rates: chiede a CTT il prezzo (stima dei costi) non appena il cliente ha inserito via, codice postale e città. La tabella dei prezzi viene usata finché l'indirizzo è incompleto e ogni volta che CTT non fornisce un prezzo. CTT chiama questo prezzo stima. Predefinito: disattivato.

Service ID: facoltativo. Quando CTT restituisce più servizi, viene usato quello con questo ServiceId. Lascialo vuoto per usare il più economico.

Exchange rate: i prezzi CTT sono in euro. Se la valuta predefinita del tuo negozio è diversa, indica quante unità della valuta del negozio equivalgono a 1 unità della valuta CTT. Senza questo valore, le tariffe in tempo reale in un'altra valuta non vengono usate e si applica la tabella dei prezzi.

Default product size (cm): lunghezza x larghezza x altezza inviate a CTT per i prodotti senza dimensioni. Predefinito: 30x20x15. I prodotti con dimensioni usano le proprie. Le dimensioni vengono convertite in cm e i pesi in grammi in base alle classi di lunghezza e peso dei prodotti.

Prezzi (il titolo della sezione mostra la valuta predefinita del tuo negozio)

Inserisci i prezzi del tuo contratto CTT o del listino pubblico di CTT su ctt.pt, nella valuta predefinita del negozio, IVA esclusa. Con le tariffe in tempo reale disattivate, questa tabella stabilisce il prezzo. Con le tariffe in tempo reale attive, è il prezzo di riserva.

Price table: una riga per destinazione. Scegli un paese, Portugal - Azores, Portugal - Madeira o * Default (other destinations). Ogni riga ha un Price base e prezzi facoltativi per le dimensioni XS (fino a 1 kg), S (fino a 2 kg), M (fino a 3 kg), L (fino a 5 kg) e XL (oltre 5 kg). Un prezzo di dimensione vuoto (o 0) usa il prezzo base. Una riga in cui entrambi sono vuoti nasconde il metodo. La riga Azores viene usata per i codici postali portoghesi 9500-9999, la riga Madeira per 9000-9499. Senza di esse si applica la riga Portugal. Clicca su Add destination per aggiungere una riga e sul pulsante × per rimuoverla. I prezzi accettano il punto o la virgola come separatore decimale. La tabella è vuota dopo l'installazione.

Calculation: come viene determinato il prezzo della tabella.

Un prezzo CTT in tempo reale è sempre riferito all'intera spedizione.

Condizioni

Min weight (kg): il peso minimo del carrello perché le opzioni CTT compaiano. 0 significa nessun limite.

Max weight (kg): le opzioni CTT vengono nascoste sopra questo peso del carrello. Predefinito: 30 (i pacchi CTT arrivano fino a 30 kg). 0 significa nessun limite. Min weight (kg) non può essere maggiore di Max weight (kg).

Minimum order amount: mostra le opzioni CTT solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, IVA esclusa) raggiunge questo importo. Lascialo vuoto per mostrarle sempre.

Spedizione gratuita

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

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, IVA esclusa) da cui le opzioni CTT costano 0. Si applica solo alle destinazioni che hanno un prezzo. Usato solo quando Free shipping è attivo.

Disponibilità

Normalmente le opzioni CTT vengono offerte nella zona geografica selezionata qui sotto. All Zones significa ovunque. Con Ignore shipping zones la zona geografica non viene verificata e decide Countries.

Geo Zone: la zona geografica dell'indirizzo di spedizione. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: non verificare la zona geografica; offri CTT nei paesi indicati sotto.

Countries: i paesi di destinazione per quella modalità. Predefinito: Portugal. Lascialo vuoto per consentire tutti i paesi. Usato solo con Ignore shipping zones.

Avanzate

Debug log: registra il calcolo dei prezzi e le chiamate all'API CTT in storage/logs/vfd_ctt_debug.log.php (su OpenCart 4 system/storage/logs/vfd_ctt_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API CTT vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, token e indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_ctt_debug.old.log.php e si avvia un nuovo log.

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

Remove data on uninstall: quando è attivo, la disinstallazione dell'estensione elimina le impostazioni, il log e i punti CTT dei checkout non completati. Quando è disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. Gli ordini, incluso il punto CTT scelto, non vengono mai modificati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Le chiavi pubblica e privata non vengono esportate.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. Le chiavi salvate vengono mantenute.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo CTT. Con Ignore shipping zones, CTT viene offerta solo per un paese di Countries (vuoto = tutti i paesi); altrimenti, se è impostata una Geo Zone, solo per indirizzi al suo interno. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione controlla il peso del carrello e l'importo minimo dell'ordine. Con Live rates attivo e un indirizzo completo, invia a CTT l'indirizzo di consegna e, per ogni riga del carrello, la quantità, il peso in grammi e le dimensioni in cm, e usa il prezzo restituito. Altrimenti, oppure quando CTT non fornisce un prezzo (errore API, timeout, nessuna copertura, una funzione non abilitata per il tuo App ID), il prezzo proviene dalla tabella. Se si applica la spedizione gratuita, il prezzo è 0. Entrambe le opzioni ricevono lo stesso prezzo. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Un prezzo CTT viene memorizzato nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene ricordata per 5 minuti, così il checkout non attende CTT a ogni aggiornamento. Anche il token API, l'elenco dei vettori e gli elenchi dei punti CTT vengono memorizzati nella cache, al massimo per la durata della cache di OpenCart (1 ora per impostazione predefinita). Gli errori dell'API non arrivano mai al cliente: si usa il prezzo della tabella, oppure il metodo viene nascosto se la destinazione non ha un prezzo.

Con le chiavi API compilate, l'estensione invia a CTT l'indirizzo di consegna, i pesi e le dimensioni dei prodotti e l'URL del tuo negozio per ottenere un prezzo o i punti CTT più vicini.

L'estensione non crea spedizioni, non stampa etichette, non richiede ritiri, non fornisce numeri di tracciamento e non mostra una mappa dei punti CTT. Esistono una sola tabella dei prezzi e un solo set di impostazioni API per entrambe le opzioni.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione nella pagina di checkout e sceglie un'opzione CTT nella finestra Shipping method options. I prezzi sono gli stessi di OpenCart 3.

Punti di ritiro

Quando il cliente seleziona l'opzione punto CTT nel passo del metodo di consegna, sotto compaiono un campo di ricerca e un elenco. Il codice postale dell'indirizzo di consegna viene compilato e cercato automaticamente. Il cliente può cercare altri punti CTT per codice postale o città (pulsante Search) e sceglierne uno dall'elenco. La scelta viene salvata subito. Viene accettato solo un punto presente nell'elenco CTT per quella ricerca.

Un punto deve essere scelto prima che il cliente possa proseguire. Quando il cliente clicca su Continue, l'estensione verifica il punto sul server. Senza un punto, il cliente vede Please select a CTT point.; con un punto che non è nell'elenco CTT, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Se CTT non è raggiungibile, il cliente vede CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

La selezione del punto è attiva solo quando la chiave pubblica, la chiave privata, l'App ID e il Carrier ID sono compilati. È pensata per il tema predefinito di OpenCart e per il suo checkout; altri temi potrebbero richiedere modifiche.

Su OpenCart 4 il campo di ricerca e l'elenco compaiono nella finestra Shipping method options, sotto l'opzione punto CTT. Il pulsante Continue della finestra non procede senza un punto valido, con gli stessi messaggi. OpenCart 4 usa un solo ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo; il punto CTT dell'ordine viene aggiornato insieme ad esso.

Il punto scelto viene aggiunto al metodo di spedizione dell'ordine, ad esempio CTT point / parcel locker: .... Così il cliente lo vede nello storico ordini del proprio account e nelle email d'ordine, viene stampato sulla fattura e mostrato in Sales > Orders. La pagina di conferma dell'ordine di OpenCart non mostra il metodo di spedizione.

Nella pagina dell'ordine dell'area di amministrazione, il pannello CTT point sopra lo storico mostra il nome e l'ID del punto. Per cambiarlo, inserisci un codice postale o una città sotto Change CTT point, clicca su Search, scegli un punto e clicca su Save. La pagina mostra CTT point updated., il testo del metodo di spedizione dell'ordine viene aggiornato e si aggiunge una voce allo storico CTT point changed to: ... senza notificare il cliente. Cambiare il punto richiede il permesso di modifica degli ordini (sale/order) e le impostazioni API. Il pannello viene mostrato anche per gli ordini CTT mentre l'estensione è disattivata.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox CTT è il primo blocco nella pagina Extensions > Extensions > Shipping > VibeFox CTT > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 di essi ci sono la riga Product: opencart-shipping-ctt e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Possono cambiare la chiave solo gli utenti amministratori con il permesso di modifica per l'estensione. I testi del blocco seguono la lingua dell'area di amministrazione (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco spiega il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio o 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 dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, CTT non viene mostrata ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore collegato all'area di amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato con (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 il login dell'area di amministrazione, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'area 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 o la pagina Edit dell'area di amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

CTT non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Enable CTT point option) sia attivo. Controlla Geo Zone, oppure Ignore shipping zones e Countries. Verifica che la destinazione abbia una riga nella tabella dei prezzi (o una riga * Default), che il peso del carrello sia compreso tra Min weight e Max weight, che sia raggiunto il Minimum order amount e che i prodotti abbiano Requires Shipping impostato su Yes.

Il cliente non può scegliere un punto CTT: il selettore compare solo sotto l'opzione punto CTT, e solo quando la chiave pubblica, la chiave privata, l'App ID e il Carrier ID sono compilati. Controlla gli avvisi in cima alla pagina delle impostazioni, attiva il Debug log e guarda il campo Log nella pagina dell'estensione.

Le tariffe in tempo reale non compaiono: viene usata la tabella dei prezzi finché il cliente non inserisce via, codice postale e città. Controlla gli avvisi e il log. Una risposta "405" significa che la funzione non è abilitata per il tuo App ID: chiedilo a CTT. In un negozio che non usa l'euro, compila Exchange rate.

La connessione all'API CTT non è riuscita: l'avviso in cima alla pagina delle impostazioni mostra l'errore. Controlla le chiavi e l'App ID. L'estensione riprova automaticamente dopo alcuni minuti.

Prezzi con o senza IVA: con una Tax class selezionata, OpenCart aggiunge l'imposta sopra il prezzo. Con --- None --- il prezzo è definitivo.

I prezzi sembrano non aggiornati dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le risposte CTT in cache.

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

Per gli sviluppatori: l'indirizzo dell'API CTT può essere sostituito con l'impostazione vfd_ctt_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 CTT. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre lo stato dell'estensione, Sort Order, Tax class e Geo Zone. Le risposte CTT in cache e il token API vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono rimosse anche le impostazioni, il log e i punti CTT dei checkout che non sono mai diventati ordini. Se è disattivo, le altre impostazioni vengono mantenute e riutilizzate quando reinstalli l'estensione. I punti CTT salvati negli ordini vengono sempre conservati, e gli ordini esistenti mantengono il loro metodo e costo di spedizione.

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

CTT è un marchio di proprietà del rispettivo titolare. Questa estensione non è affiliata a CTT né approvata da CTT.