VibeFox CTT 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.
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 questo 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 CTT. CTT decide anche quali funzioni dell'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 mostra i corrieri del tuo account dopo il salvataggio delle 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 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 cerca VibeFox CTT più tardi 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. Compila la tabella dei prezzi (almeno una riga Portugal o * Default) e clicca su Save. Facoltativamente, compila le chiavi API di CTT e il Carrier ID, poi attiva Live rates e Enable CTT point carrier (vedi Configurazione).
All'installazione il modulo crea due corrieri. CTT (consegna all'indirizzo del cliente, testo del tempo di consegna CTT delivery to your address) è attivo. CTT point / parcel locker (testo del tempo di consegna Pickup at a CTT point or parcel locker) è disattivo finché non lo attivi. Entrambi sono collegati alla zona Portogallo e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempo di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox CTT > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. I prezzi e le condizioni valgono per entrambi i corrieri CTT. Ogni salvataggio cancella le risposte CTT in cache, compresi il token API e gli elenchi dei punti CTT.
Gli avvisi sopra le impostazioni segnalano una tabella dei prezzi vuota, un prezzo mancante per il Portogallo, chiavi API incomplete, un Carrier ID mancante, una valuta del negozio diversa da EUR senza un tasso di cambio, un errore di connessione all'API di CTT e un corriere CTT eliminato. I valori non validi vengono segnalati al salvataggio: un numero non valido non viene salvato, una destinazione sconosciuta o una riga duplicata nella tabella dei prezzi viene rimossa. Se l'unità di peso o di dimensione del tuo negozio non è riconosciuta dal modulo, un avviso ti chiede di impostare le unità in International > Localization (Local units).
Generale
Enable/Disable: attiva o disattiva la consegna CTT all'indirizzo del cliente. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del corriere mostrato al cliente al checkout, per esempio "CTT Expresso". Predefinito: CTT. Obbligatorio, fino a 64 caratteri.
Tax status: None significa che i prezzi sono definitivi. Taxable con una regola fiscale significa che PrestaShop aggiunge quella tassa di spedizione (per esempio IVA) sopra i prezzi. La scelta viene salvata per entrambi i corrieri CTT.
Consegna presso un punto CTT o armadietto automatico
Il secondo corriere CTT. Il cliente cerca i punti CTT per codice postale o città e deve sceglierne uno prima di proseguire. Richiede le chiavi API di CTT e il Carrier ID. Senza di essi è un corriere senza selezione del punto.
Enable CTT point carrier: attiva o disattiva il corriere dei punti CTT. È lo stesso interruttore del suo stato in Shipping > Carriers. Predefinito: disattivo.
CTT point carrier name: il nome di questa opzione al checkout. Predefinito: CTT point / parcel locker. Obbligatorio, fino a 64 caratteri.
API e-commerce CTT (tariffe in tempo reale, punti CTT) (facoltativo; senza chiavi viene usata la tabella dei prezzi)
Public key: la chiave pubblica della 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 indica allora Saved - leave empty to keep it. Inserisci un nuovo valore solo per modificarle. Spunta Remove the saved public and private key e salva per eliminarle entrambe.
App ID (X-APPID): la chiave dell'applicazione rilasciata da CTT, inviata nell'intestazione X-APPID.
Carrier ID: l'ID del corriere CTT nel tuo account, usato per le tariffe in tempo reale e la ricerca dei punti CTT. Dopo il salvataggio delle chiavi e dell'App ID, i corrieri del tuo account vengono elencati sotto il campo, con quelli che supportano i punti CTT contrassegnati con (CTT points). Solo numeri.
Live rates: il modulo 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 una stima. Predefinito: disattivo.
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 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 a partire dalle unità del tuo negozio.
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, al netto delle imposte. Con le tariffe in tempo reale disattivate, questa tabella determina 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 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 i campi sono vuoti nasconde il corriere. La riga Azores si usa per i codici postali portoghesi 9500-9999, la riga Madeira (compreso Porto Santo) per 9000-9499. Senza di esse si applica la riga Portugal. Clicca su Add destination per aggiungere una riga e sull'icona del cestino per rimuoverne una. I prezzi accettano il punto o la virgola decimale. La tabella è vuota dopo l'installazione.
Calculation: come si trova il prezzo della tabella.
Una tariffa CTT in tempo reale vale sempre per l'intera spedizione.
Condizioni
Min weight (kg): il peso minimo del carrello perché i corrieri compaiano. 0 significa nessun limite.
Max weight (kg): i corrieri sono nascosti 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): le impostazioni non vengono salvate.
Minimum order amount: mostra i corrieri solo quando il subtotale del carrello (prodotti da spedire, dopo sconti, prima delle imposte) raggiunge questo importo. Lascia vuoto per mostrarli sempre.
Spedizione gratuita
Free shipping: attiva la consegna CTT gratuita a partire dall'importo indicato sotto.
Free shipping from: il subtotale del carrello (dopo sconti, prima delle imposte) a partire dal quale i corrieri costano 0. Vale solo per le destinazioni che hanno un prezzo. Usato solo quando Free shipping è attivo.
Disponibilità senza zone di spedizione
Normalmente i corrieri sono offerti nelle zone di spedizione a cui sono collegati in Shipping > Carriers.
Ignore shipping zones: offre i corrieri nei paesi indicati sotto senza collegarli alla loro zona. Quando lo attivi, entrambi i corrieri vengono collegati a tutte le zone attive (anche a quelle che creerai in seguito). Quando lo disattivi, riottengono le zone che avevano prima.
Countries: i paesi di destinazione per questa modalità. Predefinito: Portugal. Lascia vuoto per consentire tutti i paesi. Usato solo quando Ignore shipping zones è attivo. I clienti delle zone che i corrieri avevano prima vengono sempre serviti.
Avanzate
Debug log: registra il calcolo dei prezzi e le chiamate all'API CTT in logs/vfd_ctt_debug.log.php nella cartella del modulo. Il file non può essere aperto 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.
Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le sue impostazioni e i suoi corrieri. Se disattivo, la disinstallazione si limita a disattivare i corrieri. Gli ordini, compreso il punto CTT scelto, non vengono mai modificati.
Come funziona al checkout
Nel passaggio della spedizione, PrestaShop chiede al modulo il prezzo di ogni corriere CTT. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non rientrano nell'importo dell'ordine. Il modulo controlla prima Ignore shipping zones e i suoi paesi, 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 restituisce alcun prezzo (errore API, timeout, nessuna copertura, funzione non abilitata per il tuo App ID), il prezzo viene dalla tabella. Se si applica la spedizione gratuita, il prezzo è 0. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.
Un prezzo CTT viene memorizzato nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita viene ricordata per 5 minuti, così il checkout non attende CTT a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Gli errori dell'API non arrivano mai al cliente: si usa il prezzo della tabella, oppure il corriere viene nascosto se la destinazione non ha un prezzo.
Se modifichi un corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Con le chiavi API compilate, il modulo 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 modulo non crea spedizioni, non stampa etichette, non richiede ritiri, non fornisce numeri di tracciamento e non mostra una mappa dei punti CTT. C'è una sola tabella dei prezzi e un solo insieme di impostazioni API per entrambi i corrieri.
Punti di ritiro
Quando il cliente seleziona il corriere dei punti CTT, sotto compaiono un campo di ricerca e un elenco. Il codice postale dell'indirizzo di consegna viene inserito e cercato automaticamente. Il cliente può cercare altri punti CTT per codice postale o città (pulsante Search o Invio) e sceglierne uno dall'elenco. La scelta viene salvata subito nel carrello. 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 nel passaggio della spedizione, il modulo verifica di nuovo il punto sul server. Senza punto il cliente vede Please select a CTT point.; con un punto non presente nell'elenco CTT vede The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Gli elenchi dei punti CTT vengono memorizzati nella cache per 6 ore. 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 funziona con i temi Classic e Hummingbird. È attiva solo quando sono compilati la chiave pubblica, la chiave privata, l'App ID e il Carrier ID.
Il punto scelto viene salvato nell'ordine. Compare nella pagina dell'ordine nel back office, nel blocco CTT point (nome e ID), nella pagina di conferma dell'ordine, nei dettagli dell'ordine nell'account del cliente e nell'e-mail di conferma dell'ordine come CTT point: accanto al nome del corriere. La nuova e-mail d'ordine del modulo Mail alerts mostra anche l'ID del punto.
Nella pagina dell'ordine nel back office, 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. e viene aggiunto un messaggio privato sull'ordine CTT point changed to: con il nuovo punto. Cambiare il punto richiede il permesso di modificare gli ordini.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox CTT è il primo blocco della pagina Modules > Module Manager > VibeFox CTT > Configure, 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 si trovano la riga Product: presta-shipping-ctt e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on con una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato un posto 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, nessuno dei due corrieri CTT (consegna all'indirizzo o a un punto CTT) viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi i corrieri sono nascosti anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non 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 il 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 alla 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
CTT non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Enable CTT point carrier) sia attivo. In Shipping > Carriers verifica 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. 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 e che sia raggiunto il Minimum order amount. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Il cliente non può scegliere un punto CTT: il selettore compare solo sotto il corriere dei punti CTT, e solo quando la chiave pubblica, la chiave privata, l'App ID e il Carrier ID sono compilati. Controlla gli avvisi sopra le impostazioni, attiva Debug log e guarda il campo Log nella pagina del modulo.
Le tariffe in tempo reale non compaiono: la tabella dei prezzi viene usata 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 è abilitata per il tuo App ID: chiedilo 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 modulo riprova automaticamente dopo alcuni minuti.
Prezzi con o senza IVA: con Tax status impostato su una regola Taxable, PrestaShop aggiunge la tassa di spedizione al prezzo. Con None il prezzo è definitivo.
I prezzi sembrano non aggiornati dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le risposte CTT in cache.
La pagina dice che un corriere CTT non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo. Il ripristino conserva le impostazioni e lo stato attivo/disattivo di entrambi i corrieri.
Per sviluppatori: l'indirizzo dell'API CTT può essere modificato con la chiave di configurazione vfd_ctt_API_URL.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox CTT e scegli Uninstall. La chiave di licenza, lo stato della licenza, le risposte CTT in cache e il token API vengono sempre rimossi. Se Remove data on uninstall è attivo, entrambi i corrieri vengono eliminati (gli ordini conservano la loro storia), e vengono rimosse le impostazioni, il log e i punti CTT dei carrelli che non sono mai diventati ordini. Se è disattivo, i corrieri vengono solo disattivati e tutte le impostazioni vengono conservate. Reinstallando il modulo, ogni corriere riprende lo stato attivo/disattivo che aveva. I punti CTT salvati negli ordini vengono sempre conservati.
CTT è un marchio del rispettivo proprietario. Questo modulo non è affiliato a CTT né approvato da CTT.