VibeFox SF Express for OpenCart — Guida
Requisiti
OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).
PHP: 8.0 o successivo.
Account SF Express (solo per le tariffe in tempo reale): le tariffe 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 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 di sandbox e di produzione sono diversi. Se usi solo la tabella dei prezzi, non ti serve un account SF Express.
Province cinesi (solo per le tariffe in tempo reale): la tariffa in tempo reale richiede la provincia dell'indirizzo di consegna, cioè la zona OpenCart (Region / State) dell'indirizzo. OpenCart ha le zone della Cina, ma manca il Tibet. L'estensione può aggiungerlo per te (vedi Chinese provinces più sotto).
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.
Installazione
Il download è 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_sf_express-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_sf_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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_sf_express-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella principale del tuo negozio.
2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox SF Express e clicca su Install (il pulsante verde +).
3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.
4. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina Edit, e clicca su Activate (vedi Chiave di licenza).
5. Compila la tabella dei prezzi e/o il costo di riserva.
6. Per le tariffe in tempo reale nella Cina continentale, inserisci il codice cliente e il checkword, la provincia e la città di spedizione e, se la valuta del tuo negozio non è il CNY, il tasso di conversione valutaria. Clicca su Add Chinese provinces se la pagina lo richiede. Prova prima con Sandbox e le credenziali sandbox.
7. Attiva Enable SF Express e clicca su Save.
OpenCart 4
1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_sf_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 su Install (il pulsante verde +) accanto a esso.
3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox SF Express, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).
4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 4 a 7 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.
Dopo l'installazione il metodo resta disattivato finché non attivi Enable SF Express e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni SF Express che hai conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Le sezioni sono elencate a sinistra. Si applicano a tutte le geo zone. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe SF Express memorizzate nella cache. Solo gli amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
Al salvataggio, l'estensione controlla i valori. Un titolo del metodo vuoto, più lungo di 64 caratteri o contenente < > ; = # { }, un valore che non è un numero, un importo o un peso negativo, un tasso di conversione pari a 0, un Min weight (kg) superiore a Max weight (kg), un prezzo errato nella tabella dei prezzi o un ordine di visualizzazione che non è un numero intero vengono rifiutati con un messaggio, e non si salva nulla finché non li correggi. Gli avvisi sopra le impostazioni ti segnalano quando le tariffe in tempo reale sono configurate solo in parte (vengono elencate le impostazioni mancanti), quando manca il tasso di conversione, quando il negozio non ha zone della Cina, o quando il negozio non ha una classe di peso in kg o una classe di lunghezza in cm e la sua unità predefinita non è nota all'estensione.
Generali
Enable SF Express: mostra o nasconde SF Express al checkout. Predefinito: disattivato.
Method title: il nome del metodo mostrato nel carrello e al checkout. Predefinito: SF Express. Obbligatorio, massimo 64 caratteri.
Tax class: la classe fiscale del costo di spedizione, oppure No tax. Con una classe fiscale, sul costo viene aggiunta l'imposta di spedizione del tuo negozio. Scegli No tax se la tariffa SF Express include già tutto ciò che vuoi addebitare.
Sort order: la posizione di SF Express tra i metodi di spedizione al checkout. Un numero intero.
API FengQiao di SF Express (tariffe in tempo reale) (facoltativo, per gli indirizzi di consegna nella Cina continentale)
Customer code (partnerID): il codice cliente (顾客编码) della tua applicazione FengQiao. Svuotarlo cancella anche il checkword salvato, così puoi rimuovere le credenziali.
Checkword: il checkword (校验码) dello stesso ambiente. Serve solo a firmare le richieste e non viene mai inviato né registrato. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.
Sandbox: usa la sandbox FengQiao (sfapi-sbox.sf-express.com) per i test con credenziali sandbox. Le tariffe sandbox non sono reali. Disattivala in un negozio attivo. Predefinito: disattivato.
SF Express product: quale prodotto SF Express viene mostrato con il suo prezzo.
Sender province: la provincia da cui vengono spediti i pacchi, per esempio Guangdong / 广东. La prima opzione usa la regione del tuo negozio (System > Settings > Store > Local) quando il negozio è in Cina. Poi compare Same as the store region con il nome della provincia, altrimenti — Select —.
Sender city: il nome cinese standard della città, per esempio 深圳市. Obbligatorio per le tariffe in tempo reale: l'indirizzo del negozio in OpenCart è testo libero, quindi la città non viene mai presa da lì.
Currency conversion rate: le tariffe SF Express sono in CNY (yuan). Se la valuta predefinita del tuo negozio non è il CNY, inserisci quante unità della tua valuta vale un CNY (1 CNY = ? unità), per esempio 0.13. Senza questo valore non si usano le tariffe in tempo reale. Se la valuta del negozio è il CNY, il campo indica che non serve e le tariffe vengono usate così come sono. Sono accettati sia il punto sia la virgola come separatore decimale.
Chinese provinces: indica quante delle 32 province, regioni autonome e municipalità di SF Express sono zone della Cina in OpenCart e quali mancano. Gli indirizzi in una provincia mancante ricevono la tariffa della tabella. Clicca su Add Chinese provinces per aggiungere solo quelle mancanti come zone della Cina (codice ISO, un nome come "Tibet / 西藏"). Le zone esistenti non vengono modificate. Nulla cambia senza questo clic. Le zone aggiunte così restano nel negozio dopo la disinstallazione.
Tabella dei prezzi e riserva (usata per Hong Kong, Macao, Taiwan e altri paesi, quando le tariffe in tempo reale non sono configurate o quando SF Express non restituisce un prezzo; prezzi nella valuta predefinita del negozio, IVA esclusa)
Country prices: una tabella con un prezzo base per paese. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. La riga * All other countries si applica a tutti i paesi senza una riga propria. Un prezzo di fascia di peso maggiore di 0 sostituisce il prezzo base per i pacchi di quella fascia: 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 Base di 0 significa spedizione gratuita. Un prezzo base vuoto significa che per questo paese non c'è un prezzo e si usa il costo di riserva. Sono accettati sia "9.99" sia "9,99". Una riga senza alcun prezzo non viene salvata.
Fallback cost: usato quando né SF Express né la tabella forniscono 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.
Le tariffe in tempo reale di SF Express riguardano sempre l'intero ordine.
Condizioni
Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo il coupon, prima delle imposte) da cui la spedizione è gratuita. Lascialo vuoto per non offrire mai la spedizione gratuita. La spedizione gratuita viene verificata prima di cercare qualsiasi prezzo, quindi da questo importo il metodo viene offerto gratis per ogni destinazione in cui è disponibile, anche per un paese senza riga in tabella o senza Fallback cost.
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 dalla loro classe di peso. 0 significa nessun limite.
Max weight (kg): il peso massimo del carrello in kg. Predefinito: 50. 0 o vuoto significa nessun limite.
Geo zone: offri SF Express solo per gli indirizzi in questa geo zone. All zones (predefinito) significa nessun limite. Le geo zone si gestiscono in System > Localisation > Geo Zones. Non viene controllata quando Ignore shipping zones è attivo.
Disponibilità senza zone di spedizione
Ignore shipping zones: offri SF Express per i paesi indicati sotto, indipendentemente dalla geo zone. Quando è disattivato, decide la geo zone e l'elenco dei paesi non viene usato.
Countries: i paesi di destinazione per questa modalità. Lascia vuoto per consentire tutti i paesi attivi. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_sfex_debug.log.php. Il file non è leggibile dal web. Gli errori delle API vengono sempre registrati, anche con questa opzione disattivata. Non vengono scritti il checkword né gli indirizzi dei clienti. Quando il file raggiunge 5 MB, viene spostato in vfd_sfex_debug.old.log.php e si avvia un nuovo registro.
Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni e il registro. Se disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. Le tariffe in cache vengono sempre eliminate.
Importa / Esporta
Export: clicca su Download JSON per salvare le impostazioni in un file JSON, senza il checkword.
Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. I valori vengono controllati come in un normale salvataggio. Il checkword salvato resta invariato.
Come funziona al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione la tariffa SF Express. Se è impostata una Geo zone e l'indirizzo è al di fuori, SF Express non viene offerto (a meno che Ignore shipping zones sia attivo). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. Il subtotale è il prezzo di questi prodotti dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. L'estensione controlla poi le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. Se il subtotale raggiunge Free shipping from, la tariffa è 0 e non viene inviata alcuna richiesta a SF Express.
Per un indirizzo di consegna nella Cina continentale con codice cliente e checkword impostati, l'estensione invia a SF Express la tua provincia e città di spedizione, la provincia e la città del cliente, il peso del carrello (almeno 0,1 kg) e il volume del carrello (dai prodotti con tutte e tre le dimensioni). La richiesta viene firmata con il tuo checkword. SF Express restituisce le tariffe in CNY; l'estensione converte quella scelta nella valuta predefinita del tuo negozio e la arrotonda ai decimali previsti. Il prezzo viene poi mostrato nella valuta del cliente con l'imposta della Tax class selezionata.
SF Express riconosce gli indirizzi tramite i nomi cinesi standard. La provincia del cliente proviene dalla zona Region / State dell'indirizzo, riconosciuta dal suo nome. La zona "Hong Kong" non è una provincia della Cina continentale e riceve la tariffa della tabella. 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 la tariffa della tabella.
Ogni tariffa viene memorizzata nella cache per un'ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata per 10 minuti, così il checkout non attende SF Express a ogni aggiornamento. Il timeout HTTP è di 10 secondi.
Se non c'è una tariffa in tempo reale, il prezzo viene preso dalla tabella dei prezzi e 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 registro.
L'estensione calcola solo le tariffe. Non crea lettere di vettura o 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 servizio o un armadietto SF. SF Express viene usato come corriere porta a porta. Le tariffe in tempo reale esistono solo per gli indirizzi di consegna nella Cina continentale. L'estensione è stata sviluppata sulla documentazione FengQiao e su risposte simulate, quindi verifica le tariffe con il tuo account SF Express (prima in sandbox) prima di andare in produzione.
Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie SF Express nella finestra Shipping method options, dove il titolo del metodo è mostrato insieme al prezzo. Il metodo funziona come su OpenCart 3.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox SF Express è il primo blocco di Extensions > Extensions > Shipping > VibeFox SF Express > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopo di che 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-sf-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 è raggiungibile, l'estensione continua a funzionare con l'ultimo stato noto.
Una chiave funziona su un dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, il metodo di spedizione SF Express non viene mostrato ai clienti al checkout e non viene calcolato alcun prezzo. Un utente amministratore che ha effettuato l'accesso all'area admin nello stesso browser vede ancora 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 dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'admin compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.
Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard o la pagina Edit dell'admin: 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 l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
SF Express non compare al checkout: controlla che la licenza sia attiva e che Enable SF Express sia attivo. Controlla Geo zone oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e Minimum subtotal. Controlla che la tabella o il Fallback cost abbiano un prezzo per il paese. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.
La tariffa viene dalla tabella, non da SF Express: le tariffe in tempo reale richiedono il codice cliente e il checkword, una provincia e una città di spedizione, un indirizzo di consegna nella Cina continentale con provincia e nome cinese della città e (per negozi con valuta diversa dal CNY) il tasso di conversione valutaria. Leggi gli avvisi in cima alla pagina dell'estensione, poi attiva il Debug log, ricarica il checkout e controlla il campo Log per vedere il motivo. Una richiesta non riuscita viene ritentata dopo 10 minuti.
Il registro mostra un errore di firma: il checkword è errato o appartiene all'altro ambiente. Controlla l'impostazione Sandbox. Se SF Express segnala che l'API non è consentita, aggiungi l'API di richiesta tariffe alla tua applicazione FengQiao.
Gli indirizzi in Tibet ricevono la tariffa della tabella: clicca su Add Chinese provinces nella sezione API della pagina dell'estensione.
Hong Kong: funziona con la tabella dei prezzi e il costo di riserva. La richiesta tariffe FengQiao riguarda gli indirizzi della Cina continentale.
Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe SF Express in cache.
La pagina dice "Warning: You do not have permission to modify VibeFox SF Express!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_sf_express (OpenCart 3) o extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: gli eventi OpenCart vfd_sf_express/quote_request e vfd_sf_express/api_url permettono a un'altra estensione di modificare la richiesta di tariffa (per esempio verso un altro codice prodotto) e l'URL del gateway.
Disinstallazione
Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox SF Express. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable SF Express, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il registro. Se è disattivo, restano e vengono riutilizzate quando reinstalli l'estensione. Le zone della Cina aggiunte con Add Chinese provinces restano. 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, clicca su Uninstall (il pulsante arancione −) accanto a VibeFox SF Express nell'elenco delle estensioni installate, quindi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.
SF Express è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da SF Express.