VibeFox Frenet for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

Account Frenet (solo per i preventivi in tempo reale): crea un account gratuito nel pannello Frenet (painel.frenet.com.br), attiva i corrieri che usi e copia il tuo token API. Se usi solo prezzi fissi, non ti serve un account Frenet.

Prodotti: compila peso e dimensioni per prezzi accurati. I prodotti senza questi dati vengono quotati come 0,3 kg e 16 × 11 × 2 cm (la scatola minima di Correios).

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona per 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 più tardi VibeFox Frenet nell'elenco dei moduli e clicca su Configure.

3. Incolla 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. Incolla il token API e inserisci il CEP di partenza. Se la valuta predefinita del tuo negozio non è il BRL, inserisci il tasso di cambio del BRL. Facoltativamente aggiungi prezzi fissi e un costo di riserva. Clicca su Save.

All'installazione il modulo crea il corriere Frenet con il testo del tempo di consegna Delivery by the carriers of your Frenet account. Il corriere viene assegnato a tutte le zone 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 proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Frenet > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i preventivi Frenet in cache. I campi dei prezzi accettano sia il punto sia la virgola come separatore decimale; un valore che non è un numero viene rifiutato con il messaggio "…" must be a number. Vengono rifiutati anche importi e pesi negativi, un BRL exchange rate pari a 0 o inferiore, e un Minimum weight superiore al Maximum weight. In caso di errore non viene salvato nulla.

In cima alla pagina il modulo mostra degli avvisi: nessun token API (vengono usati solo i prezzi fissi, oppure il corriere non viene mai mostrato se non ci sono prezzi fissi), nessun CEP di partenza di 8 cifre, oppure una valuta predefinita diversa dal BRL senza tasso di cambio. Avvisa anche quando l'unità di peso o di dimensione del tuo negozio non è riconosciuta dal modulo; tale unità viene trattata come kg o cm. Imposta un'unità standard (kg, g, lb o oz; cm, mm, m o in) in International > Localization (Local units).

Generale

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

Method title: il nome del corriere mostrato nel carrello e al checkout. Default: Frenet. Obbligatorio, massimo 64 caratteri.

Preventivi Frenet in tempo reale

Frenet confronta i corrieri attivati nel tuo account Frenet e restituisce i loro prezzi per il carrello. I preventivi in tempo reale vengono richiesti solo per indirizzi in Brasile con un CEP completo di 8 cifre. La sezione contiene un link al pannello Frenet.

API token: il tuo token API Frenet, preso dal pannello Frenet. Lascialo vuoto per usare solo prezzi fissi. Dopo il salvataggio il campo resta vuoto e mostra A token is saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo. Per eliminare il token salvato, spunta Remove the saved token e salva.

Origin CEP: il codice postale (CEP) da cui vengono spediti i pacchi, per esempio 00000-000. Lascialo vuoto per usare il codice postale del negozio impostato in Shop Parameters > Contact > Stores, se l'indirizzo del negozio è in Brasile. Un CEP con meno di 8 cifre viene salvato come inserito e la pagina mostra Frenet: the origin CEP must have 8 digits.

Service to offer: Cheapest service (predefinito) oppure Fastest service. Frenet restituisce più servizi e il corriere mostra un solo prezzo.

BRL exchange rate: Frenet quota in real brasiliani. Se la valuta predefinita del tuo negozio non è il BRL, indica quanto vale 1 BRL nella valuta predefinita, per esempio 0.16. Il preventivo e il valore dichiarato dell'ordine vengono convertiti con questo valore. Senza di esso i preventivi in tempo reale non vengono usati. Quando la valuta predefinita è il BRL, il campo mostra Not needed (shop currency is BRL).

Prezzi fissi

Vengono usati quando non c'è un token API, per i paesi che Frenet non serve e ogni volta che Frenet non restituisce un prezzo (API non disponibile, CEP non servito).

Price per country: una tabella con le colonne Country, Price, XS, S, M, L e XL, con prezzi nella valuta predefinita, IVA esclusa. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. Le colonne di dimensione dipendono dal peso del carrello: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg, XL oltre 5 kg. Si usa Price quando la colonna di dimensione è vuota. Un Price pari a 0 significa spedizione gratuita per quel paese. Usa * Default per tutti gli altri paesi. Le righe senza alcun prezzo vengono rimosse al salvataggio.

Fallback cost: usato quando né Frenet né la tabella forniscono un prezzo. Lascialo vuoto per nascondere il corriere.

Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli. Questo vale solo per i prezzi fissi e per il costo di riserva. I preventivi Frenet coprono già l'intero carrello.

Condizioni

Minimum weight: nasconde il corriere sotto questo peso del carrello, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere sopra questo peso del carrello, in kg. Default: 30 (usato anche quando il campo è vuoto). 0 significa nessun limite. Non può essere inferiore a Minimum weight.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle imposte) è almeno pari a questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) da cui la spedizione è gratuita. Lascialo vuoto per non offrire mai la spedizione gratuita.

Tax: la regola fiscale del corriere, oppure No tax. I prezzi Frenet sono prezzi finali del corriere. Scegli No tax se PrestaShop non deve aggiungere imposte.

I pesi e le dimensioni dei prodotti vengono convertiti dalle unità del negozio in kg e cm.

Disponibilità senza zone di spedizione

Di norma il corriere viene offerto nelle zone a cui è assegnato in Shipping > Carriers.

