VibeFox Sameday Easybox 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.

Nome utente e password API Sameday: l'accesso API fa parte di un account business Sameday in Romania, Ungheria o Bulgaria. Chiedi al tuo account manager Sameday o al team di integrazione Sameday. Le credenziali sono spesso le stesse del portale eAWB (eawb.sameday.ro, .hu o .bg). Per l'API demo, Sameday fornisce credenziali di prova separate. Senza nome utente e password API il metodo non viene offerto, perché il cliente non potrebbe scegliere un locker.

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 clicca su Install Now. Puoi anche caricare la cartella vfd_sameday_easybox in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Sameday Easybox, oppure clicca 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 clicca su Activate.

5. Inserisci il tuo API username e la tua API password di Sameday, scegli il Sameday country e salva. La pagina dovrebbe mostrare "Connected to Sameday ... easybox lockers". Pickup point ed Easybox service vengono compilati dal tuo account.

6. Imposta i prezzi: Exchange rate of the estimate se la valuta del tuo negozio è diversa da quella di Sameday, e una riga di Country prices (per esempio * Default) oppure un Fallback cost.

7. Aggiungi VibeFox Sameday Easybox alla zona di spedizione del tuo paese Sameday in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Sameday Easybox. 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 i clienti vedono in questa zona. Lascialo vuoto per usare il Name globale.

Sopra le impostazioni la pagina mostra lo stato della connessione: l'host Sameday, il numero di locker easybox e quando l'elenco è stato aggiornato, oppure che Sameday ha rifiutato nome utente o password. Elenca anche i problemi di configurazione, per esempio credenziali mancanti, nessun prezzo o nessun tasso di cambio per la stima.

Tutti i prezzi e i limiti accettano la virgola o il punto come separatore decimale (4,99 o 4.99). Un numero non valido viene rifiutato con un messaggio.

Generale

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

Name: il nome del metodo di spedizione mostrato al cliente. Una zona può sostituirlo con il proprio Title. Default: Sameday easybox.

Tax status: Taxable aggiunge l'IVA di WooCommerce al costo di spedizione, None non la aggiunge.

Account Sameday (API)

Al salvataggio, il plugin accede a Sameday e carica i tuoi servizi, i punti di ritiro e l'elenco dei locker easybox. L'elenco viene aggiornato ogni giorno.

API username: il tuo nome utente API di Sameday.

API password: la tua password API di Sameday. Se Sameday la rifiuta, non viene riprovata per 10 minuti.

Sameday country: il paese del tuo account Sameday: Romania (api.sameday.ro) (predefinito), Hungary (api.sameday.hu) oppure Bulgaria (api.sameday.bg). Vengono offerti i suoi locker, e il metodo viene mostrato solo per questo paese di destinazione.

Test mode: usa l'API demo di Sameday con credenziali demo.

Prezzi

L'ordine di utilizzo è: la stima Sameday (quando sono impostati Pickup point ed Easybox service), poi la tabella dei prezzi per paese, poi il costo di riserva. I prezzi della tabella si inseriscono nella valuta del negozio.

Pickup point: il tuo punto di ritiro Sameday, dove Sameday ritira i pacchi. Dopo un accesso riuscito è un elenco dei punti di ritiro del tuo account, e quello predefinito viene scelto automaticamente. Necessario per la stima Sameday. Scegli - not set (price table only) - per usare solo la tabella dei prezzi.

Easybox service: il servizio Sameday per la consegna easybox, di solito "Locker NextDay" (codice LN), scelto automaticamente. Necessario per la stima Sameday.

Exchange rate of the estimate: Sameday calcola le stime nella valuta del tuo paese Sameday: RON, HUF o BGN (EUR per i negozi bulgari che vendono in euro). Se il tuo negozio vende in un'altra valuta, inserisci il valore di 1 unità della valuta Sameday nella valuta del tuo negozio, per esempio 0.20. Senza questo valore la stima non viene usata e si applica la tabella dei prezzi. Lev ed euro vengono convertiti automaticamente al tasso fisso.

Table price: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli spedibili. Questo vale per il prezzo della tabella e per il costo di riserva. La stima Sameday riguarda sempre l'intero pacco.

