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

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 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 i prezzi in tempo reale): il prezzo in tempo reale richiede la provincia dell'indirizzo di consegna. PrestaShop non ha province cinesi di default. Il modulo può aggiungerle per te (vedi sotto Chinese provinces).

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 più tardi VibeFox SF Express 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 e clicca su Save.

5. Per i prezzi in tempo reale nella Cina continentale, inserisci il codice cliente e il checkword, la provincia e la città del mittente (oppure imposta un indirizzo del negozio in Cina) e, se la valuta del tuo negozio non è CNY, il tasso di conversione. Clicca su Add Chinese provinces se la pagina lo richiede. Prova prima con Sandbox e le credenziali sandbox.

All'installazione il modulo crea il corriere SF 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 prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox SF Express > Configure. Valgono per tutte le zone del corriere. Ogni sezione ha il suo pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i prezzi SF Express in cache.

Al salvataggio il modulo controlla i numeri. Un valore che non è un numero, un importo o un peso negativo, un tasso di conversione di 0, un Min weight superiore a Max weight o un prezzo errato nella tabella vengono rifiutati con un messaggio, e non si salva nulla finché non correggi. Gli avvisi sopra le impostazioni ti dicono quando i prezzi in tempo reale sono configurati solo in parte (sono elencate le impostazioni mancanti), quando manca il tasso di conversione, quando gli indirizzi cinesi non hanno il campo provincia, o quando l'unità di peso o di dimensione del tuo negozio non è riconosciuta dal modulo. Le unità si impostano in International > Localization (Local units).

Generale

Enable SF 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: SF Express. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Con una regola fiscale, l'imposta sulla spedizione del tuo negozio si aggiunge al costo. Scegli No tax se il prezzo SF Express include già tutto ciò che vuoi far pagare.

API FengQiao di SF Express (prezzi in tempo reale) (opzionale, per 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 se vuoi cambiarlo.

Sandbox: usa la sandbox FengQiao (sfapi-sbox.sf-express.com) per fare test con credenziali sandbox. I prezzi sandbox non sono reali. Disattivala in un negozio in produzione. Predefinito: disattivato.

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 Shop Parameters > Contact > Stores, 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 predefinita del tuo negozio non è CNY, indica quante unità della tua valuta vale un CNY (1 CNY = ? unità). Senza, i prezzi in tempo reale non vengono usati. Se la valuta del tuo negozio è CNY, i prezzi vengono usati così come sono. Sono accettati sia il punto sia la virgola come separatore decimale.

Chinese provinces: mostra se gli indirizzi cinesi possono avere una provincia. Se no, clicca su Add Chinese provinces. Il pulsante aggiunge le 32 province, regioni autonome e municipalità come stati della Cina (codici ISO come GD e BJ, nomi come "Guangdong / 广东"), attiva "Contains states" per la Cina e aggiunge il campo stato al modulo di indirizzo cinese. Le province già esistenti non vengono aggiunte di nuovo. Senza questo clic non cambia nulla.

Tabella dei prezzi e riserva (usata 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 predefinita del tuo negozio, IVA esclusa)

Country prices: una tabella con un prezzo base per paese. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. La riga * All other countries 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: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Un prezzo base di 0 significa spedizione gratuita. Un prezzo base vuoto significa che non c'è prezzo per questo paese 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 danno un prezzo. Lascialo vuoto per nascondere il corriere in quel caso.

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

I prezzi SF Express in tempo reale sono sempre calcolati per l'intero ordine.

Condizioni

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) 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 corriere è offerto gratis per ogni destinazione in cui è disponibile, anche per un paese senza riga in tabella o senza Fallback cost.

Minimum subtotal: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Min weight: il peso minimo del carrello in kg. I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio. 0 significa nessun limite.

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

Disponibilità senza zone di spedizione

Ignore shipping zones: offre SF Express per i paesi sotto indicati, qualunque zona corrisponda. Al salvataggio il corriere viene aggiunto a tutte le zone, e vengono aggiunte anche le zone create in seguito. Disattivando l'opzione, le zone aggiunte vengono rimosse. Quando è disattivata, il corriere compare solo nelle proprie zone.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi attivi. Questo campo è usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli dei prezzi in logs/vfd_sfex_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori delle API vengono sempre registrati, anche con questa opzione disattivata. Non vengono scritti il checkword né gli indirizzi dei clienti.

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

Remove data on uninstall: se attiva, la disinstallazione del modulo elimina le impostazioni, il corriere, i prezzi in cache e i log. Se disattiva, tutto viene conservato per una reinstallazione.

Come funziona al checkout

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

Per un indirizzo di consegna nella Cina continentale con codice cliente e checkword impostati, il modulo invia a SF Express la provincia e la città del mittente, 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 viene firmata con il tuo checkword. SF Express restituisce i prezzi in CNY e il modulo converte quello scelto nella valuta predefinita del tuo negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.

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

Ogni prezzo viene memorizzato nella cache per un'ora, quindi lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene messa in cache per 10 minuti, così il checkout non attende 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 da Fallback cost. Se nessuno dei due si applica, il corriere viene nascosto. Il cliente non vede mai un errore. L'errore 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 prezzi. Non crea lettere di vettura né etichette, non crea ordini in SF Express, non prenota ritiri, 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 indirizzi di consegna nella Cina continentale. Il modulo è 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 modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox SF Express è il primo blocco della pagina Modules > Module Manager > VibeFox SF Express > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per 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 ci sono la riga Product: presta-shipping-sf-express e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono cambiare 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 spiega il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con una data. Dopo un cambio dell'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 SF Express non viene mostrato ai clienti al checkout e non viene calcolato alcun prezzo. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo 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 a settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo 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. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure attiva Ignore shipping zones e controlla Countries). Controlla i limiti di peso e il Minimum subtotal. Controlla che la tabella o il Fallback cost abbiano un prezzo per il paese. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Il prezzo viene dalla tabella, non da SF Express: i prezzi in tempo reale richiedono codice cliente e checkword, una provincia e una città del mittente, 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. Leggi gli avvisi in cima alla pagina del modulo, poi attiva Debug log, ricarica il checkout e controlla il campo Log per vedere il motivo. Una richiesta non riuscita viene ritentata dopo 10 minuti.

Il modulo di indirizzo per la Cina non ha la provincia: clicca su Add Chinese provinces nella sezione API della pagina del modulo.

Errore A1006 nel log: firma non valida. Il checkword è sbagliato o 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 prezzi FengQiao riguarda solo gli indirizzi della Cina continentale.

I prezzi sembrano obsoleti dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella i prezzi SF Express in cache.

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

Per gli sviluppatori: l'hook actionVfdSfExpressQuoteRequest modifica la richiesta di prezzo, per esempio per usare un altro codice prodotto. actionVfdSfExpressApiUrl cambia l'URL del gateway.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox SF Express e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I prezzi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimosse impostazioni e log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallare il modulo, o un Reset, riporta il corriere allo stato che aveva prima. Gli ordini esistenti conservano le loro righe di spedizione.

SF Express è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato né approvato da SF Express.