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

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 test separate. Senza nome utente e password API il corriere non viene offerto, perché il cliente non potrebbe scegliere un locker.

Contee nel modulo dell'indirizzo: la stima Sameday richiede la contea dell'indirizzo di consegna. PrestaShop non ha contee per Romania, Ungheria e Bulgaria per impostazione predefinita. Il modulo può aggiungerle per te (vedi Lockers easybox più sotto). Senza di esse, i prezzi provengono dalla tua tabella o dal costo di riserva.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Sameday Easybox nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in alto nella pagina di configurazione e clicca su Activate (vedi Chiave di licenza).

4. Inserisci il tuo API username e la tua API password di Sameday, scegli il Sameday country e clicca su Save. La pagina dovrebbe mostrare "Connesso a Sameday ... locker easybox". Il Pickup point e l'Easybox service vengono compilati dal tuo account.

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

6. Se la pagina indica che il negozio non ha contee per il tuo paese Sameday, clicca su Add counties nella sezione Lockers easybox.

All'installazione il modulo crea il corriere Sameday easybox con il testo dei tempi di consegna Delivery to a Sameday easybox locker. È assegnato a tutti i gruppi di clienti e alla zona della Romania. Puoi modificare zone, gruppi di clienti, tempi di consegna e logo in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina Configure del modulo, in sei sezioni. Il pulsante Save di qualsiasi sezione salva l'intera pagina.

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 il nome utente o la password. Elenca inoltre i problemi di configurazione, ad esempio credenziali mancanti, nessun prezzo, nessun tasso di cambio per la stima, nessuna contea, un'unità di peso del negozio che il modulo non riconosce, o che il corriere non è stato trovato.

Tutti i prezzi e i limiti accettano la virgola o il punto come separatore decimale (4,99 o 4.99). Un numero non valido o negativo non viene salvato: un avviso indica il campo e resta il valore precedente.

Generale

Enable/Disable: attiva o disattiva il corriere. Equivale allo stato del corriere in Shipping > Carriers.

Name: il nome del metodo di spedizione mostrato al cliente (il nome del corriere). Predefinito: Sameday easybox.

Tax status: None significa che il prezzo è definitivo. Taxable con una regola fiscale fa aggiungere a PrestaShop l'imposta di spedizione sopra il prezzo.

Account Sameday (API)

Al salvataggio il modulo 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 Sameday.

API password: la tua password API Sameday. Non viene più mostrata: lascia il campo vuoto per mantenere quella salvata. Svuotare il nome utente rimuove anche la password. 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) o Bulgaria (api.sameday.bg). Sono offerti i suoi locker e il corriere viene mostrato solo per questo paese di destinazione. Quando lo cambi, il corriere viene collegato anche alla zona del nuovo paese.

Test mode: usa l'API demo di Sameday (sameday-api.demo.zitec.com) con credenziali demo.

Prezzi

L'ordine di utilizzo è: prima la stima Sameday (quando Pickup point e Easybox service sono impostati), poi la tabella dei prezzi per paese e infine il costo di riserva. I prezzi della tabella si inseriscono nella valuta predefinita del negozio. I clienti che pagano in un'altra valuta vedono il prezzo convertito.

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 in easybox, di solito "Locker NextDay" (codice LN), scelto automaticamente. Necessario per la stima Sameday.

Exchange rate of the estimate: Sameday calcola la stima 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 negozio, ad esempio 0.20. Il tasso deve essere superiore a 0. Senza di esso 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. Questo vale per il prezzo della tabella e per il costo di riserva. La stima Sameday è sempre per l'intero pacco.

Country prices: un prezzo per paese di destinazione e peso del pacco. Clicca su + Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Ogni riga ha una colonna Price e le colonne di peso: XS fino a 1 kg, S da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 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 inizia come * Default con tutti i prezzi a 0, cioè spedizione gratuita. Scegli il paese e inserisci i prezzi prima di salvare, oppure rimuovi la riga. Se lo stesso paese compare in due righe, al salvataggio resta solo la prima e un avviso lo segnala. Se una cella non è un numero valido, la tabella non viene salvata.

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

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, senza tasse) da cui la consegna in easybox è gratuita. Quando il subtotale lo raggiunge, il corriere viene offerto senza costi e non viene richiesto alcun prezzo. Lascia vuoto per non offrire mai la spedizione gratuita.