Country prices: un prezzo per paese di destinazione e peso del pacco. Clicca su + Add country per aggiungere una riga e sulla croce per eliminarne una. Ogni riga ha una colonna Price e colonne di peso: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL oltre 5 kg. Una colonna di peso lasciata a 0 usa la colonna Price. La riga * Default viene usata per i paesi senza una riga propria. Una nuova riga parte come * Default con tutti i prezzi a 0, che significa spedizione gratuita. Scegli il paese e inserisci i prezzi prima di salvare, oppure elimina la riga. Se lo stesso paese compare in due righe, al salvataggio viene mantenuta solo la prima. Se una cella non è un numero valido, la tabella non viene salvata.

Fallback cost: usato quando non c'è una stima Sameday e la tabella dei paesi non ha una riga per la destinazione. Lascialo vuoto per non offrire il metodo in quel caso.

Free shipping from: il subtotale del carrello (dopo gli sconti, senza IVA) da cui la consegna easybox è gratuita. Si applica solo dove viene trovato un prezzo: una riga di paese, la riga * Default o il costo di riserva (in tal caso non viene richiesta alcuna stima), oppure la stima Sameday. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. Il peso viene convertito dall'unità di peso del tuo negozio. Vuoto o 0 significa nessun limite.

Maximum weight (kg): i pacchi più pesanti di questo valore non ricevono l'offerta di consegna easybox. Default: 30. Controlla il limite del tuo contratto Sameday e le dimensioni dei box easybox. Vuoto o 0 significa nessun limite.

Minimum cart subtotal: offri il metodo solo quando il subtotale del carrello (dopo gli sconti, senza IVA) raggiunge questo importo.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.

Ignore shipping zones: quando è attivo, il metodo viene offerto per i paesi selezionati qui sotto, anche se non è stato aggiunto alla zona di spedizione corrispondente. Quando è disattivo, viene offerto solo nelle zone a cui è stato aggiunto.

Countries (ignore zones mode): i paesi di destinazione per questa modalità. Lascialo vuoto per usare il paese Sameday. I paesi diversi dal paese Sameday vengono ignorati. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe, le chiamate API e le scelte dei locker in WooCommerce > Status > Logs (origine "vfd-sameday-easybox"). Gli errori API vengono sempre registrati. Non vengono registrati password, token o dati personali dei clienti. Disattiva il log quando hai finito.

Remove data on uninstall: quando è attivo, eliminare il plugin rimuove le impostazioni e le istanze di questo metodo nelle zone. Disattivare il plugin non cancella mai nulla. Il locker salvato negli ordini viene sempre conservato.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica le condizioni: paese di consegna del tuo account Sameday, credenziali API e un elenco di locker utilizzabile, peso del carrello, subtotale minimo del carrello e classi di spedizione escluse. Poi cerca un prezzo: la stima Sameday, la tabella dei paesi, il costo di riserva. Se non c'è un prezzo, il metodo viene nascosto. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi.

Altrimenti il plugin chiede a Sameday una stima, una volta che il cliente ha inserito una città e una provincia. Invia il tuo punto di ritiro e servizio, il peso del pacco e l'indirizzo, la città, la provincia e il CAP del cliente. Non vengono inviati nome, e-mail o numero di telefono. Bucarest viene inviata come "Sector 1", come nel plugin ufficiale Sameday. La stima viene convertita nella valuta del tuo negozio. Se non c'è una stima (non configurata, nessuna città o provincia ancora, errore, nessun tasso di cambio), il prezzo arriva dalla tabella dei paesi, poi dal costo di riserva. Se non c'è un prezzo, il metodo viene nascosto.

I problemi di Sameday non bloccano mai il checkout. La stima viene memorizzata nella cache per 1 ora. Un errore viene memorizzato nella cache per 10 minuti. Dopo un timeout o un errore del server, non viene richiesta alcuna stima per 5 minuti. Le richieste scadono dopo 15 secondi. L'elenco dei locker viene letto dal tuo server, non da Sameday, durante il checkout.

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