Ignore shipping zones: offre Frenet per i paesi sotto indicati, qualunque sia la zona corrispondente. Al salvataggio il corriere viene aggiunto a tutte le zone, comprese quelle che creerai in seguito. Quando lo disattivi di nuovo, il corriere riottiene le zone che aveva prima.

Countries: i paesi di destinazione per questa modalità, scelti tra i paesi attivi del tuo negozio. Lascialo vuoto per usare tutti i paesi in cui spedisci. Viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra ogni richiesta e risposta di preventivo in logs/vfd_frn_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati. Il token non viene mai registrato e il CEP del cliente viene abbreviato. Disattivalo quando hai finito.

Log: mostra la dimensione e gli ultimi inserimenti del registro. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate tutte le impostazioni Frenet, il corriere e il registro. Se disattivo, tutto viene conservato per una nuova installazione. I preventivi in cache vengono sempre rimossi. I servizi Frenet salvati con gli ordini fanno parte dello storico degli ordini e vengono conservati.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Frenet. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Prima che il cliente inserisca un indirizzo, il modulo usa il paese che il negozio stima per il visitatore. Il modulo controlla prima l'elenco dei paesi (se Ignore shipping zones è attivo), il peso del carrello e l'importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Frenet.

Per un indirizzo in Brasile con un CEP completo di 8 cifre, il modulo invia a Frenet il CEP di partenza e quello di destinazione, ogni articolo del carrello (peso in kg, dimensioni in cm, quantità, riferimento del prodotto e categorie), il valore dell'ordine in BRL e il primo codice coupon del carrello. Non viene fatta alcuna richiesta finché il CEP è incompleto. Frenet restituisce i servizi dei tuoi corrieri attivati. I servizi con errore o senza prezzo vengono saltati. Il modulo sceglie il servizio più economico o quello più veloce e converte il prezzo nella valuta predefinita del negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.

Ogni risposta viene memorizzata nella cache per 1 ora per lo stesso carrello e lo stesso indirizzo. Una richiesta non riuscita, o un CEP che nessun corriere attivato serve, viene ricordata per 10 minuti. Il timeout dell'API è di 10 secondi. In questi casi il cliente non vede alcun errore: viene usato il prezzo fisso o il costo di riserva, oppure il corriere viene nascosto se non ce n'è nessuno. Il motivo viene scritto nel registro. Per gli indirizzi fuori dal Brasile vengono usati solo i prezzi fissi.

Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, 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 e non traccia i pacchi. Mostra un servizio Frenet per carrello, non più di uno, e non prevede punti di ritiro o armadietti. Frenet fornisce preventivi solo per il Brasile; per gli altri paesi usa i prezzi fissi.

Ordini

Quando un ordine viene effettuato con il corriere Frenet, il modulo salva come è stato calcolato il prezzo della spedizione. La pagina dell'ordine nel back office mostra quindi un blocco Frenet con queste righe:

Carrier: il corriere Frenet e il servizio, per esempio un servizio Correios o Jadlog. Mostrato per i preventivi in tempo reale.

Delivery time: il tempo di consegna in giorni lavorativi restituito da Frenet. Mostrato per i preventivi in tempo reale.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost oppure Free shipping.

Questi dati vengono conservati alla disinstallazione del modulo, anche con Remove data on uninstall.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Frenet è il primo blocco di Modules > Module Manager > VibeFox Frenet > Configure, sopra le impostazioni. Incolla 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 compaiono la riga Product: presta-shipping-frenet 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 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo una modifica 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 per un solo dominio: quello 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 Frenet non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non provarlo 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 controllato di nuovo 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Frenet non compare al checkout: verifica che la licenza sia attiva e che Enable Frenet 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. Controlla gli avvisi in cima alla pagina del modulo, i limiti di peso e il Minimum order amount. Motivi tipici: il cliente non ha ancora inserito un CEP completo di 8 cifre e non ci sono prezzi fissi, oppure Frenet non ha restituito alcun servizio per la tratta e non c'è un prezzo fisso. I prodotti possono inoltre essere limitati a determinati corrieri nella pagina del prodotto.

I preventivi in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo: nessun CEP di partenza, nessun tasso di cambio BRL, CEP del cliente incompleto, un limite di peso o di importo, oppure i messaggi dei servizi saltati.

Il registro indica che il token API è stato rifiutato (HTTP 401 o 403): copia di nuovo il token dal pannello Frenet e incollalo in API token.

Il registro indica che Frenet non ha restituito servizi: attiva almeno un corriere nel pannello Frenet.

Il mio negozio vende in euro o dollari: Frenet risponde in BRL. Inserisci il BRL exchange rate (quanto vale 1 BRL nella valuta predefinita del negozio).

Sul prezzo Frenet viene applicata anche l'imposta: i prezzi Frenet sono prezzi finali del corriere. Imposta Tax su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Così vengono cancellati i preventivi Frenet in cache.

La pagina dice che il corriere Frenet non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Fino ad allora, il salvataggio mostra The settings were saved, but the carrier could not be updated.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Frenet e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I preventivi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano lo storico) e le impostazioni e il registro vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo o eseguire un Reset riporta il corriere salvato allo stato che aveva prima: un corriere che avevi disattivato resta disattivato. Gli ordini esistenti mantengono il corriere Frenet e il blocco Frenet nella pagina dell'ordine.

Frenet è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Frenet né approvato da Frenet.