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

Accesso all'API di J&T Express Malaysia (solo per le tariffe in tempo reale): le tariffe 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 dell'estensione 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 sono emessi da J&T per l'integrazione API. Chiedili al tuo account manager J&T. J&T nelle Filippine, in Indonesia e in altri paesi non ha un'API pubblica per le tariffe, quindi usa per loro la tabella dei prezzi. Se usi solo la tabella dei prezzi e il costo di riserva, non ti serve l'accesso all'API J&T.

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

Installazione

Il file da scaricare è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_jt_express-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_jt_express.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'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_jt_express-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 J&T Express e clicca su Install (il pulsante verde +).

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

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

5. Compila la tabella dei prezzi e/o il costo di riserva. Per le tariffe in tempo reale in Malesia, inserisci anche le credenziali API J&T, il codice postale del mittente e, se la valuta predefinita del negozio non è MYR, il tasso di cambio (vedi Configurazione). Attiva Enable J&T Express e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_jt_express.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 accanto ad esso su Install (il pulsante verde +).

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox J&T Express, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

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

Dopo l'installazione il metodo è disattivato finché non attivi Enable J&T Express e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni di J&T Express che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva tutta la pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe J&T in cache. Se un valore è errato, non viene salvato nulla e la pagina mostra il motivo: un titolo del metodo non valido, un importo che non è un numero maggiore o uguale a 0, una Currency conversion rate pari a 0, un Min weight (kg) maggiore di Max weight (kg), oppure un ordinamento che non è un numero intero. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi sopra le impostazioni (mostrati di nuovo dopo ogni salvataggio) segnalano quando le tariffe in tempo reale sono configurate solo in parte: elencano le impostazioni API mancanti oppure indicano che la valuta del negozio non è MYR e manca il tasso di cambio. Un altro avviso compare se il negozio non ha una classe di peso con l'unità kg in System > Localisation > Weight Classes. I pesi dei prodotti vengono quindi convertiti in base al nome della loro unità (kg, g, lb, oz), e le altre unità vengono lette come kg.

Generale

Il metodo viene offerto per la zona geografica selezionata o per i paesi di Ignore shipping zones. Le impostazioni di questa pagina valgono per tutte le zone.

Enable J&T Express: mostra o nasconde il metodo al checkout (lo stato di questa estensione). Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: J&T Express. Obbligatorio, fino a 64 caratteri, senza i caratteri < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Una classe fiscale aggiunge l'imposta di spedizione al costo. Scegli No tax se il prezzo J&T include già tutto ciò che vuoi addebitare.

Sort order: la posizione del metodo tra i metodi di spedizione al checkout. Un numero intero.

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

La tariffa viene richiesta a J&T Express Malaysia per ogni codice postale malese e memorizzata nella cache per un'ora. Senza le credenziali, e per gli altri paesi, si usano la tabella dei prezzi e il costo di riserva.

VIP customer code: il tuo codice VIP di J&T Express. Cancellarlo 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 nei log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarla. Per rimuoverla, cancella VIP customer code e salva.

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

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

Sender postcode: il codice postale malese da cui vengono spediti i pacchi, per esempio 50000. Obbligatorio per le tariffe in tempo reale: l'indirizzo del negozio in OpenCart è testo libero, quindi il codice postale non viene mai ricavato da lì.

Currency conversion rate: le tariffe di J&T Express Malaysia sono in MYR. Se la valuta predefinita del tuo negozio non è MYR, indica quante unità della tua valuta valgono un MYR (1 MYR = X), per esempio 0.20. Senza questo valore le tariffe in tempo reale non vengono usate e si usa la tabella dei prezzi o il costo di riserva. Se la tua valuta predefinita è MYR, il campo lo indica e non serve: le tariffe vengono usate così come sono. Il tasso deve essere maggiore di 0.

Tabella dei prezzi e riserva (usata per i paesi diversi dalla Malesia, quando le tariffe in tempo reale non sono configurate o quando J&T non fornisce una tariffa; prezzi nella valuta predefinita del negozio, imposte escluse)