Disponibilità

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

Maximum weight (kg): i pacchi più pesanti di questo non ricevono la consegna in easybox. Predefinito: 30. Controlla il limite del tuo contratto Sameday e le dimensioni dei box easybox. Vuoto o 0 significa nessun limite. Un peso minimo superiore al peso massimo non viene salvato: un avviso lo segnala e restano i valori precedenti.

Minimum cart subtotal: offri il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, senza tasse) raggiunge questo importo.

Ignore shipping zones: quando è attivo, il corriere viene offerto per i paesi selezionati sotto (il paese Sameday se l'elenco è vuoto), anche se la loro zona non è impostata per il corriere. Il corriere viene poi collegato a tutte le zone attive, anche a quelle create in seguito. Quando lo disattivi, il corriere riprende le zone che aveva prima. Quando è disattivo, il corriere viene offerto solo nelle sue zone in Shipping > Carriers.

Countries (ignore zones mode): i paesi di destinazione per questa modalità. I paesi diversi dal paese Sameday vengono saltati, e la pagina li segnala. Questo campo si usa solo quando Ignore shipping zones è attivo.

Lockers easybox

Locker list: mostra quanti locker easybox in quante città sono caricati e da quando. Refresh the locker list now li ricarica. L'elenco viene aggiornato al salvataggio delle impostazioni e, quando è più vecchio di un giorno, dopo una richiesta di checkout. Per un aggiornamento giornaliero fisso, richiama una volta al giorno l'Cron URL mostrato qui da un cron job del tuo server. L'URL contiene un token segreto. Senza il token risponde con un errore e non contatta Sameday.

Counties: la stima Sameday richiede la contea dell'indirizzo. Se PrestaShop non ha contee (states) per il tuo paese Sameday, clicca su Add counties. Il modulo aggiunge le contee di Romania, Ungheria o Bulgaria e il campo contea al modulo dell'indirizzo di quel paese. Le contee già presenti non vengono aggiunte due volte. Quando sono in place, la pagina ne mostra il numero.

Avanzate

Debug log: scrive i calcoli delle tariffe, le chiamate API e le scelte dei locker nel file logs/vfd_sdeb_debug.log.php nella cartella del modulo, che non è leggibile dal web. Gli errori API vengono sempre registrati. Nessuna password, token o dato personale del cliente viene registrato. Il campo Log qui sotto mostra la fine del file, con un pulsante Clear log. Disattiva il log quando hai finito.

Remove data on uninstall: quando è attivo, disinstallando il modulo vengono eliminate le impostazioni e il corriere. Senza, disinstallare si limita a disattivare il corriere. L'elenco dei locker e le cache vengono sempre rimossi. Il locker salvato negli ordini viene sempre conservato.

Come funziona al checkout

Quando il negozio calcola la spedizione per un carrello, PrestaShop chiede al modulo il prezzo del corriere Sameday easybox. Il modulo verifica le condizioni: paese di consegna del tuo account Sameday, credenziali API e un elenco di locker utilizzabile, i paesi di Ignore shipping zones, peso del carrello e subtotale minimo. I prodotti che non richiedono spedizione (prodotti virtuali) non vengono conteggiati. Se si applica la spedizione gratuita, il cliente vede il corriere senza costi.

Altrimenti il modulo chiede a Sameday una stima, una volta che il cliente ha inserito una città e una contea. Invia il tuo punto di ritiro e servizio, il peso del pacco e la via, la città, la contea e il codice postale dell'indirizzo del cliente. Non viene inviato alcun nome, e-mail o numero di telefono. Bucarest viene inviata come "Sector 1", come fa il plugin ufficiale di Sameday. La stima viene convertita nella valuta del negozio. Se non c'è una stima (non configurata, nessuna città o contea ancora, errore, nessun tasso di cambio), il prezzo proviene dalla tabella del paese, poi dal costo di riserva. Se non c'è un prezzo, il corriere viene nascosto.

I problemi di Sameday non bloccano mai il checkout. La stima viene memorizzata nella cache per 1 ora. Un errore viene memorizzato 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 corriere funziona nel passaggio di spedizione del tema Classic (PrestaShop 8) e del tema Hummingbird (PrestaShop 9).

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

Punti di ritiro

Quando il cliente seleziona il corriere, sotto compare un blocco easybox locker con due elenchi: - Select city - e - Select easybox locker -. La città dell'indirizzo di consegna viene preselezionata quando ha dei locker. Ogni locker mostra il nome e l'indirizzo. La scelta viene salvata subito nel carrello, quindi resta quando il passaggio di spedizione si aggiorna o la pagina viene ricaricata.

Il locker è obbligatorio. Senza un locker il cliente non può proseguire e vede "Scegli un locker easybox Sameday." Quando il cliente clicca su Continue, il server verifica che il locker scelto sia nell'elenco. Un ID di locker falsificato o rimosso viene rifiutato con "Il locker easybox selezionato non è più disponibile. Scegline un altro." Se l'elenco non può essere caricato, il cliente vede "Impossibile caricare i locker easybox. Riprova tra poco o scegli un altro metodo di spedizione." Nome e indirizzo salvati con l'ordine provengono dall'elenco, non dal browser. Una volta effettuato l'ordine, il suo locker non cambia più.

Pagina dell'ordine nel back office: un blocco Sameday easybox locker con nome, indirizzo e Locker ID per l'AWB Sameday. Se un ordine easybox non ha un locker, il blocco indica "Nessun locker easybox è stato selezionato per questo ordine."

Pagine di conferma e cronologia ordini: Sameday easybox locker: con nome e indirizzo.

E-mail degli ordini: nome e indirizzo del locker vengono aggiunti al corriere nell'e-mail di conferma dell'ordine. La nuova e-mail d'ordine al negozio (modulo Mail alerts) include anche il Locker ID.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Sameday Easybox è il primo blocco di Modules > Module Manager > VibeFox Sameday Easybox > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (ad 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-sameday-easybox 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, ad 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 dominio: il dominio 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 Sameday easybox non viene mostrato ai clienti al checkout e non viene richiesto né calcolato alcun prezzo. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche a 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 vengono toccati.

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 il modulo rimuove sempre la chiave di licenza e lo stato della licenza. Reset di questo modulo non cancella i dati, quindi chiave e stato vengono conservati.

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, che la pagina Configure indichi "Connesso a Sameday" e che il paese di destinazione sia quello del tuo account Sameday. Verifica che sia disponibile un prezzo (stima Sameday, riga del paese, riga * Default o Fallback cost) e i limiti di peso e subtotale. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo, oppure attiva Ignore shipping zones. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto. Attiva Debug log per vedere il motivo nel campo Log.

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 esso disattivo. Nel frattempo viene offerto l'elenco di locker salvato, se presente, e la stima Sameday non viene usata.

Il prezzo viene dalla mia tabella, non da Sameday: la stima richiede un Pickup point, l'Easybox service, contee nel modulo dell'indirizzo e, quando la valuta del 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 contea. Quando Sameday non è raggiungibile o restituisce un errore, si usa la tabella o il costo di riserva; il motivo è nel log.

L'elenco dei locker è vecchio o mancante: clicca su Refresh the locker list now o salva le impostazioni. Se un aggiornamento fallisce, si usa l'elenco precedente e lo stato lo indica. Se il negozio è in modalità manutenzione, l'URL cron è bloccato come il resto del negozio, a meno che l'IP del server cron non sia consentito.

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

I limiti di peso o le colonne di peso non corrispondono: se la pagina avvisa che l'unità di peso del negozio non è riconosciuta, imposta kg, g, lb o oz in International > Localization (Local units).

La pagina dice che il corriere Sameday easybox non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Il reset mantiene le impostazioni e lo stato di un corriere esistente.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox Sameday Easybox e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. L'elenco dei locker salvato, il risultato della verifica dell'account e tutte le cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e le impostazioni e il log vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallare il modulo restituisce al corriere salvato lo stato che aveva. Gli ordini esistenti conservano il locker salvato.

Sameday e easybox sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Sameday.