VibeFox ShipStation for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

Account ShipStation: collega i tuoi corrieri in ShipStation (Settings > Shipping > Carriers), poi copia API Key e API Secret da ShipStation > Settings > Account > API Settings. L'accesso API dipende dal tuo piano ShipStation. Se la pagina non è disponibile, il tuo piano non include l'accesso API. Il modulo usa l'API V1 di ShipStation (API Key e API Secret). Gli account ShipStation API V2 con una singola chiave API non sono supportati. Senza chiavi vengono usate solo le tariffe di riserva.

Chiave di licenza VibeFox: si acquista 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, più tardi, trova VibeFox ShipStation nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco della licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Incolla API Key e API Secret, inserisci il codice postale di partenza e clicca su Save. La pagina ora elenca i codici corriere del tuo account. Inserisci quello o quelli che vuoi in Carrier codes e salva di nuovo.

5. Se la valuta predefinita del tuo negozio non è la valuta del tuo account ShipStation, imposta Exchange rate.

6. Facoltativamente, compila le tariffe di riserva.

All'installazione il modulo crea il corriere ShipStation Shipping con il testo dei tempi di consegna ShipStation carriers (USPS, UPS, FedEx, ...). Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox ShipStation > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota la cache delle tariffe ShipStation e controlla API Key e API Secret. La pagina mostra poi i corrieri collegati al tuo account con i rispettivi codici, per esempio "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)".

Gli avvisi in cima alla pagina ti segnalano quando le tariffe in tempo reale non possono funzionare: nessuna chiave, nessun codice corriere, nessun codice postale di partenza, tasso di cambio mancante, verifica della connessione non riuscita oppure codici corriere non collegati al tuo account. Un avviso compare anche quando l'unità di peso o di dimensione del negozio non è convertibile dal modulo. Imposta kg, g, lb o oz e cm, mm, m o in in International > Localization (Local units). Un campo numerico con valore negativo o con testo non numerico, oppure un Minimum weight superiore al Maximum weight, viene segnalato come errore e non viene salvato nulla.

Generale

Enable ShipStation shipping: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del corriere mostrato al cliente al checkout. Predefinito: ShipStation Shipping. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Le tariffe ShipStation non includono l'imposta sulle vendite. No tax le mostra così come sono quotate; una regola fiscale aggiunge l'imposta sulla spedizione secondo le tue regole fiscali.

Account ShipStation

API Key: la API Key da ShipStation > Settings > Account > API Settings. Viene inviata solo a ShipStation e non viene mai registrata. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

API Secret: l'API Secret della stessa pagina. Viene trattata allo stesso modo della chiave.

Remove the saved API key and secret: appare quando le chiavi sono salvate. Selezionalo e salva per rimuoverle entrambe.

Carrier codes: uno o più codici corriere ShipStation, separati da virgole, per esempio stamps_com, ups_walleted. Vengono usati fino a 5 codici, con una richiesta API per corriere. Se ne inserisci di più, vengono mantenuti solo i primi 5 e la pagina lo segnala. Viene mostrata la tariffa più economica di questi corrieri. Prendi i codici dall'elenco mostrato dopo il salvataggio.

Allowed services: facoltativo, codici servizio ShipStation separati da virgole, per esempio usps_priority_mail, ups_ground. Lascia vuoto per mostrare il servizio più economico dei corrieri indicati sopra.

Package code: "package" (predefinito) quota la tua scatola ed esclude le buste e le scatole a tariffa fissa del corriere. Lascia vuoto per quotare tutti i tipi di pacco offerti dal corriere.

Spedizione da

Ship-from postal code: obbligatorio per le tariffe in tempo reale. ShipStation calcola la tariffa solo in base al codice postale, che deve trovarsi nel paese del tuo account ShipStation. Lascia vuoto per usare il codice postale del negozio da Shop Parameters > Contact > Stores.

Tariffe

Parcels: come il carrello viene inviato a ShipStation.

ShipStation account currency: la valuta in cui ShipStation restituisce le tariffe: USD, CAD, GBP, AUD, NZD o EUR. Predefinito: USD (account statunitensi).

Exchange rate: il prezzo di 1 unità della valuta dell'account nella valuta predefinita del tuo negozio, per esempio 0.92. Serve solo quando la valuta predefinita è diversa da quella dell'account. Senza di esso le tariffe in tempo reale non vengono usate e si applicano le tariffe di riserva. I tassi di cambio non vengono aggiornati automaticamente.

Tariffe di riserva (usate quando non c'è una tariffa in tempo reale: nessuna chiave API, ShipStation non raggiungibile, nessuna tariffa dei corrieri per l'indirizzo; prezzi nella valuta predefinita del tuo negozio; lascia vuote la tabella e Other countries per nascondere il corriere in quel caso)

Prices by country: una tabella con una tariffa base per paese e colonne di dimensione in base al peso del pacco: XS ≤ 1 kg, S ≤ 2 kg, M ≤ 3 kg, L ≤ 5 kg e XL > 5 kg. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Una dimensione vuota usa la tariffa base. Una tariffa base di 0 significa spedizione gratuita. La riga * Default (all other countries) si applica ai paesi che non hanno una riga propria. Una riga senza alcun prezzo non viene salvata.

Other countries: la tariffa quando la tabella non ha un prezzo per il paese. Lascia vuoto per nascondere il corriere in quel caso.

Condizioni

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) da cui la spedizione è gratuita. In quel caso non viene fatta nessuna richiesta a ShipStation. Lascia vuoto per disattivare.

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

