VibeFox CTT for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
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 a CTT una proposta). Nella pagina di gestione delle chiavi di quell'account, crea una coppia di chiavi pubblica e privata. L'App ID (X-APPID) è rilasciato da CTT per la tua integrazione: chiedilo al tuo referente e-commerce di CTT. CTT decide anche quali funzioni dell'API (stima del costo, punti CTT) può usare il tuo App ID. Infine ti serve il Carrier ID di CTT nel tuo account. La pagina delle impostazioni mostra i vettori del tuo account una volta salvate le chiavi. Se usi solo la tabella dei prezzi e la consegna a domicilio, 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_ctt in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox CTT, 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. Compila la tabella dei prezzi (almeno una riga Portugal o * Default). Facoltativamente, inserisci le chiavi API di CTT e il Carrier ID e attiva Live rates (vedi Configurazione).
6. In WooCommerce > Settings > Shipping > Shipping zones, apri o crea una zona per il Portogallo e aggiungi VibeFox CTT. Nelle impostazioni del metodo scegli il titolo e il tipo di consegna. Oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Prezzi, chiavi API e condizioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox CTT. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona contiene due campi:
Title (zone): il nome di questa opzione al checkout in questa zona. Lascialo vuoto per usare il Name globale.
Delivery: To the customer's address (predefinito) oppure To a CTT point or parcel locker chosen at checkout. Un punto CTT richiede le chiavi API di CTT e il Carrier ID nelle impostazioni globali. Aggiungi il metodo due volte a una zona per offrire fianco a fianco la consegna a domicilio e la consegna presso un punto CTT.
Gli avvisi sopra le impostazioni ti segnalano un prezzo mancante per il Portogallo, chiavi API incomplete, un Carrier ID mancante, una valuta del negozio senza tasso di cambio e una connessione non riuscita all'API di CTT. Ogni volta che salvi le impostazioni, le risposte di CTT in cache vengono cancellate.
Generale
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al checkout, per esempio "CTT Expresso". Predefinito: CTT. Il Title di una zona lo sostituisce.
Tax status: Taxable aggiunge al prezzo l'imposta sulla spedizione di WooCommerce (per esempio IVA), None significa che il prezzo è definitivo.
API e-commerce CTT (tariffe in tempo reale, punti CTT) (facoltativo; senza chiavi si usa 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.
App ID (X-APPID): la chiave applicativa rilasciata da CTT per la tua integrazione.
Carrier ID: l'ID del vettore CTT nel tuo account, usato per le tariffe in tempo reale e per la ricerca dei punti CTT. Dopo aver salvato le chiavi, i vettori del tuo account sono elencati sotto il campo, con quelli che supportano i punti CTT contrassegnati.
Live rates: chiede a CTT il prezzo (stima del costo) non appena il cliente ha inserito via, codice postale e città. Finché l'indirizzo è incompleto, o ogni volta che CTT non fornisce un prezzo, si usa la tabella dei prezzi. CTT chiama questo prezzo una 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 di CTT sono in euro. Se la valuta 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 a partire dalle unità del tuo negozio.
Prezzi (il titolo della sezione mostra la valuta del tuo negozio)
Inserisci i prezzi del tuo contratto CTT o del listino pubblico di CTT, nella valuta del negozio. 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 (PT-AC), Portugal - Madeira (PT-MA) o * Default (other destinations). Ogni riga ha un prezzo base (Price) 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 Azzorre si usa per i codici postali portoghesi 9500-9999, la riga Madeira (incluso Porto Santo) per 9000-9499. Senza di esse si applica la riga Portugal. Fai clic su + Add destination per aggiungere una riga e sulla croce per rimuoverne una. I prezzi accettano il punto o la virgola decimale. Le righe non valide vengono segnalate al salvataggio.
Calculation: come si determina il prezzo della tabella.
Una tariffa CTT in tempo reale vale sempre per la spedizione completa.
Condizioni
Min weight (kg): il peso minimo del carrello perché il metodo compaia. 0 significa nessun limite.
Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 30 (i pacchi CTT arrivano fino a 30 kg). 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo quando un articolo del carrello appartiene a una di queste classi di spedizione di WooCommerce.
Spedizione gratuita
Free shipping: attiva la consegna gratuita di CTT a partire dall'importo sotto indicato.
Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) a partire dal quale questo metodo costa 0. Vale solo dove il metodo ha un prezzo. Usato solo quando Free shipping è attivo.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre il metodo nei paesi sotto indicati quando la zona del cliente non lo contiene.
Countries: i paesi di destinazione per quella modalità. Predefinito: Portugal. Lascia vuoto per usare tutti i paesi in cui spedisci. Questo campo è usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra il calcolo dei prezzi e le chiamate all'API di CTT in WooCommerce > Status > Logs, origine vfd-ctt. Gli errori dell'API di CTT vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, token e indirizzi dei clienti non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i suoi metodi di zona. Disattivare il plugin non cancella mai dati. Gli ordini non vengono mai modificati.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin un prezzo. Il plugin controlla prima il peso del carrello, l'importo minimo dell'ordine e le classi di spedizione escluse. 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 mostra il prezzo restituito. Altrimenti, oppure quando CTT non fornisce un prezzo (errore API, timeout, nessuna copertura, funzione non attiva per il tuo App ID), il prezzo proviene dalla tabella. Se si applica la spedizione gratuita, il prezzo è 0.
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. Il timeout dell'API è di 12 secondi.
Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con High-Performance Order Storage (HPOS) di WooCommerce.
Con le chiavi API compilate, il plugin 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.
Il plugin 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 l'intero negozio. Le zone differiscono per titolo e tipo di consegna.
Punti di ritiro
Per un metodo di zona con Delivery impostato su un punto CTT, al checkout compaiono sotto il metodo un campo di ricerca e un elenco. L'indirizzo di consegna viene cercato automaticamente. Il cliente può cercare altri punti CTT per codice postale o città e deve sceglierne uno prima di effettuare l'ordine. Questo viene verificato anche lato server. Gli elenchi dei punti CTT vengono memorizzati nella cache per 6 ore. Se CTT non è raggiungibile, il cliente vede un messaggio e può riprovare più tardi oppure scegliere un altro metodo di spedizione.
Il punto scelto viene salvato nell'ordine. È mostrato nella gestione ordini sotto l'indirizzo di spedizione, nella pagina dell'ordine ricevuto, in My account > Orders e nelle e-mail degli ordini (HTML e testo semplice) come CTT point.
Nella gestione ordini, fai clic su Change accanto al punto CTT, cerca per codice postale o città e scegli un altro punto. La modifica viene salvata subito e aggiunge una nota all'ordine.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox CTT. 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, CTT non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, 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 vengono modificati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
CTT non compare al 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 consentito). Verifica che la destinazione abbia una riga nella tabella dei prezzi (o una riga * Default), che il peso del carrello rientri tra Min weight e Max weight, che sia raggiunto il Minimum order amount e che nessun prodotto appartenga a una classe di spedizione esclusa.
Il cliente non può scegliere un punto CTT: il selettore compare solo per un metodo di zona con Delivery impostato su un punto CTT, e solo quando chiave pubblica, chiave privata, App ID e Carrier ID sono compilati. Attiva il Debug log e controlla WooCommerce > Status > Logs.
Le tariffe in tempo reale non compaiono: si usa la tabella dei prezzi finché il cliente non ha inserito via, codice postale e città. Controlla gli avvisi sopra le impostazioni e il log. La risposta "405" significa che la funzione non è attiva per il tuo App ID: chiedi a CTT. In un negozio che non usa l'euro, compila Exchange rate.
La connessione all'API di CTT non è riuscita: l'avviso sopra le impostazioni mostra l'errore. Controlla le chiavi e l'App ID. Il plugin riprova automaticamente dopo qualche minuto.
Prezzi con o senza IVA: con Tax status su Taxable, WooCommerce aggiunge l'imposta di spedizione al prezzo. Con None, il prezzo è definitivo.
Il blocco della 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 sul 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, così come le risposte di CTT in cache e il token API. Impostazioni e metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano disponibili per una reinstallazione futura. Gli ordini, incluso il punto CTT scelto, non vengono mai modificati e quelli esistenti mantengono le proprie righe di spedizione.
CTT è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato né approvato da CTT.