VibeFox Estafeta for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la 3.0.5.0) o 4.0.2 e successive (testato con la 4.1.0.3).

PHP: 8.0 o successivo con l'estensione cURL.

Account DrEnvio (solo per le tariffe in tempo reale): le tariffe Estafeta in tempo reale provengono da DrEnvio, partner di Estafeta in Messico. Crea un account su drenvio.com, attiva Estafeta, imposta lì il tuo indirizzo di ritiro e copia la chiave API dal pannello DrEnvio. È la stessa chiave usata dal plugin ufficiale DrEnvio. Se usi solo i tuoi prezzi, non ti serve un account DrEnvio.

Prodotti: i prodotti devono avere un peso per le tariffe in tempo reale.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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_estafeta-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_estafeta.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'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_estafeta-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Estafeta 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. Inserisci la DrEnvio API key e, facoltativamente, il Origin postcode. Se la valuta predefinita non è MXN, inserisci il MXN exchange rate. Imposta un prezzo per il paese MX o un Fallback cost se il metodo deve restare visibile quando DrEnvio non ha una tariffa. Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_estafeta.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 Estafeta, 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 4 e 5 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/Disable e salvi. Se reinstalli l'estensione dopo la disinstallazione, vengono usate di nuovo le impostazioni Estafeta che hai conservato.

Configurazione

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

In cima alla pagina l'estensione mostra degli avvisi: manca la chiave API DrEnvio, la valuta predefinita non è MXN senza un tasso di cambio, non c'è un prezzo per il paese MX e non c'è un costo di riserva (il metodo viene allora nascosto quando non c'è una tariffa in tempo reale, oppure non viene mai mostrato senza chiave API), oppure non c'è una classe di peso in kg (i pesi dei prodotti vengono convertiti in base al nome dell'unità della loro classe di peso, e le unità sconosciute sono considerate kg; aggiungi una classe kg in System > Localisation > Weight Classes). I campi numerici accettano il punto o la virgola decimale. Al salvataggio, un valore errato viene segnalato e poi cancellato o ripristinato come descritto in ogni campo, il modulo mostra il valore salvato e le altre impostazioni vengono comunque salvate (The other settings were saved.).

Generale

Il metodo viene offerto per la zona geografica indicata sotto (o per ogni indirizzo), oppure per i paesi di Availability without shipping zones.

Enable/Disable: attiva o disattiva la spedizione Estafeta. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Estafeta. Obbligatorio: da 1 a 64 caratteri, senza < > ; = # { }. Un nome non valido viene segnalato e si mantiene quello precedente.

Tax class: la classe fiscale aggiunta al costo di spedizione, oppure No tax (predefinito). Se i prezzi DrEnvio includano l'IVA dipende dal tuo account DrEnvio. Se li includono già, scegli No tax.

Geo zone: offre Estafeta solo per gli indirizzi di questa zona geografica, per esempio una zona "Messico". All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usata quando Ignore shipping zones è attivo.

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

Tariffe in tempo reale (API DrEnvio)

La sezione spiega dove ottenere la chiave. Viene proposto il servizio Estafeta più economico per l'indirizzo. Senza chiave vengono usati i prezzi di Prices without a live rate.

DrEnvio API key: la chiave API del tuo pannello DrEnvio. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarla.

Remove the saved API key: visibile solo quando una chiave è salvata. Attivalo e salva per eliminare la chiave. Restano usati solo Country prices e il Fallback cost. Una chiave inserita nel campo sopra sostituisce quella salvata.

Origin country: il codice paese a due lettere dell'indirizzo di ritiro. Predefinito: MX. Viene inviato solo insieme al codice postale di origine. Un codice non valido viene segnalato e riportato a MX.

Origin postcode: il codice postale a 5 cifre dell'indirizzo di ritiro. Lascialo vuoto per usare l'indirizzo di origine salvato nel tuo account DrEnvio. Un codice postale che non ha 5 cifre viene cancellato e segnalato al salvataggio.

