VibeFox SF 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.

Account SF Express (solo per i prezzi in tempo reale): i prezzi in tempo reale usano la piattaforma aperta FengQiao di SF Express (open.sf-express.com). Ti servono un account mensile SF Express e un account sviluppatore su FengQiao. Registrati lì, crea un'applicazione, aggiungi l'API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) e copia il codice cliente e il checkword. I checkword della sandbox e della produzione sono diversi. Se usi solo la tabella dei prezzi, non ti serve un account SF Express.

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_sf_express in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox SF 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.

6. Per i prezzi in tempo reale nella Cina continentale, inserisci il codice cliente e il checkword, la provincia e la città di partenza (oppure imposta un indirizzo del negozio in Cina) e, se la valuta del negozio non è CNY, il tasso di conversione. Prova prima con Sandbox e con le credenziali sandbox.

7. Aggiungi VibeFox SF 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 SF 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 i clienti vedono per questa zona. Lascialo vuoto per usare il Method title generale.

Ogni volta che salvi le impostazioni, i prezzi SF Express in cache vengono cancellati. Se i prezzi in tempo reale sono configurati solo in parte, un avviso sopra le impostazioni elenca le impostazioni mancanti o il tasso di conversione mancante.

Generali

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

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

Tax status: Taxable aggiunge al costo l'imposta sulla spedizione del tuo negozio, None non la aggiunge. Scegli None se il prezzo SF Express include già tutto ciò che vuoi addebitare.

API FengQiao di SF Express (prezzi in tempo reale) (opzionale, per gli indirizzi di consegna nella Cina continentale)

Customer code (partnerID): il codice cliente (顾客编码) della tua applicazione FengQiao.

Checkword: il checkword (校验码) dello stesso ambiente. Serve solo a firmare le richieste e non viene mai inviato né registrato.

Sandbox: usa la sandbox FengQiao per i test con credenziali sandbox. I prezzi della sandbox non sono reali. Disattivala in un negozio attivo. Predefinito: off.

SF Express product: di quale prodotto SF Express viene mostrato il prezzo.

Sender province: la provincia da cui partono i pacchi. Lascialo vuoto per usare la provincia dell'indirizzo del negozio in WooCommerce > Settings > General, quando il negozio si trova in Cina.

Sender city: il nome standard della città cinese, per esempio 深圳市. Lascialo vuoto per usare la città del negozio, quando il negozio si trova in Cina.

Currency conversion rate: i prezzi SF Express sono in CNY (yuan). Se la valuta del negozio non è CNY, indica quante unità della valuta del negozio vale un CNY. Senza, i prezzi in tempo reale non vengono usati. Se la valuta del negozio è CNY, i prezzi vengono usati così come sono. Sono accettati sia il punto sia la virgola come separatore decimale.

Tabella dei prezzi e costo di riserva (usati per Hong Kong, Macao, Taiwan e altri paesi, quando i prezzi in tempo reale non sono configurati o quando SF Express non restituisce un prezzo; i prezzi sono nella valuta del negozio)

Country prices: una tabella con un prezzo base per paese. La riga * Any other country si applica a tutti i paesi senza una riga propria. Un prezzo di fascia di peso superiore a 0 sostituisce il prezzo base per i pacchi di quella fascia: ≤ 1 kg, ≤ 2 kg, ≤ 3 kg, ≤ 5 kg e > 5 kg. Un prezzo base di 0 significa spedizione gratuita. Un prezzo base vuoto significa che non c'è un prezzo per questo paese e viene usato il costo di riserva.

Fallback cost: usato quando né SF Express né la tabella restituiscono un prezzo. Lascialo vuoto per nascondere il metodo in quel caso.

Table / fallback price is: come vengono addebitati i prezzi da tabella e di riserva.

I prezzi SF Express in tempo reale si riferiscono sempre all'intero ordine.

Condizioni

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. La spedizione gratuita viene offerta solo dove il metodo ha un prezzo per la destinazione: un prezzo in tempo reale, una riga della tabella o il Fallback cost. Lascialo vuoto per non offrire mai 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): il peso minimo del carrello in kg. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio. 0 significa nessun limite.

Max weight (kg): il peso massimo del carrello in kg. Predefinito: 50. 0 significa nessun limite.

Excluded shipping classes: nasconde il metodo se il carrello contiene prodotti di queste classi di spedizione WooCommerce.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati sotto anche se non è aggiunto a una zona. Quando è disattivata, il metodo compare solo nelle zone di spedizione 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 è attiva.

Avanzate

