VibeFox EasyPost for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Senza di esse il modulo non si installa.

Account EasyPost (solo per le tariffe in tempo reale): crea un account sul sito di EasyPost, collega i tuoi account dei corrieri (USPS, UPS, FedEx e altri) nella dashboard di EasyPost e copia la chiave API da EasyPost Dashboard > Account Settings > API Keys. EasyPost addebita le etichette acquistate, non le richieste di tariffe. Se usi solo le tariffe di riserva, non ti serve un account EasyPost.

Prodotti: i prodotti devono avere un peso e, meglio ancora, anche le dimensioni.

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova VibeFox EasyPost più tardi nell'elenco dei moduli e fai clic su Configure.

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

4. Incolla la tua chiave API di EasyPost e compila l'indirizzo Ship from. Il codice postale è obbligatorio per le tariffe in tempo reale.

5. Se la valuta predefinita non è l'USD, inserisci l'USD exchange rate. Facoltativamente inserisci le tariffe di riserva (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere EasyPost Shipping con il testo dei tempi di consegna Live carrier rate (EasyPost). Il corriere viene 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 prezzi lì: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox EasyPost > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe EasyPost memorizzate nella cache.

In cima alla pagina il modulo mostra avvisi quando le tariffe in tempo reale non possono essere usate: nessuna chiave API (con o senza tariffe di riserva), nessun codice postale o paese di spedizione, oppure una valuta predefinita diversa dall'USD senza tasso di cambio. Compare anche una nota quando è impostata una chiave API di test, un errore quando il corriere del modulo è stato eliminato, e un avviso quando l'unità di peso o di dimensione del tuo negozio (International > Localization) non è tra quelle che il modulo conosce (kg, g, lb, oz; cm, mm, m, in).

Al salvataggio, un valore che non è un numero (o è negativo) non viene salvato: un avviso indica il campo e resta il valore precedente. Lo stesso accade quando USD exchange rate è 0, o quando Minimum weight è maggiore di Maximum weight.

Generale

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

Name: il nome del corriere mostrato al cliente nel checkout, massimo 64 caratteri (un nome più lungo viene rifiutato e non si salva nulla). Predefinito: EasyPost Shipping. Se il nome è vuoto o contiene caratteri che PrestaShop non consente in un nome di corriere, viene usato il nome predefinito.

Account EasyPost

API key: la tua chiave API di EasyPost da EasyPost Dashboard > Account Settings > API Keys. Una chiave di produzione (inizia con EZAK) restituisce tariffe reali. Una chiave di test (inizia con EZTK) restituisce tariffe di prova di EasyPost; usala solo per i test. Dopo il salvataggio il campo resta vuoto e mostra la chiave salvata mascherata, per esempio EZAK******abcd. Lascia il campo vuoto per mantenerla. Inserisci un nuovo valore solo per cambiarla.

Remove the saved API key: spunta questa casella e fai clic su Save per eliminare la chiave salvata.

Allowed carriers / services: facoltativo, separato da virgole. Inserisci un corriere (USPS) oppure un corriere e un servizio (USPS:Priority, UPS:Ground) così come li chiama EasyPost. Viene mostrata la tariffa consentita più economica. Lascia vuoto per mostrare la tariffa più economica di qualsiasi corriere.

Spedizione da

L'indirizzo da cui vengono spediti i tuoi pacchi. Se il Country è il paese del tuo negozio, i campi vuoti vengono compilati dall'indirizzo del negozio in Shop Parameters > Contact > Stores (e il nome del mittente dal nome del negozio).

Sender name / company: il nome del mittente o dell'azienda.

Street address: la via dell'indirizzo di spedizione.

City: la città dell'indirizzo di spedizione.

State: il codice dello stato a due lettere, per esempio CA o NY.

ZIP code: il codice postale dell'indirizzo di spedizione. Obbligatorio per le tariffe in tempo reale.

Country: il paese da cui spedisci. Predefinito: United States.

Tariffe

Parcels: come il carrello viene inviato a EasyPost.

I pesi vengono convertiti dall'unità del tuo negozio in once (minimo 1 oz) e le dimensioni in pollici. Se un prodotto non ha dimensioni, il pacco viene tariffato solo in base al peso.

USD exchange rate: le tariffe EasyPost sono in USD. Inserisci il prezzo di 1 USD nella tua valuta predefinita, per esempio 0.92. Senza questo valore non vengono usate le tariffe in tempo reale, solo quelle di riserva. Non serve se la valuta predefinita è l'USD. I negozi in USD e CAD chiedono a EasyPost di quotare nella propria valuta. Sono accettati sia il punto sia la virgola come separatore decimale.

Tax: la regola fiscale del corriere, oppure No tax. Le tariffe EasyPost non includono l'imposta sulle vendite. Scegli le regole fiscali che si applicano alla spedizione.

Tariffe di riserva

Usate quando non c'è una tariffa in tempo reale: nessuna chiave API, EasyPost non raggiungibile, chiave rifiutata o nessun corriere con una tariffa per l'indirizzo. I prezzi sono nella valuta predefinita, IVA esclusa. Lascia vuoti entrambi i campi per nascondere il corriere in questo caso.

Country prices: una riga per paese: codice paese di due lettere, due punti e il prezzo, per esempio US:9.99. Le righe in un altro formato vengono ignorate e riportate in un avviso al salvataggio.

Other countries: il prezzo per i paesi non presenti nell'elenco sopra. Lascia vuoto per nascondere il corriere per questi paesi.

Condizioni

Free shipping from: il subtotale del carrello (prodotti da spedire, dopo gli sconti, prima delle imposte, nella valuta predefinita) a partire dal quale la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta a EasyPost. Lascia vuoto per disattivare.

Minimum subtotal: mostra il corriere solo se il subtotale del carrello (prodotti da spedire, dopo gli sconti, prima delle imposte) è almeno pari a questo importo. Lascia vuoto per mostrarlo sempre.

Minimum weight: nasconde il corriere quando il carrello pesa meno, nell'unità di peso del tuo negozio (indicata nell'etichetta del campo). 0 significa nessun limite.

