VibeFox EasyPost for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivi (testato su 4.1.0.3).

PHP: 8.0 o successivo con cURL.

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 i prezzi di riserva, non ti serve un account EasyPost.

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

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_easypost-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_easypost.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_easypost-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox EasyPost e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

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

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

6. Se la valuta predefinita non è USD, inserisci il USD exchange rate. Facoltativamente inserisci i prezzi di riserva (vedi Configurazione). Attiva Enable EasyPost shipping e clicca su Save.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_easypost.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox EasyPost, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 4 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo è disattivato finché non attivi Enable EasyPost shipping e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox EasyPost > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe EasyPost memorizzate nella cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni o svuotare il registro.

In cima alla pagina l'estensione mostra avvisi quando le tariffe in tempo reale non possono essere usate: nessuna chiave API (con o senza prezzi di riserva), nessun CAP o paese di partenza, oppure una valuta predefinita diversa da USD senza un tasso di cambio. Compare anche una nota quando è impostata una chiave API di test, e un avviso quando l'unità di peso o di lunghezza del tuo negozio (System > Settings > Option) non è una di quelle riconosciute dall'estensione (kg, g, lb, oz; cm, mm, m, in).

Al salvataggio, un nome più lungo di 64 caratteri, un Sort order che non è un numero intero, o una classe fiscale o una zona geografica sconosciute bloccano il salvataggio, e in tal caso non viene salvato nulla. Un valore che non è un numero (o è negativo) non viene salvato: un avviso indica il campo e viene mantenuto il valore precedente, mentre le altre impostazioni vengono salvate. Lo stesso accade quando il USD exchange rate è 0, o quando il Minimum weight è maggiore del Maximum weight.

Generale

Enable EasyPost shipping: offre il metodo al checkout. È lo stato dell'estensione in Extensions > Extensions > Shipping. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato al cliente al checkout, al massimo 64 caratteri. Predefinito: EasyPost Shipping. Se il nome è vuoto, viene usato il nome predefinito. Un nome con i caratteri < > ; = # { } viene sostituito con il nome predefinito, con un avviso.

Sort order: la posizione del metodo tra i metodi di spedizione al checkout. Un numero intero.

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 Saved key: EZAK******abcd. Leave the field empty to keep it. Inserisci un nuovo valore solo se vuoi modificarla. Senza chiave vengono usati solo i prezzi di riserva.

Remove the saved API key: attivalo e clicca 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) come li chiama EasyPost. Viene mostrata la tariffa consentita più economica. Lascialo vuoto per mostrare la tariffa più economica di qualsiasi corriere.

Partenza

L'indirizzo da cui vengono spediti i tuoi pacchi. Se il Country è il paese del tuo negozio, il campo vuoto Sender name / company viene preso dal nome del negozio e il campo vuoto State dalla regione del negozio (System > Settings). OpenCart non ha un CAP per il negozio, quindi il CAP va inserito qui.

Sender name / company: il nome del mittente o l'azienda. Vuoto significa il nome del negozio (solo nello stesso paese).

Street address: la via dell'indirizzo di partenza.

City: la città dell'indirizzo di partenza.

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

ZIP code: il CAP dell'indirizzo di partenza, per esempio 94105. 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à di peso del tuo negozio in once (minimo 1 oz) e le dimensioni dall'unità di lunghezza del negozio 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 valuta predefinita del tuo negozio, per esempio 0.92. Senza di esso le tariffe in tempo reale non vengono usate, solo i prezzi di riserva. Non serve se la valuta predefinita è 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 class: la classe fiscale applicata alla spedizione, oppure No tax. Le tariffe EasyPost non includono l'imposta sulle vendite.

Prezzi di riserva

Vengono usati quando non c'è una tariffa in tempo reale: nessuna chiave API, EasyPost non raggiungibile, chiave rifiutata, oppure nessun corriere ha una tariffa per l'indirizzo. I prezzi sono nella valuta predefinita del negozio, IVA esclusa. Lascia vuoti entrambi i campi per nascondere il metodo in quel caso.

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

Other countries: il prezzo per i paesi non presenti nell'elenco sopra. Lascialo vuoto per nascondere il metodo per loro.

Condizioni

Free shipping from: il subtotale del carrello (prodotti da spedire, dopo il coupon, prima delle imposte, nella valuta predefinita) da cui la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta a EasyPost. Lascialo vuoto per disattivarla.

Minimum subtotal: mostra il metodo solo se il subtotale del carrello (prodotti da spedire, dopo il coupon, prima delle imposte) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

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

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

Disponibilità

Di solito è la zona geografica a decidere dove viene offerto il metodo. In alternativa può essere offerto per paese, indipendentemente dalla zona geografica.

Geo zone: offre il metodo solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non usato con Ignore shipping zones.

Ignore shipping zones: offre il metodo per i paesi indicati sotto, che siano o no nella zona geografica.

