VibeFox J&T Express for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

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 delle impostazioni 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 rilasciati da J&T per l'integrazione API. Chiedili al tuo account manager J&T. J&T Filippine, Indonesia e gli altri paesi non hanno un'API pubblica per le quotazioni, quindi per loro usa 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: si acquista 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. In alternativa puoi caricare la cartella vfd_jt_express in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox J&T Express, 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 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 del negozio non è MYR, il tasso di conversione (vedi Configurazione).

6. Aggiungi VibeFox J&T Express a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox J&T Express. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome che il cliente vede per questa zona. Lascialo vuoto per usare il Method title globale.

Ogni volta che salvi le impostazioni, le quotazioni J&T memorizzate nella cache vengono cancellate. Se le quotazioni in tempo reale sono configurate solo in parte, un avviso in cima alla pagina elenca le impostazioni mancanti oppure segnala che manca il tasso di conversione valutaria.

Generale

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente. Predefinito: on.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Una zona può sostituirlo. Predefinito: J&T Express.

Tax status: Taxable aggiunge l'imposta di spedizione del tuo negozio al costo, None non la aggiunge. Scegli None 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; servono tutte e quattro le credenziali)

VIP customer code: il tuo codice cliente VIP di J&T Express.

VIP API key: la chiave API (password) che J&T Express ti ha dato insieme al codice VIP. Non viene mai scritta nel log.

API account: il nome del tuo account API di J&T Express.

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é scritta nel log.

Sender postcode: il codice postale malese da cui partono i pacchi. Lascialo vuoto per usare il codice postale del negozio da WooCommerce > Settings > General, 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 del tuo negozio non è MYR, indica quante unità della tua valuta valgono un MYR (1 MYR = X). Senza questo valore non si usano le quotazioni in tempo reale, e al loro posto si usano la tabella dei prezzi o il costo di riserva. Se la valuta del negozio è MYR, lascialo vuoto: le quotazioni vengono usate così come sono. Sono accettati sia il punto sia la virgola come separatore decimale.

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 alcuna quotazione; prezzi nella valuta del tuo negozio)

Country prices: una tabella con una riga per paese. Fai clic su Add country per aggiungere una riga e sulla croce 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 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 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 metodo in quel caso.

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 (dopo gli sconti, prima delle imposte) da cui la spedizione è gratuita. Lascialo vuoto se non vuoi la 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 dall'unità di peso del tuo negozio. 0 significa nessun limite.

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

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati qui sotto, anche se non è aggiunto a nessuna zona di spedizione. Quando è disattivato, il metodo compare solo nelle zone a cui è stato aggiunto.

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

Avanzate

Debug log: scrive i calcoli dei prezzi in WooCommerce > Status > Logs, origine vfd-jt-express. Gli errori dell'API J&T vengono sempre registrati, anche con questa opzione disattivata. Non vengono scritte chiavi, password o codici postali dei clienti. Disattiva il log quando hai finito.

Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse le sue impostazioni, i metodi delle zone e le quotazioni in cache. Disattivare il plugin non cancella mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, subtotale minimo e classi di spedizione escluse. Se il subtotale del carrello raggiunge Free shipping from, il metodo viene mostrato con un costo di 0, ma solo se il paese ha un prezzo: una riga in Country prices, un Fallback cost o una quotazione J&T in tempo reale. J&T viene interrogato solo quando tabella e costo di riserva non forniscono un prezzo.

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 il codice postale del mittente, il paese di consegna è la Malesia, il cliente ha inserito un codice postale di 5 cifre e, per i negozi che non usano MYR, è impostato un tasso di conversione. Il plugin invia a J&T i codici postali del mittente e del destinatario e il peso del carrello (minimo 0,1 kg) per il servizio standard EZ, un pacco, e converte il prezzo restituito in MYR nella valuta del tuo negozio.

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

3. Fallback cost.

Se nessuna di queste fonti fornisce un prezzo, il metodo viene nascosto. Per item si applica solo ai prezzi da tabella e di riserva.

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 il costo di riserva, e il motivo viene scritto nel log.

Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin 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 sempre. Il plugin è 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 online.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox J&T Express. 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 il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, J&T Express non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

J&T Express non compare al checkout: controlla 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 sia consentito). Controlla i limiti di peso, Minimum subtotal e Excluded shipping classes. Verifica che Country prices abbia una riga per il paese o una riga *, oppure che Fallback cost sia impostato. Attiva il Debug log e controlla WooCommerce > Status > Logs.

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 codice postale di 5 cifre e, per i negozi che non usano MYR, il Currency conversion rate. Controlla gli avvisi in cima alla pagina delle impostazioni. Se J&T rifiuta la richiesta o non risponde, l'errore viene registrato e viene usato il prezzo da tabella o il costo di riserva. La richiesta non riuscita viene ritentata dopo 10 minuti.

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

Un paese riceve 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.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così si cancellano le quotazioni J&T in cache.

Hook per sviluppatori: il filtro vfd_jtex_quote_request modifica il corpo della richiesta di quotazione (per esempio il tipo di servizio), vfd_jtex_api_url cambia l'endpoint delle quotazioni e il filtro standard woocommerce_shipping_vfd_jt_express_is_available controlla la disponibilità.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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 per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin conserva 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. Impostazioni, metodi delle zone e quotazioni in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano disponibili per una reinstallazione successiva. Gli ordini esistenti mantengono le loro righe di spedizione.

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