Debug log: scrive i calcoli dei prezzi nel log di WooCommerce: WooCommerce > Status > Logs, origine vfd-sf-express. Gli errori API vengono sempre registrati, anche quando questa opzione è disattivata. Non vengono scritti checkword né indirizzi dei clienti.

Remove data on uninstall: quando è attiva, eliminando il plugin vengono rimosse le sue impostazioni, i suoi metodi nelle zone di spedizione e le cache. Disattivare il plugin non elimina mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin un prezzo. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, subtotale minimo e classi di spedizione escluse. Se si applica la spedizione gratuita e la tabella dei prezzi o il Fallback cost hanno un prezzo per la destinazione, il metodo viene mostrato con prezzo 0 e nessuna richiesta viene inviata a SF Express. Altrimenti il plugin chiede prima a SF Express un prezzo in tempo reale e mostra il metodo come gratuito solo se ne arriva uno.

Per un indirizzo di consegna nella Cina continentale, con codice cliente e checkword impostati, il plugin invia a SF Express la provincia e la città di partenza, la provincia e la città del cliente, il peso del carrello e il volume del carrello (dai prodotti con tutte e tre le dimensioni). La richiesta è firmata con il tuo checkword. SF Express restituisce i prezzi in CNY e il plugin converte quello scelto nella valuta del tuo negozio.

SF Express riconosce gli indirizzi tramite i nomi cinesi standard. La provincia del cliente proviene dal campo stato del checkout. La città deve essere scritta in cinese, per esempio 广州市. Per Pechino, Shanghai, Tianjin e Chongqing la città viene compilata automaticamente. Una città scritta con caratteri latini, come "Guangzhou", riceve il prezzo della tabella.

Ogni prezzo è memorizzato nella cache per un'ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita è memorizzata nella cache per 10 minuti, perché il checkout non debba attendere SF Express a ogni aggiornamento. Il timeout HTTP è di 10 secondi.

Se non c'è un prezzo in tempo reale, il prezzo viene dalla tabella dei prezzi, poi dal Fallback cost. Se nessuno dei due si applica, il metodo viene nascosto. Il cliente non vede mai un errore. L'errore viene scritto nel log.

Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS). Sono incluse le traduzioni in inglese e in cinese semplificato.

Il plugin calcola solo i prezzi. Non crea lettere di vettura né etichette, non crea ordini in SF Express, non prenota ritiri e non annulla né traccia le spedizioni. Crea e traccia le spedizioni nel tuo account SF Express come al solito. I clienti non possono scegliere un punto di ritiro SF o un armadietto. SF Express viene usato come corriere porta a porta. I prezzi in tempo reale esistono solo per gli indirizzi di consegna nella Cina continentale. Il plugin è stato sviluppato sulla documentazione FengQiao e su risposte simulate, quindi verifica i prezzi con il tuo account SF Express (prima in sandbox) prima di andare in produzione.

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 SF 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 dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, SF Express non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato con (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 il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

SF 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 attiva e il paese consentito). Controlla i limiti di peso, Minimum subtotal e Excluded shipping classes. Verifica che la tabella o il Fallback cost abbiano un prezzo per il paese.

Il prezzo viene dalla tabella, non da SF Express: i prezzi in tempo reale richiedono codice cliente e checkword, una provincia e una città di partenza, un indirizzo di consegna nella Cina continentale con provincia e nome di città cinese e (per i negozi non in CNY) il tasso di conversione. Apri WooCommerce > Status > Logs, origine vfd-sf-express, per vedere il motivo. Una richiesta non riuscita viene ripetuta dopo 10 minuti.

Errore A1006 nel log: firma non valida. Il checkword è sbagliato oppure appartiene all'altro ambiente. Controlla l'impostazione Sandbox.

Errore A1004 nel log: l'API di richiesta prezzi non è aggiunta alla tua applicazione FengQiao.

Hong Kong: funziona con la tabella dei prezzi e il costo di riserva. La richiesta di prezzi FengQiao riguarda solo gli indirizzi della Cina continentale.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così vengono cancellati i prezzi SF Express in cache.

Per gli sviluppatori: il filtro vfd_sfex_quote_request modifica la richiesta di prezzo, per esempio per usare un altro codice prodotto. vfd_sfex_api_url cambia l'URL del gateway.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot 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 di licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona e prezzi in cache vengono rimossi solo se Remove data on uninstall era attiva. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti mantengono le loro righe di spedizione.

SF Express è un marchio del rispettivo titolare. Questo plugin non è affiliato a SF Express né approvato da essa.