MXN exchange rate: DrEnvio emette i preventivi in pesos messicani. Serve solo se la valuta predefinita non è MXN: il valore di 1 MXN nella valuta predefinita, per esempio 0.05. Senza di esso le tariffe in tempo reale non vengono usate. Deve essere maggiore di 0. Se la valuta del negozio è MXN, lascialo vuoto.

Prezzi senza tariffa in tempo reale

Vengono usati quando non c'è una chiave API o DrEnvio non restituisce una tariffa Estafeta (API non disponibile, codice postale sconosciuto, codice postale non ancora inserito). I prezzi sono nella valuta predefinita del negozio, IVA esclusa.

Country prices: un paese di destinazione per riga, nel formato CC:PREZZO, per esempio MX:150. Usa il punto o la virgola decimale, senza separatore delle migliaia. Le parti in un altro formato vengono ignorate e segnalate al salvataggio.

Fallback cost: il prezzo quando non c'è né una tariffa in tempo reale né un prezzo per paese. Lascialo vuoto per nascondere il metodo; 0 significa spedizione gratuita.

Calculation type: Per order (predefinito) addebita il prezzo una sola volta. Per item (price x number of items) lo moltiplica per il numero di articoli nel carrello. Questo vale per Country prices e Fallback cost. Una tariffa DrEnvio in tempo reale è sempre il prezzo dell'intero pacco.

Condizioni

Free shipping from: la spedizione è gratuita quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) raggiunge questo importo. In quel caso non viene inviata nessuna richiesta a DrEnvio. Lascialo vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il metodo solo se lo stesso subtotale è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Min weight (kg): il peso minimo del carrello perché il metodo compaia. 0 significa nessun limite (predefinito).

Max weight (kg): il peso massimo del carrello. Il metodo viene nascosto se viene superato. Predefinito: 30. 0 significa nessun limite.