Countries: i paesi di destinazione per questa modalità. Lascialo 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 storage/logs/vfd_ep.log.php (su OpenCart 4 system/storage/logs/vfd_ep.log.php). Il file non può essere letto dal web. Quando raggiunge 5 MB, viene spostato in vfd_ep.old.log.php e inizia un nuovo registro. Gli errori e gli avvisi dell'API vengono sempre registrati, anche quando questa opzione è disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le sue impostazioni e il registro. I dati EasyPost degli ordini effettuati vengono conservati. Disattivare il metodo non elimina mai le impostazioni.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

Import: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. La chiave API salvata non viene modificata.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di EasyPost. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. L'estensione verifica prima le condizioni: paese di destinazione (con Ignore shipping zones), peso del carrello e subtotale minimo. Il subtotale è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a EasyPost.

Altrimenti l'estensione invia a EasyPost l'indirizzo di partenza, 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 del negozio e la mostra nella valuta del cliente con l'imposta della Tax class selezionata. Per i paesi contrassegnati come Postcode Required in System > Localisation > Countries, la richiesta viene fatta solo se l'indirizzo di consegna ha un CAP. Nei dati standard di OpenCart questo flag è disattivato per gli Stati Uniti, quindi viene inviato anche un indirizzo statunitense senza ZIP code; EasyPost restituisce allora un errore e viene usato il prezzo di riserva.

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 vengono fatte richieste. Il timeout dell'API è di 10 secondi. In tutti questi casi il cliente non vede alcun errore: viene usato il prezzo di riserva, oppure il metodo viene nascosto se non c'è un prezzo di riserva. Il motivo viene scritto nel registro.

L'estensione calcola solo le tariffe. Non acquista etichette, non traccia i pacchi, non convalida gli indirizzi, non offre punti di ritiro o di consegna e non aggiunge assicurazioni o opzioni di firma. Mostra un'opzione (la tariffa consentita più economica), non un elenco di servizi. Non c'è un confezionamento in scatole oltre all'impilare gli articoli in un unico pacco, né maggiorazioni della tariffa o commissioni di gestione.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie il metodo EasyPost nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando viene effettuato un ordine con il metodo EasyPost, la tariffa mostrata al checkout viene conservata con l'ordine. La pagina dell'ordine in amministrazione (Sales > Orders) mostra il riquadro EasyPost shipping sopra la cronologia:

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

Estimated delivery days: i giorni di consegna restituiti da EasyPost (solo nella 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 del negozio.

Il riquadro viene mostrato anche se l'estensione viene disattivata in seguito. Le modifiche successive all'ordine in amministrazione non cambiano questi valori. Usali per acquistare l'etichetta nel tuo account EasyPost. OpenCart crea un record d'ordine ogni volta che il checkout arriva alla fase di conferma; le tariffe salvate di questi ordini non completati vengono eliminate dopo 30 giorni.

Su OpenCart 4 il checkout mantiene un unico ordine e lo aggiorna ogni volta che il cliente conferma di nuovo. La tariffa salvata viene aggiornata insieme: è la tariffa che il cliente ha visto al checkout. Se il cliente passa a un altro metodo di spedizione, il riquadro non viene più mostrato per quell'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox EasyPost è il primo blocco nella pagina Extensions > Extensions > Shipping > VibeFox EasyPost > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, 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: opencart-shipping-easypost e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (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 aver cambiato l'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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione EasyPost non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo è nascosto per tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non vengono influenzati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

EasyPost non compare al checkout: verifica che la licenza sia attiva e che Enable EasyPost shipping sia attivo. Controlla Geo zone (o Ignore shipping zones e Countries), i limiti di peso e il Minimum subtotal. Senza una tariffa in tempo reale il metodo ha bisogno di un prezzo di riserva per il paese o per Other countries. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina dell'estensione, poi attiva Debug log, ricarica il checkout e guarda il campo Log. Cause comuni: nessuna chiave API o CAP di partenza, un negozio non in USD senza il USD exchange rate, l'indirizzo di consegna non ha ancora un CAP, nessun corriere del tuo account EasyPost serve l'indirizzo, oppure Allowed carriers / services filtra tutte le tariffe.

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

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

L'imposta è inclusa? Le tariffe EasyPost non includono l'imposta sulle vendite. Scegli la classe fiscale in Tax class per aggiungere l'imposta alla spedizione.

Le tariffe sembrano non aggiornate dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota le tariffe EasyPost memorizzate nella cache.

La pagina mostra "Warning: You do not have permission to modify VibeFox EasyPost!": il tuo gruppo di utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_easypost (OpenCart 3) o extension/vfd_easypost/shipping/vfd_easypost (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: altre estensioni possono modificare il corpo della richiesta, la tariffa scelta e l'URL base dell'API con gli eventi OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate e vfd_easypost/api_url.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox EasyPost. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable EasyPost shipping, Sort order, Tax class e Geo zone. L'estensione rimuove sempre i propri eventi e le tariffe in cache. Se Remove data on uninstall è attivo, vengono eliminati anche le altre impostazioni e il registro. Se è disattivo, le impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I dati EasyPost degli ordini effettuati non vengono mai eliminati, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Per rimuovere anche i file dell'estensione su OpenCart 4, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox EasyPost nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso a forma di cestino) per eliminare il pacchetto caricato.

EasyPost è un marchio registrato del suo titolare. Questa estensione non è affiliata a EasyPost né da essa approvata.