VibeFox Estafeta for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Il modulo non si installa con versioni precedenti di PHP o senza 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, configura lì il tuo indirizzo di ritiro e copia la chiave API dal pannello DrEnvio. È la stessa chiave usata dal plugin ufficiale di 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: acquistata 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 cerca più tardi VibeFox Estafeta nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).

4. Inserisci la DrEnvio API key e, facoltativamente, il Origin postcode. Se la valuta predefinita del tuo negozio non è MXN, inserisci il MXN exchange rate. Imposta un prezzo per paese per MX oppure una Fallback cost se il corriere deve restare visibile quando DrEnvio non ha una tariffa. Fai clic su Save.

All'installazione il modulo crea il corriere Estafeta con il testo dei tempi di consegna Estafeta courier (Mexico). 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 lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

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

In cima alla pagina il modulo mostra degli avvisi: manca la chiave API DrEnvio, la valuta predefinita non è MXN senza tasso di cambio, non c'è un prezzo per paese per MX né un costo di riserva (in tal caso il corriere viene nascosto quando non c'è una tariffa in tempo reale, oppure non viene mai mostrato senza chiave API), oppure c'è un'unità di peso del negozio che il modulo non riconosce (i pesi dei prodotti vengono allora considerati in kg; imposta l'unità in International > Localization, Local units). I campi numerici accettano il punto o la virgola come separatore decimale. Un valore che non è un numero valido viene cancellato e segnalato al salvataggio; le altre impostazioni vengono comunque salvate.

Generali

Zone, gruppi di clienti e limiti di dimensione del corriere si impostano in Shipping > Carriers. Queste impostazioni valgono per tutte le zone.

Enable/Disable: attiva o disattiva la spedizione Estafeta. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del corriere mostrato al cliente al checkout. Predefinito: Estafeta. Obbligatorio. Un nome non valido viene segnalato e viene mantenuto quello precedente.

Tax: la regola fiscale del corriere, oppure No tax. Il negozio aggiunge questa imposta al costo di spedizione. Se i prezzi DrEnvio includano l'IVA dipende dal tuo account DrEnvio. Se li includono già, scegli No tax.

Tariffe in tempo reale (API DrEnvio)

Viene offerto il servizio Estafeta più economico per l'indirizzo. Senza chiave si usano i prezzi della sezione successiva.

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

Remove the saved API key: visibile solo quando è salvata una chiave. Impostalo su Yes e salva per eliminare la chiave. Restano in uso solo i Country prices e la 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 CAP di origine.

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

MXN exchange rate: DrEnvio fornisce preventivi in pesos messicani. Serve solo se la valuta predefinita del tuo negozio non è MXN: il valore di 1 MXN nella tua valuta predefinita, ad esempio 0.05. Senza di esso le tariffe in tempo reale non vengono usate.

Prezzi senza tariffa in tempo reale

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

Country prices: un paese di destinazione per riga, nel formato CC:PRICE, ad esempio MX:150. Usa il punto o la virgola come separatore 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 corriere; 0 significa spedizione gratuita.

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

Condizioni

Free shipping from: la spedizione è gratuita quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle imposte) raggiunge questo importo. In quel caso non viene inviata alcuna richiesta a DrEnvio. Lascialo vuoto per non offrire mai la spedizione gratuita.

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

Min weight: il peso minimo del carrello in kg perché il corriere compaia. 0 significa nessun limite.

Max weight: il peso massimo del carrello in kg. Il corriere 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 dall'unità di peso del negozio in kg.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il corriere per i paesi indicati senza configurare zone per esso. Finché è attiva, il corriere riceve tutte le zone, comprese quelle che creerai in seguito. Disattivandola, il corriere riprende le proprie zone.

Countries: i paesi di destinazione per questa modalità, scelti tra i paesi attivi del tuo negozio. Lascialo vuoto per tutti i paesi. Viene usato solo quando Ignore shipping zones è attiva.