Maximum weight: nasconde il corriere quando il carrello pesa di più, nell'unità di peso del tuo negozio. 0 significa nessun limite.

Disponibilità senza zone di spedizione

Normalmente il corriere viene offerto nelle zone a lui assegnate in Shipping > Carriers. In alternativa può essere offerto per paese, indipendentemente dalle zone.

Ignore shipping zones: offre il corriere per i paesi indicati sotto, che la loro zona sia o non sia assegnata al corriere. Quando salvi con questa opzione attiva, il corriere viene assegnato a tutte le zone, comprese quelle create in seguito. Quando la disattivi, il corriere riprende le sue zone precedenti.

Countries: i paesi di destinazione per questa modalità. Usa Ctrl+clic per selezionarne più di uno. Lascia vuoto per usare tutti i paesi attivi del tuo negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive le richieste EasyPost in modules/vfd_easypost/logs/vfd_ep.log.php. Il file non può essere aperto dal web e viene ruotato a 5 MB. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attiva, disinstallando il modulo vengono eliminati le sue impostazioni, le tabelle e il registro. Disattivare il modulo non elimina mai le impostazioni.

Log: il pannello sotto le impostazioni mostra le ultime 100 righe del registro. Fai clic su Clear log per svuotarlo.

Come funziona nel checkout

Nella fase di spedizione PrestaShop chiede al modulo il prezzo EasyPost. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima le condizioni: paese di destinazione (con Ignore shipping zones), peso del carrello e subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a EasyPost.

Altrimenti il modulo invia a EasyPost l'indirizzo di spedizione, l'indirizzo di consegna e il pacco, e riceve le tariffe di tutti i tuoi account dei corrieri. Sceglie la tariffa consentita più economica, la converte nella valuta predefinita e la mostra nella valuta del carrello del cliente. Per i paesi che richiedono un codice postale, la richiesta viene fatta solo quando l'indirizzo di consegna lo contiene. Finché il cliente non ha inserito un indirizzo, si conosce solo il paese del visitatore, quindi nei paesi che richiedono un codice postale viene applicata la tariffa di riserva fino all'inserimento dell'indirizzo.

