VibeFox J&T Express 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.

Accesso all'API di J&T Express Malaysia (solo per le quotazioni in tempo reale): le quotazioni in tempo reale esistono solo per J&T Express Malaysia, per gli indirizzi di consegna in Malesia. Servono quattro valori. Richiedi un account VIP J&T sul sito di J&T Express Malaysia (la pagina del modulo contiene un link): J&T ti fornisce il codice cliente VIP e la chiave API VIP. L'account API e la chiave privata per firmare le richieste vengono rilasciati da J&T per l'integrazione API. Chiedili al tuo account manager J&T. J&T Filippine, Indonesia e altri paesi non hanno un'API pubblica per le quotazioni, quindi per questi usa la tabella dei prezzi. Se usi solo la tabella dei prezzi e il costo di riserva, non ti serve l'accesso all'API di J&T.

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 trova VibeFox J&T Express 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 e/o il costo di riserva. Per le quotazioni in tempo reale per la Malesia, inserisci anche le credenziali API di J&T, il codice postale del mittente e, se la valuta predefinita del tuo negozio non è MYR, il tasso di conversione valutaria (vedi Configurazione). Clicca su Save.

All'installazione il modulo crea il corriere J&T Express con il testo dei tempi di consegna Courier delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo viene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox J&T Express > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le quotazioni J&T in cache. Se le quotazioni in tempo reale sono configurate solo in parte, un avviso in cima alla pagina elenca le impostazioni mancanti o segnala che manca il tasso di conversione valutaria. Gli importi che non sono un numero pari o superiore a 0 vengono rifiutati con un errore, così come un Currency conversion rate pari a 0 e un Min weight superiore a Max weight. Se l'unità di peso del tuo negozio non è riconosciuta, un avviso ti chiede di impostare un'unità standard in International > Localization.

Generale

Le impostazioni di questa pagina valgono per tutte le zone. Zone, gruppi di clienti e limiti di dimensione del corriere si impostano in Shipping > Carriers (oppure usa Ignore shipping zones qui sotto).

Enable J&T Express: 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. Predefinito: J&T Express. Obbligatorio.

Tax: la regola fiscale del corriere, oppure No tax. Una regola fiscale aggiunge l'IVA sulla spedizione del tuo negozio al costo. Scegli No tax se il prezzo J&T include già tutto ciò che vuoi addebitare.

API di J&T Express Malaysia (quotazioni in tempo reale) (facoltativo, per gli indirizzi di consegna in Malesia; tutte e quattro le credenziali sono obbligatorie)

VIP customer code: il tuo codice cliente VIP di J&T Express. Svuotarlo cancella anche la chiave API VIP salvata.

VIP API key: la chiave API (password) che J&T Express ti ha fornito insieme al codice VIP. Non viene mai registrata nel log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

API account: il nome del tuo account API di J&T Express. Svuotarlo cancella anche la chiave privata salvata.

API private key: la chiave privata dell'account API. Serve solo per firmare le richieste (SHA-256). Non viene mai inviata a J&T né registrata nel log. Come la chiave API VIP, non viene più mostrata dopo il salvataggio.

Sender postcode: il codice postale malese da cui partono i pacchi. Lascialo vuoto per usare il codice postale del negozio da Shop Parameters > Contact > Stores, quando il negozio si trova in Malesia. Gli spazi vengono rimossi al salvataggio.

Currency conversion rate: le quotazioni di J&T Express Malaysia sono in MYR. Se la valuta predefinita del tuo negozio non è MYR, inserisci quante unità della tua valuta vale un MYR (1 MYR = X). Senza questo valore non vengono usate le quotazioni in tempo reale: si usano invece la tabella dei prezzi o il costo di riserva. Se la tua valuta predefinita è MYR, il campo lo indica e non serve: le quotazioni vengono usate così come sono. Sono accettati sia il punto sia la virgola come separatore decimale. Il tasso deve essere maggiore di 0.

Tabella dei prezzi e riserva (usata per i paesi diversi dalla Malesia, quando le quotazioni in tempo reale non sono configurate o quando J&T non fornisce una quotazione; prezzi nella valuta predefinita del tuo negozio, IVA esclusa)

Country prices: una tabella con una riga per paese. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Scegli * Any other country per tutti i paesi senza una riga propria. Ogni riga ha un Base price e cinque fasce di peso: 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 fascia superiore a 0 sostituisce il prezzo base per i carrelli di quella fascia. Una fascia a 0 usa il prezzo base. Un prezzo base di 0 significa spedizione gratuita, e un prezzo base vuoto viene salvato come 0. Se un paese compare in due righe, resta l'ultima. I paesi senza riga (quando non c'è una riga *) non ricevono un prezzo da tabella.

Fallback cost: il prezzo usato quando né J&T né la tabella forniscono un prezzo. Lascialo vuoto per nascondere il corriere in quel caso. 0 significa spedizione gratuita.

Table / fallback price is: Per order addebita il prezzo una sola volta. Per item (multiplied by the number of items) lo moltiplica per il numero di articoli nel carrello. Le quotazioni J&T in tempo reale riguardano sempre l'intero ordine.

Condizioni