Country prices: una tabella con una riga per paese. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. 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 maggiore di 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. I paesi senza riga (quando non c'è una riga *) non ottengono un prezzo dalla tabella.

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

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

Condizioni

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

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

Min weight (kg): nasconde il metodo quando il carrello pesa meno. I pesi dei prodotti vengono convertiti con la loro classe di peso. 0 significa nessun limite (predefinito). Non può essere maggiore di Max weight (kg).

Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 50. 0 significa nessun limite.

Geo zone: offre il metodo solo per indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usata quando Ignore shipping zones è attivo.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi qui sotto, indipendentemente dalla zona geografica. Predefinito: disattivato.

Countries: i paesi di destinazione per questa modalità, scelti tra quelli abilitati nel tuo negozio. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli dei prezzi in storage/logs/vfd_jtex_debug.log.php (su OpenCart 4 in system/storage/logs/vfd_jtex_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API J&T vengono sempre registrati, anche con questa opzione disattivata. Chiavi, password, il codice cliente e i codici postali dei clienti non vengono mai scritti. Disattiva il log quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_jtex_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono cancellate le impostazioni di J&T Express e il log. Se disattivo (predefinito), vengono conservate per una reinstallazione. Le tariffe in cache vengono sempre rimosse.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni come file JSON. La chiave API VIP e la chiave privata non vengono esportate.

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

Funzionamento al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di J&T Express. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. L'estensione controlla poi le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se il subtotale 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. Tariffa 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 a 5 cifre e, per i negozi la cui valuta predefinita non è MYR, è impostato un tasso di cambio. L'estensione 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 collo, e converte il prezzo in MYR restituito nella valuta predefinita del tuo negozio.

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

3. Costo di riserva.

Se nessuna di queste fonti fornisce un prezzo, il metodo viene nascosto per quel carrello. Per item si applica solo ai prezzi di tabella e di riserva. 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.

Ogni risposta di J&T viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita 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 della tabella o di riserva, e il motivo viene scritto nel log.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie J&T Express nella finestra Shipping method options. Il metodo funziona allo stesso modo di OpenCart 3.

L'estensione calcola solo i costi di spedizione. Non crea lettere di vettura, bolle o etichette, non prenota ritiri, non annulla né traccia le spedizioni e non permette al cliente di scegliere un punto di ritiro. Non aggiunge nulla agli ordini: l'ordine mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di OpenCart. Crea e traccia le spedizioni nel tuo account J&T come di consueto. L'estensione è stata sviluppata in base al formato delle richieste dell'integrazione ufficiale di J&T Express Malaysia. Conferma i prezzi con il tuo account J&T prima di andare in produzione.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza License — VibeFox J&T Express è il primo blocco di Extensions > Extensions > Shipping > VibeFox J&T Express > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 ci sono la riga Product: opencart-shipping-jt-express e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (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 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 risponde, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: l'indirizzo del negozio nella configurazione di OpenCart. 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 metodo di spedizione J&T Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque 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 l'accesso all'amministrazione, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallando l'estensione vengono sempre rimossi 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. Controlla Geo zone (o che Ignore shipping zones sia attivo e il paese sia in Countries), 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. Verifica che i prodotti abbiano Requires Shipping impostato su Yes. Attiva Debug log e controlla il campo Log nella pagina dell'estensione.

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

Nessuna tariffa in tempo reale per le Filippine o l'Indonesia: J&T non offre un'API pubblica per le tariffe 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 dell'estensione. Questo cancella le tariffe J&T in cache.

La pagina dice "Warning: You do not have permission to modify VibeFox J&T Express!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_jt_express (OpenCart 3) o extension/vfd_jt_express/shipping/vfd_jt_express (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: altre estensioni possono modificare il corpo della richiesta di tariffa (per esempio il tipo di servizio) con l'evento OpenCart vfd_jt_express/quote_request, e l'indirizzo dell'endpoint delle tariffe con vfd_jt_express/api_url.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox J&T Express. La chiave di licenza e lo stato di licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable J&T Express, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono cancellate anche le impostazioni di J&T Express e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

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 J&T Express nell'elenco delle estensioni installate, quindi su Delete (il pulsante rosso del cestino) per rimuovere il pacchetto caricato.

J&T Express è un marchio del suo rispettivo proprietario. Questa estensione non è affiliata né approvata da J&T Express.