Ogni risposta viene memorizzata nella cache per 1 ora per lo stesso indirizzo e lo stesso pacco. Un indirizzo senza tariffe utilizzabili viene ricordato per 10 minuti. Dopo un timeout, una chiave rifiutata, un limite di richieste o un errore del server EasyPost, per 5 minuti non viene inviata alcuna richiesta. Il timeout dell'API è di 10 secondi. In tutti questi casi il cliente non vede alcun errore: viene usata la tariffa di riserva oppure, se non c'è, il corriere viene nascosto. Il motivo viene scritto nel registro.

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 le tariffe. Non acquista etichette, non traccia i pacchi, non convalida gli indirizzi, non offre punti di ritiro o consegna e non aggiunge opzioni di assicurazione o firma. Mostra una sola opzione (la tariffa consentita più economica), non un elenco di servizi. Non c'è confezionamento in scatole oltre all'accorpamento degli articoli in un unico pacco, né maggiorazioni sulla tariffa o commissioni di gestione.

Ordini

Quando viene effettuato un ordine con il corriere EasyPost, la tariffa mostrata nel checkout viene conservata con l'ordine. La pagina dell'ordine nel back office mostra il blocco EasyPost shipping:

Carrier / service: il corriere e il servizio EasyPost della tariffa, per esempio USPS Priority. In modalità un pacco per articolo vengono elencati tutti i servizi utilizzati.

Estimated delivery days: i giorni di consegna restituiti da EasyPost (solo in modalità un pacco per ordine, quando EasyPost li restituisce).

Price source: Live EasyPost rate, Fallback price (no live rate) oppure Free shipping threshold.

Calculated price (excl. tax): il prezzo nella valuta predefinita.

Le modifiche successive al carrello nel back office non cambiano questi valori. Usali per acquistare l'etichetta nel tuo account EasyPost. Le tariffe dei carrelli abbandonati vengono eliminate dopo 30 giorni.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox EasyPost è il primo blocco di Modules > Module Manager > VibeFox EasyPost > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo l'attivazione, 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-easypost 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 o License expired on seguito da una data. Dopo che l'indirizzo del negozio cambia, 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. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il corriere EasyPost non viene mostrato ai clienti nel checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi testarlo nel 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 il rinnovo. Lo stato viene controllato 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

EasyPost non compare nel checkout: verifica che la licenza sia attiva e che Enable EasyPost shipping sia attivo. In Shipping > Carriers verifica che il corriere sia attivo e copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e il paese selezionato). Controlla i limiti di peso e il Minimum subtotal. Senza tariffa in tempo reale, il corriere ha bisogno di una tariffa di riserva per il paese o per Other countries. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina del modulo, poi attiva il Debug log, ricarica il checkout e controlla il pannello Log. Motivi comuni: nessuna chiave API o codice postale di spedizione, un negozio non in USD senza USD exchange rate, l'indirizzo di consegna non ha ancora il codice postale, nessun corriere del tuo account EasyPost serve l'indirizzo, oppure i filtri Allowed carriers / services escludono tutte le tariffe.

Le tariffe sembrano prezzi di prova: è impostata una chiave di test (EZTK...). Usa una chiave di produzione (EZAK...) sul negozio online.

Le tariffe si sono fermate per alcuni minuti: dopo un timeout, una chiave rifiutata o un errore del server EasyPost, il modulo sospende le richieste per 5 minuti e usa le tariffe di riserva. Controlla la chiave API e il registro.

Le imposte sono incluse? Le tariffe EasyPost non includono l'imposta sulle vendite. Scegli la regola fiscale in Tax per aggiungere l'imposta alla spedizione.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe EasyPost memorizzate nella cache.

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

Hook per sviluppatori: gli hook actionVfdEpShipmentRequest (corpo della richiesta), actionVfdEpSelectedRate (tariffa scelta) e actionVfdEpApiUrl (URL base dell'API) permettono di personalizzare il modulo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox EasyPost e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Il corriere viene rimosso dal checkout (gli ordini mantengono la cronologia) e le tariffe in cache vengono sempre eliminate. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni, le tariffe salvate degli ordini e il registro. Se è disattivo, le impostazioni e i dati EasyPost degli ordini effettuati vengono conservati per una nuova installazione. Installare o ripristinare il modulo crea un nuovo corriere. Se le impostazioni sono state conservate, il corriere riprende lo stato (attivo o disattivo) del corriere precedente.

EasyPost è un marchio del rispettivo proprietario. Questo modulo non è affiliato a EasyPost né approvato da EasyPost.