Free shipping from: il subtotale del carrello (prodotti che richiedono la spedizione, dopo gli sconti, prima delle imposte) a partire dal quale la spedizione è gratuita. Lascialo vuoto se non vuoi la spedizione gratuita.

Minimum subtotal: mostra il corriere solo quando il subtotale del carrello raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Min weight: nasconde il corriere quando il carrello pesa meno, in kg. I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio. 0 significa nessun limite. Non può essere maggiore di Max weight.

Max weight: nasconde il corriere quando il carrello pesa di più, in kg. Predefinito: 50. 0 significa nessun limite.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il corriere per i paesi indicati qui sotto, anche se non è collegato alla loro zona. Quando lo attivi, il corriere viene collegato a tutte le zone attive, e anche alle zone che crei in seguito. Quando è disattivato, il corriere è offerto solo nelle sue zone in Shipping > Carriers. Disattivandolo, il corriere riprende le sue zone precedenti.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi in cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli dei prezzi in logs/vfd_jtex_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API J&T vengono sempre registrati, anche con questa opzione disattivata. Non vengono scritte chiavi, password né codici postali dei clienti. Disattiva il log quando hai finito.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate le impostazioni del modulo, il corriere, le quotazioni in cache e il log. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo di J&T Express. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla prima le condizioni: paese di consegna (con Ignore shipping zones), peso del carrello e subtotale minimo. Se il subtotale del carrello raggiunge Free shipping from, il prezzo è 0 e non viene inviata alcuna richiesta a J&T.

Altrimenti il costo viene preso dalla prima fonte che fornisce un prezzo:

1. Quotazione J&T in tempo reale: solo quando sono impostate tutte e quattro le credenziali API e un codice postale del mittente, il paese di consegna è la Malesia, il cliente ha inserito un codice postale di 5 cifre e, per i negozi la cui valuta predefinita non è MYR, è impostato un tasso di conversione. Il modulo invia a J&T i codici postali del mittente e del destinatario e il peso del carrello (almeno 0,1 kg) per il servizio standard EZ, un pacco, e converte il prezzo restituito in MYR nella valuta predefinita del tuo negozio.

2. Prezzi per paese: la riga del paese di consegna, oppure la riga *, con il prezzo della fascia di peso del carrello.

3. Costo di riserva.

Se nessuna di queste fonti fornisce un prezzo, il corriere viene nascosto per quel carrello. Per item si applica solo ai prezzi da tabella e di riserva. Il prezzo viene calcolato nella valuta predefinita del tuo negozio e poi mostrato nella valuta del carrello del cliente.

Ogni risposta di J&T viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende J&T a ogni aggiornamento. Il timeout della richiesta è di 10 secondi. Se J&T restituisce un errore, un prezzo pari a zero o nessuna risposta, il cliente non vede alcun errore. Viene usato il prezzo da tabella o di riserva, e il motivo viene scritto nel log.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo i costi di spedizione. Non crea lettere di vettura, documenti di trasporto o etichette, non prenota ritiri, non annulla né traccia le spedizioni e non permette ai clienti di scegliere un punto di ritiro. Crea e traccia le spedizioni nel tuo account J&T come di consueto. Il modulo è stato sviluppato in base al formato delle richieste del plugin ufficiale di J&T Express Malaysia. Verifica i prezzi con il tuo account J&T prima di andare in produzione.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox J&T Express è il primo blocco in Modules > Module Manager > VibeFox J&T Express > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-jt-express e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo chi ha il permesso Configure per il modulo può 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, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure 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, 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il corriere J&T Express non 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 il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi 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 un 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

J&T Express non compare al checkout: verifica che la licenza sia attiva e che Enable J&T Express 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 i limiti di peso e Minimum subtotal. Verifica che Country prices abbia una riga per il paese o una riga *, oppure che Fallback cost sia impostato. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto. Attiva Debug log e controlla il campo Log nella pagina del modulo.

Il prezzo arriva dalla tabella, non da J&T: le quotazioni in tempo reale richiedono tutte e quattro le credenziali API, un codice postale del mittente, un indirizzo di consegna malese con un codice postale di 5 cifre e, per i negozi non in MYR, il Currency conversion rate. Controlla gli avvisi in cima alla pagina del modulo. Se J&T rifiuta la richiesta o non risponde, l'errore viene registrato e si usa il prezzo da tabella o di riserva. La richiesta non riuscita viene ripetuta dopo 10 minuti.

Nessuna quotazione in tempo reale per Filippine o Indonesia: J&T non offre un'API pubblica per le quotazioni in questi paesi. Usa lì la tabella dei prezzi e il costo di riserva.

Un paese ottiene la spedizione gratuita per errore: la sua riga ha un prezzo base di 0 (un prezzo base vuoto viene salvato come 0). Inserisci un prezzo base o rimuovi la riga. Controlla anche Free shipping from.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le quotazioni J&T in cache.

La pagina dice che il corriere J&T Express non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

Hook per sviluppatori: l'hook actionVfdJtexQuoteRequest modifica il corpo della richiesta di quotazione (ad esempio il tipo di servizio), e actionVfdJtexApiUrl cambia l'endpoint delle quotazioni.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox J&T Express e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le quotazioni in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e le impostazioni e il log vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallando il modulo, il corriere salvato riprende il suo stato precedente.

J&T Express è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da J&T Express.