Il plugin non crea AWB (spedizioni), non stampa etichette, non traccia i pacchi e non gestisce il contrassegno. Non prevede la consegna a domicilio con corriere né un widget mappa di Sameday. Crea l'AWB nel portale Sameday eAWB o nel tuo strumento abituale con l'ID del locker mostrato sull'ordine.

Scelta del locker

Quando il cliente seleziona il metodo, sotto compare un blocco easybox locker con due elenchi: - Select city - e - Select easybox locker -. La città del cliente viene preselezionata se ha dei locker. Ogni locker mostra il proprio nome e indirizzo. La scelta viene ricordata quando il checkout si aggiorna o la pagina viene ricaricata.

Il locker è obbligatorio. Senza, il checkout si ferma con il messaggio "Please choose a Sameday easybox locker.". Il server verifica che il locker scelto sia nell'elenco, sia nel checkout classico sia in quello a blocchi. Un ID di locker falsificato o rimosso viene rifiutato con il messaggio "The selected easybox locker is not available any more. Please choose another easybox locker.". Nome e indirizzo salvati con l'ordine provengono dall'elenco, non dal browser.

Schermata di gestione dell'ordine: Sameday easybox locker con nome e indirizzo e il Locker ID per l'AWB Sameday, sotto l'indirizzo di spedizione. Se un ordine easybox non ha un locker, la schermata indica "No easybox locker was selected for this order.".

Pagina di ringraziamento e visualizzazione dell'ordine: Sameday easybox locker: con nome e indirizzo.

E-mail degli ordini: nome e indirizzo del locker nelle e-mail HTML e in testo semplice. Le e-mail per l'amministratore includono anche il Locker ID.

Nel database il locker è memorizzato nei metadati dell'ordine _vfd_sdeb_locker_id (l'ID del locker Sameday per l'AWB) e _vfd_sdeb_locker_name (nome e indirizzo).

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 Sameday Easybox. Incolla la chiave in License key e clicca 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, Sameday easybox non viene mostrato ai clienti al checkout. Gli amministratori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (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 assistenza richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Sameday easybox non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che nome utente e password API siano inseriti e che la pagina delle impostazioni indichi "Connected to Sameday", e che il paese di destinazione sia il paese del tuo account Sameday. Verifica che sia disponibile un prezzo (stima Sameday, riga del paese, riga * Default o Fallback cost), i limiti di peso e subtotale, Excluded shipping classes, e che il metodo sia aggiunto alla zona corrispondente (oppure che Ignore shipping zones sia attivo). Attiva Debug log per vedere il motivo in WooCommerce > Status > Logs.

Sameday ha rifiutato nome utente o password API: controllali e salva di nuovo. Le credenziali demo funzionano solo con Test mode attivo, quelle di produzione solo con il test disattivato. Nel frattempo viene offerto l'elenco dei locker salvato, se presente, e la stima Sameday non viene usata.

Il prezzo arriva dalla mia tabella, non da Sameday: la stima richiede un Pickup point, l'Easybox service e, quando la valuta del tuo negozio è diversa da quella di Sameday, l'Exchange rate of the estimate. Viene richiesta solo dopo che il cliente ha inserito una città e una provincia. Quando Sameday non è raggiungibile o restituisce un errore, si usano la tabella o il costo di riserva; il motivo è nel log.

L'elenco dei locker è vecchio o manca: salva le impostazioni. L'elenco viene ricaricato quando è vuoto, ha più di un'ora o l'ultimo caricamento non è riuscito. Se un aggiornamento fallisce, si usa l'elenco precedente e lo stato lo indica.

La spedizione è gratuita per errore: controlla in Country prices le righe con un Price di 0, soprattutto una riga * Default aggiunta con + Add country e lasciata vuota.

Locker transfrontalieri: gli sviluppatori possono aggiungere paesi di destinazione con il filtro vfd_sdeb_countries. L'elenco dei locker è sempre quello del tuo account.

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 clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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 e interrompe solo l'aggiornamento giornaliero dell'elenco dei locker. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi, insieme all'elenco dei locker salvato, al risultato del controllo dell'account e a tutte le cache. 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 righe di spedizione e il locker salvato.

Sameday ed easybox sono marchi dei rispettivi proprietari. Questo plugin non è affiliato a Sameday né approvato da Sameday.