VibeFox ShipStation for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

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

PHP: 8.0 o successivo.

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 plugin usa l'API V1 di ShipStation (API Key e API Secret). Gli account ShipStation API V2 con una sola chiave API non sono supportati. Senza chiavi vengono usate solo le tariffe di riserva.

Chiave di licenza VibeFox: acquistata 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. Puoi anche caricare la cartella vfd_shipstation in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox ShipStation, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Incolla API Key e API Secret, inserisci il CAP di partenza della spedizione e salva. La pagina elenca ora i codici corriere del tuo account. Inserisci quello o quelli che ti interessano in Carrier codes e salva di nuovo.

6. Se la valuta del tuo negozio non è quella dell'account ShipStation, imposta Exchange rate.

7. Facoltativamente, compila le tariffe di riserva.

8. Aggiungi VibeFox ShipStation 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 ShipStation. Si applicano a 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 Name generale.

Ogni volta che salvi le impostazioni, le tariffe ShipStation in cache vengono cancellate e API Key e API Secret vengono verificate. 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 sopra le impostazioni ti dicono quando le tariffe in tempo reale non possono funzionare: chiavi mancanti, codice corriere mancante, CAP di partenza mancante, tasso di cambio mancante, verifica della connessione non riuscita o codici corriere non collegati al tuo account.

Generale

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

Name: il nome del metodo di spedizione mostrato al checkout. Una zona può sostituirlo con il proprio Title. Predefinito: ShipStation Shipping.

Account ShipStation

API Key: l'API Key da ShipStation > Settings > Account > API Settings.

API Secret: l'API Secret della stessa pagina.

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. 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. Lascialo vuoto per mostrare il servizio più economico dei corrieri indicati sopra.

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

Spedizione da

Ship-from postal code: obbligatorio per le tariffe in tempo reale. ShipStation calcola le tariffe solo in base al CAP e deve trovarsi nel paese del tuo account ShipStation. Lascialo vuoto per usare il CAP del negozio impostato in WooCommerce > Settings > General.

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 del tuo negozio, per esempio 0.92. Serve solo se la valuta del negozio è diversa da quella dell'account. Senza di esso non vengono usate le tariffe in tempo reale e si applicano le tariffe di riserva. I tassi di cambio non vengono aggiornati automaticamente.

Tax status: Taxable consente a WooCommerce di aggiungere imposte sulla spedizione secondo le tue regole fiscali; None non le aggiunge. Le tariffe ShipStation non includono l'imposta sulle vendite.

Tariffe di riserva (usate quando non c'è una tariffa in tempo reale: senza chiavi API, ShipStation non raggiungibile o nessuna tariffa dei corrieri per l'indirizzo; prezzi nella valuta del tuo negozio; lascia vuoti la tabella e Other countries per nascondere il metodo in questo 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. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. 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 senza una riga propria.

Other countries: la tariffa quando la tabella non ha un prezzo per il paese. Lascialo vuoto per nascondere il metodo in questo caso.

Condizioni

Free shipping from: il subtotale del carrello a partire dal quale la spedizione è gratuita. In quel caso non viene fatta nessuna richiesta a ShipStation. Lascialo vuoto per disattivarlo.

Minimum subtotal: mostra il metodo solo se il subtotale del carrello è almeno pari a questo importo. Lascialo vuoto per mostrarlo sempre.

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

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

Disabled shipping classes: nasconde il metodo se il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati sotto, che sia o no aggiunto a una zona.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui il negozio spedisce. Questo campo viene usato solo quando Ignore shipping zones è attivo. Un metodo aggiunto a una zona di spedizione funziona sempre per i paesi di quella zona.

Avanzate

Debug log: registra le richieste a ShipStation in WooCommerce > Status > Logs, origine vfd-shipstation. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. API Key, API Secret e indirizzi dei clienti non vengono mai registrati. Il CAP viene mascherato.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i suoi metodi nelle zone di spedizione. La disattivazione del plugin non cancella mai le impostazioni.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica prima le condizioni: peso del carrello, subtotale minimo e classi di spedizione disattivate. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo 0 e non viene inviata nessuna richiesta a ShipStation.

Il plugin invia poi a ShipStation il CAP di partenza, il paese di destinazione, lo stato, la città e il CAP di destinazione, il peso del pacco e le dimensioni della scatola. Nessuna richiesta viene fatta finché il cliente non ha inserito un CAP. I paesi senza CAP ricevono le tariffe di riserva. Pesi e dimensioni vengono convertiti dalle unità del tuo negozio. Gli articoli vengono impilati in una scatola. Se un prodotto non ha dimensioni, il pacco viene calcolato solo in base al peso.

ShipStation viene interrogato una volta per ogni codice corriere. Il plugin mostra la tariffa consentita più economica, convertita nella valuta del tuo negozio, sotto il nome del metodo.

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 reset indicato da ShipStation. Il timeout della richiesta è di 12 secondi. La disattivazione del plugin cancella le tariffe in cache.

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

Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin calcola solo le 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, suddivisione in più pacchi o maggiorazione delle tariffe.

Ordini

La riga di spedizione dell'ordine salva il Service scelto, per esempio "USPS Ground Advantage - Package". Lo vedi nella schermata dell'ordine nell'area di amministrazione e puoi creare l'etichetta corrispondente in ShipStation.

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 ShipStation. 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 verificare 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 di dominio. Liberalo dal tuo account vibefox.net.

Senza una chiave attiva, ShipStation 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 testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin 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 verificato di nuovo automaticamente in background.

Risoluzione dei problemi

ShipStation non compare al checkout: verifica 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 Disabled shipping classes. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbia un prezzo.

Il checkout mostra la tariffa di riserva invece della tariffa ShipStation: controlla gli avvisi in cima alla pagina delle impostazioni (chiavi, codice corriere, CAP di partenza, tasso di cambio). Attiva Debug log e apri WooCommerce > Status > Logs, origine vfd-shipstation. Serve il CAP del cliente. Nessuna richiesta viene fatta finché non viene inserito.

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

La tariffa non corrisponde a ShipStation: il pacco viene costruito dai pesi e dalle dimensioni dei prodotti, con gli articoli impilati in una scatola. I prodotti senza dimensioni vengono calcolati solo in base al peso. Le tariffe sono memorizzate in cache per 1 ora. Salva le impostazioni per svuotare la cache.

Per gli sviluppatori: i filtri vfd_shst_rate_request, vfd_shst_selected_rate e vfd_shst_api_url modificano la richiesta di tariffa per corriere, la tariffa scelta e l'URL base dell'API.

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

La disattivazione del plugin mantiene le impostazioni e cancella solo le tariffe in cache. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, le tariffe in cache e l'elenco dei corrieri salvato vengono sempre rimossi. Impostazioni e metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione.

ShipStation è un marchio del suo rispettivo proprietario. Questo plugin non è affiliato a ShipStation né approvato da ShipStation.