Minimum weight: il peso minimo del carrello, nell'unità di peso del tuo negozio, per mostrare il corriere. 0 significa nessun limite.

Maximum weight: il corriere viene nascosto sopra questo peso del carrello, nell'unità di peso del tuo negozio. 0 significa nessun limite.

Disponibilità senza zone di spedizione

Normalmente il corriere viene offerto nelle sue zone in Shipping > Carriers. In alternativa può essere offerto per paese.

Ignore shipping zones: offre il corriere per i paesi indicati sotto, che la loro zona sia assegnata o meno. Finché è attivo, il corriere viene aggiunto a tutte le zone, anche a quelle create in seguito. Disattivandolo, le zone aggiunte vengono rimosse.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi attivi del negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra le richieste a ShipStation in logs/vfd_shst_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche quando questa opzione è disattivata. API Key, API Secret e indirizzi dei clienti non vengono mai registrati. Il codice postale viene mascherato.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni, il corriere, il registro e il servizio ShipStation salvato con gli ordini. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nella fase di spedizione PrestaShop chiede al modulo il prezzo. 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 si applica la spedizione gratuita, il corriere viene mostrato con prezzo 0 e non viene inviata nessuna richiesta a ShipStation.

Il modulo invia poi a ShipStation il codice postale di partenza, il paese di destinazione, la provincia, la città e il codice postale, il peso del pacco e le dimensioni della scatola. Nessuna richiesta viene fatta prima che il cliente inserisca un codice postale. I paesi senza codici postali ricevono le tariffe di riserva. Gli articoli vengono impilati in un'unica scatola. Se un prodotto non ha dimensioni, il pacco viene quotato solo in base al peso.

ShipStation viene interrogato una volta per ogni codice corriere. Il modulo usa la tariffa consentita più economica, convertita nella valuta predefinita del tuo negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.

Ogni risposta viene memorizzata in cache per 1 ora. Quando ShipStation risponde senza una tariffa utilizzabile, la risposta viene ricordata per 10 minuti. Quando ShipStation rifiuta le chiavi o non è raggiungibile, le richieste vengono sospese per 5 minuti. Dopo un limite di richieste, la pausa segue l'orario di ripristino indicato da ShipStation. Il timeout della richiesta è di 12 secondi. Disattivare il modulo svuota le tariffe in cache.

Se non c'è una tariffa in tempo reale, il prezzo proviene dalla tabella delle tariffe di riserva e poi da Other countries. Se nessuna delle due si applica, il corriere viene nascosto. Il cliente non vede mai i testi di errore di ShipStation. I dettagli vanno nel registro di debug.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo tariffe. Non acquista etichette, non crea ordini o spedizioni in ShipStation, non traccia i pacchi e non gestisce i resi. Non ci sono punti di ritiro, né scelta tra più servizi al checkout, né verifica dell'indirizzo, assicurazione, conferma della firma, confezionamento in più pacchi o maggiorazione delle tariffe.

Ordini

Quando un ordine viene effettuato con una tariffa ShipStation in tempo reale, il servizio scelto viene salvato con l'ordine. La pagina dell'ordine nel back office lo mostra in un blocco ShipStation come Service, per esempio "USPS Ground Advantage - Package", così puoi creare l'etichetta corrispondente in ShipStation. I successivi ricalcoli del carrello non lo modificano. Gli ordini effettuati con tariffa di riserva o spedizione gratuita non hanno il blocco del servizio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox ShipStation è il primo blocco di Modules > Module Manager > VibeFox ShipStation > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 verificare 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-shipstation 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 indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il corriere ShipStation non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il negozio online 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 influenzati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

ShipStation non compare al checkout: verifica che la licenza sia attiva e che Enable ShipStation shipping sia attivo. In Shipping > Carriers verifica 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. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbiano un prezzo. Inoltre i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.

Il checkout mostra la tariffa di riserva invece della tariffa ShipStation: controlla gli avvisi in cima alla pagina del modulo (chiavi, codice corriere, codice postale di partenza, tasso di cambio). Attiva il Debug log, ricarica il checkout e guarda il campo Log. Il codice postale del cliente è obbligatorio. Nessuna richiesta viene fatta prima che venga inserito.

Quale codice corriere inserire: salva le impostazioni con la chiave e il secret. La pagina elenca i codici corriere del tuo account. Usane uno o più.

La verifica della connessione a ShipStation non è riuscita: il messaggio indica il motivo. Controlla API Key e API Secret, poi salva di nuovo per ripetere la verifica.

La tariffa non coincide con quella di ShipStation: il pacco viene costruito dai pesi e dalle dimensioni dei prodotti, con gli articoli impilati in una scatola. I prodotti senza dimensioni vengono quotati solo in base al peso. Le tariffe sono memorizzate in cache per 1 ora. Clicca su Save nella pagina del modulo per svuotare la cache.

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

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox ShipStation e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. La cache delle tariffe e il risultato della verifica della connessione vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia), e vengono rimosse le impostazioni, il registro e il servizio salvato con gli ordini. Se è disattivo, il corriere viene solo disattivato e vengono conservate le impostazioni e il servizio degli ordini effettuati. Reinstallare il modulo o eseguire un Reset riporta il corriere allo stato che aveva prima.

ShipStation è un marchio registrato del suo titolare. Questo modulo non è affiliato a ShipStation né approvato da ShipStation.