Se Min weight è maggiore di Max weight, al salvataggio compare un errore e entrambi i pesi restano invariati. I pesi dei prodotti vengono convertiti in kg dalla classe di peso di ogni prodotto.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati sotto senza verificare la zona geografica. Predefinito: disattivato.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per tutti i paesi. Viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive le richieste API e i calcoli delle tariffe in storage/logs/vfd_est_debug.log.php (su OpenCart 4 system/storage/logs/vfd_est_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche quando il registro è disattivato. La chiave API e gli indirizzi dei clienti non vengono mai registrati. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_est_debug.old.log.php e ne viene avviato uno nuovo.

Log: mostra la dimensione e le ultime voci del registro di debug. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate tutte le sue impostazioni e il registro. Se disattivo (predefinito), tutto viene conservato per una reinstallazione. I servizi Estafeta salvati negli ordini vengono sempre conservati.

Importa / Esporta

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

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

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Estafeta. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è fuori da essa, Estafeta non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nel subtotale. Il subtotale è il prezzo di questi prodotti dopo lo sconto del coupon e prima delle tasse; buoni regalo, punti fedeltà e credito del negozio non vengono considerati. L'estensione poi verifica le condizioni: l'elenco Countries (quando Ignore shipping zones è attivo), il peso del carrello e il subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata nessuna richiesta a DrEnvio.

Altrimenti l'estensione invia a DrEnvio il paese e il codice postale di destinazione, il peso del carrello, il numero di articoli e il subtotale in MXN, oltre al codice postale di origine se ne hai impostato uno. I codici postali messicani devono avere 5 cifre; finché il cliente non inserisce un indirizzo di consegna con un codice valido, non viene fatta alcuna richiesta. DrEnvio restituisce i preventivi di tutti i corrieri del tuo account. L'estensione usa solo i preventivi Estafeta, ignora i prezzi a zero, sceglie il più economico e lo converte nella valuta predefinita. Il prezzo viene arrotondato alle cifre decimali di quella valuta e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita o un percorso senza tariffa Estafeta viene ricordato per 5 minuti, così un'API lenta o guasta non rallenta mai ogni aggiornamento del checkout. Il timeout dell'API è di 12 secondi. In questi casi il cliente non vede alcun errore: viene usato il prezzo per paese o il costo di riserva, oppure il metodo viene nascosto se non c'è né l'uno né l'altro. Il motivo viene scritto nel registro.

Il cliente vede solo il nome del metodo e il prezzo. L'estensione calcola soltanto le tariffe. Non crea spedizioni, non stampa etichette (guías) e non traccia i pacchi; crea la spedizione nel tuo account DrEnvio o Estafeta. Il cliente non può scegliere uno specifico servizio Estafeta né un ufficio Estafeta, e i tassi di cambio non vengono aggiornati automaticamente.

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

Ordini

Quando viene effettuato un ordine con Estafeta, l'estensione salva la tariffa mostrata al cliente, senza una nuova richiesta a DrEnvio. Le modifiche successive dell'ordine nell'amministrazione non la cambiano. Su OpenCart 4 il checkout mantiene un unico ordine e lo aggiorna ogni volta che il cliente conferma di nuovo, quindi la tariffa salvata viene sostituita dall'ultima tariffa del checkout. Se il cliente passa a un altro metodo di spedizione, il riquadro non viene più mostrato per quell'ordine.

La pagina dell'ordine in Sales > Orders mostra un riquadro Estafeta:

Estafeta service: il servizio Estafeta del preventivo DrEnvio e il suo tempo di consegna. Mostrato solo per le tariffe in tempo reale.

Price source: Live DrEnvio rate, Country price (no live rate), Fallback cost (no live rate) o Free shipping threshold.

Shipping cost: il prezzo di spedizione calcolato al checkout nella valuta predefinita del negozio, IVA esclusa.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Estafeta è il primo blocco di Extensions > Extensions > Shipping > VibeFox Estafeta > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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-estafeta 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 indica 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 solo 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, Estafeta non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare 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 a 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 modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: 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 l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Estafeta non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo zone, oppure Ignore shipping zones e Countries. Controlla gli avvisi in cima alla pagina dell'estensione, i limiti di peso e Minimum subtotal. Senza chiave API, o quando DrEnvio non ha una tariffa Estafeta, il metodo richiede un prezzo per paese per la destinazione o un costo di riserva. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Mostra il motivo: nessuna chiave API, nessun tasso di cambio per un negozio la cui valuta predefinita non è MXN, codice postale mancante o non valido, chiave API rifiutata (HTTP 401 o 403 da DrEnvio, controlla la chiave API), nessuna tariffa Estafeta per il percorso (il registro elenca i corrieri restituiti da DrEnvio), oppure una tariffa in una valuta diversa da MXN.

Il prezzo include l'IVA? Dipende dal tuo account DrEnvio. Se i prezzi DrEnvio includono già l'IVA, imposta Tax class su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe DrEnvio in cache.

La pagina dell'ordine non ha il riquadro Estafeta: il riquadro viene mostrato solo per gli ordini effettuati con Estafeta mentre l'estensione era installata e attiva.

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

Per gli sviluppatori: l'indirizzo dell'API DrEnvio si può sostituire con l'impostazione vfd_est_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Estafeta. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre eliminati. OpenCart reimposta sempre Enable/Disable, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre eliminate. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Estafeta e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla reinstallazione dell'estensione. I servizi Estafeta salvati negli ordini vengono conservati in entrambi i casi, e gli ordini mantengono il loro metodo e costo di spedizione.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione, clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Estafeta nell'elenco delle estensioni installate, quindi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Estafeta e DrEnvio sono marchi dei rispettivi proprietari. Questa estensione non è affiliata né approvata da Estafeta o DrEnvio.