Avanzate

Debug log: scrive richieste API e calcoli delle tariffe in logs/vfd_est_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati. La chiave API e gli indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito.

Log: mostra la dimensione e le voci più recenti del log di debug. Fai clic su Clear log per svuotarlo.

Remove data on uninstall: se attiva, la disinstallazione del modulo elimina tutte le impostazioni del modulo, il corriere, i servizi Estafeta salvati degli ordini e il log. Se disattiva, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Estafeta. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima le condizioni: l'elenco Countries (quando è attiva Ignore shipping zones), il peso del carrello e il subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a DrEnvio.

Altrimenti il modulo invia a DrEnvio il paese e il CAP di destinazione, il peso del carrello, il numero di articoli e il subtotale in MXN, oltre al CAP di origine se ne hai impostato uno. I CAP messicani devono avere 5 cifre; finché il cliente non inserisce un indirizzo di consegna con un CAP di questo tipo, non viene fatta alcuna richiesta. DrEnvio restituisce i preventivi di tutti i corrieri del tuo account. Il modulo usa solo i preventivi Estafeta, ignora i prezzi pari a zero, sceglie il più economico e lo converte nella valuta predefinita del negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.

Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta fallita o una tratta senza tariffa Estafeta vengono ricordate 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 corriere viene nascosto se non è impostato nessuno dei due. Il motivo viene scritto nel log.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto degli ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo 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 un servizio Estafeta specifico né un ufficio Estafeta, e i tassi di cambio non vengono aggiornati automaticamente.

Ordini

Quando viene effettuato un ordine con il corriere Estafeta, il modulo conserva la tariffa calcolata per il suo carrello. I ricalcoli successivi, per esempio nella pagina dell'ordine nel back office, non la modificano.

La pagina degli ordini in Orders > Orders mostra un blocco 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) oppure Free shipping threshold.

Calculated price (excl. tax): il prezzo di spedizione nella valuta predefinita del negozio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Estafeta è il primo blocco di Modules > Module Manager > VibeFox Estafeta > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi 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 compaiono la riga Product: presta-shipping-estafeta 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 modificare 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, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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: quello 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 Estafeta non viene mostrato ai clienti al 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 testarlo al 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 a 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

Estafeta non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attiva e il paese sia consentito). Controlla gli avvisi in cima alla pagina del modulo, i limiti di peso e il Minimum subtotal. Senza chiave API o quando DrEnvio non ha una tariffa Estafeta, il corriere ha bisogno di un prezzo per paese per la destinazione o di un costo di riserva. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Indica il motivo: manca la chiave API; non c'è un tasso di cambio per un negozio la cui valuta predefinita non è MXN; il CAP manca o non è valido; la chiave API è stata rifiutata (HTTP 401 o 403 da DrEnvio, controlla la chiave API); non c'è una tariffa Estafeta per la tratta (il log elenca i corrieri restituiti da DrEnvio); oppure c'è 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 su No tax.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo svuota la cache delle tariffe DrEnvio.

La pagina indica che il corriere Estafeta non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Lo stesso vale per il messaggio The settings were saved, but the carrier could not be updated.

La pagina dell'ordine non ha il blocco Estafeta: il blocco viene mostrato solo per gli ordini effettuati con il corriere Estafeta mentre il modulo era installato. La disinstallazione con Remove data on uninstall attivo elimina i servizi salvati.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox Estafeta e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre eliminati. La cache delle tariffe viene sempre eliminata. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano lo storico), e vengono eliminate le impostazioni, i servizi Estafeta salvati degli ordini e il log. Se è disattivo, il corriere viene solo disabilitato e le impostazioni e i servizi salvati degli ordini vengono conservati. Reinstallando il modulo, il corriere riprende lo stato che aveva prima della disinstallazione.

Estafeta e DrEnvio sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Estafeta o DrEnvio.