VibeFox Envioclick for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

Account Envioclick (solo per le tariffe in tempo reale): un account Envioclick in Messico o Colombia con accesso API. La chiave API si trova nel tuo account Envioclick, in Mi cuenta (in alto a destra) > Información del API. Se usi solo prezzi fissi, non ti serve un account Envioclick.

User-Agent (solo Messico): Envioclick Messico richiede un valore User-Agent per ogni richiesta API. Chiedilo al supporto Envioclick (soporte.tecnico@envioclick.com).

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nell'amministrazione 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 Envioclick 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 Configure, e clicca su Activate (vedi Chiave di licenza).

4. Inserisci la chiave API, scegli il paese dell'API, inserisci lo User-Agent (Messico), il codice postale o il codice DANE di partenza e l'indirizzo di partenza. Se la valuta predefinita del tuo negozio non è MXN o COP, inserisci il tasso di cambio. Per la Colombia, clicca su Add Colombian departments se la pagina lo propone.

5. Facoltativamente aggiungi prezzi fissi per paese e un costo di riserva, poi clicca su Save.

All'installazione il modulo crea il corriere Envioclick Shipping con il testo dei tempi di consegna Courier delivery by the best Envioclick carrier. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Envioclick > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Envioclick in cache. I campi numerici accettano sia il punto sia la virgola come separatore decimale.

Quando è impostata una chiave API, in cima alla pagina compaiono avvisi se le tariffe in tempo reale non possono funzionare: nessun tasso di cambio per una valuta del negozio diversa da MXN o COP, nessuno User-Agent per il Messico, nessun codice postale o codice DANE di partenza, oppure nessun indirizzo di partenza per la Colombia. La pagina avvisa anche se l'unità di peso o di dimensione del tuo negozio non è riconosciuta; imposta kg, g, lb o oz e cm, mm, m o in in International > Localization (Local units). Al salvataggio il modulo verifica che Method title sia un nome di corriere valido, che i campi numerici contengano numeri non negativi, che Currency conversion rate sia maggiore di 0, che Minimum weight non sia maggiore di Maximum weight e che il codice di partenza abbia 5 cifre per il Messico o 8 cifre (oppure il codice comunale a 5 cifre) per la Colombia. Se una verifica non riesce, viene mostrato un errore e non si salva nulla.

Generali

Zone, gruppi di clienti e limiti di dimensione del corriere si impostano in Shipping > Carriers (oppure usa Ignore shipping zones più sotto). Le impostazioni di questa pagina si applicano a tutte le zone.

Enable Envioclick: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato al cliente nel carrello e al checkout. Predefinito: Envioclick Shipping. Obbligatorio.

Carrier in the title: mostra il corriere Envioclick e il tempo di consegna stimato di una tariffa in tempo reale sotto il corriere al checkout, per esempio «Estafeta Express, 1 day». Il corriere viene comunque salvato nell'ordine e mostrato nelle pagine degli ordini. Predefinito: attivo.

API Envioclick (tariffe in tempo reale)

Facoltativo. Senza chiave API si usano solo i prezzi fissi. La sezione contiene i link alla documentazione dell'API Envioclick per Messico e Colombia. Le tariffe in tempo reale vengono richieste solo per destinazioni nel paese dell'API. Le spedizioni verso altri paesi usano i prezzi fissi.

API key: la tua chiave API Envioclick, da Mi cuenta > Información del API. Viene inviata nell'intestazione «Authorization». Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Remove the saved API key: visibile solo mentre una chiave è salvata. Scegli Yes e salva per eliminare la chiave; si useranno solo i prezzi fissi. Una chiave inserita in API key sostituisce quella salvata.

API country: il paese del tuo account Envioclick.

Colombian departments: solo Colombia. PrestaShop non ha di default i dipartimenti colombiani. Senza di essi vengono riconosciuti solo i nomi di città unici in Colombia; il dipartimento distingue i comuni con lo stesso nome. Il pulsante Add Colombian departments aggiunge i 33 dipartimenti come stati della Colombia (codici ISO ANT, DC e così via), attiva «Contains states» per la Colombia e aggiunge il campo dipartimento al modulo dell'indirizzo colombiano. I dipartimenti già presenti non vengono aggiunti due volte. Quando tutto è pronto, il campo mostra quanti dipartimenti hanno gli indirizzi colombiani.

User-Agent (Messico): il valore emesso dal supporto Envioclick (soporte.tecnico@envioclick.com), per esempio EcUserAgent-2/123456. Obbligatorio per il Messico; senza di esso non si richiedono tariffe in tempo reale per il Messico. Facoltativo per la Colombia.

Carrier choice: Cheapest (predefinito) oppure Fastest (then cheapest). Envioclick restituisce tariffe di diversi corrieri e il cliente riceve un'unica tariffa.

Branch pickup rates: considera anche le tariffe «Ocurre», in cui il cliente ritira il pacco presso la filiale del corriere. Se disattivato, si usano solo le tariffe di consegna a domicilio. I servizi di pagamento alla consegna (COD) non vengono mai usati. Predefinito: disattivato.

Currency conversion rate: Envioclick calcola in MXN (Messico) o COP (Colombia). Se la valuta predefinita del tuo negozio è diversa, inserisci il valore di 1 MXN o 1 COP nella valuta del tuo negozio, per esempio 0.05. Il valore dichiarato del pacco viene convertito allo stesso modo. Lascia vuoto il campo se la valuta del negozio è MXN o COP. Senza il tasso, in un'altra valuta le tariffe in tempo reale non vengono usate.

Spedizione da

Usato per le tariffe in tempo reale. I campi vuoti vengono compilati con l'indirizzo del negozio in Shop Parameters > Contact > Stores, se il negozio si trova nel paese dell'API.

Origin postcode / DANE code: Messico: il codice postale a 5 cifre. Colombia: il codice DANE a 8 cifre del comune, per esempio 11001000 per Bogotá; funziona anche il codice comunale a 5 cifre (11001).

Origin address: via e numero dell'indirizzo di ritiro. Obbligatorio per la Colombia, facoltativo per il Messico.

Prezzi fissi

Usati quando non c'è una tariffa in tempo reale: nessuna chiave API, una destinazione fuori dal paese dell'API, un errore dell'API o nessun corriere per la tratta.

Price per country: una tabella di codici paese a 2 lettere e di prezzi nella valuta predefinita del negozio, IVA esclusa. Clicca su Add row per aggiungere un paese e sull'icona del cestino per rimuoverlo. Usa * come codice paese per tutti i paesi senza una riga propria.

Fallback cost: usato quando non c'è una tariffa in tempo reale e nessuna riga della tabella corrisponde. Lascia vuoto il campo per nascondere il corriere in questo caso.

Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Le tariffe Envioclick in tempo reale sono sempre per spedizione.

Condizioni

Minimum weight: nasconde il corriere sotto questo peso del carrello, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere sopra questo peso del carrello, in kg. Predefinito: 25. 0 significa nessun limite.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) è almeno questo importo. Lascia vuoto il campo per mostrarlo sempre.

Free shipping from: spedizione gratuita quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. In quel caso non viene inviata alcuna richiesta a Envioclick. Lascia vuoto il campo per non offrire mai la spedizione gratuita.

Tax: la regola fiscale del corriere oppure No tax. Le tariffe Envioclick includono già le tasse dei corrieri, quindi scegli No tax per non far pagare l'IVA sulla spedizione due volte.

Disponibilità senza zone di spedizione

Normalmente il corriere viene offerto nelle zone a lui assegnate in Shipping > Carriers.

Ignore shipping zones: offre Envioclick per i paesi indicati sotto anche se il corriere non è assegnato alla loro zona. Quando lo attivi, il corriere viene assegnato a tutte le zone, comprese quelle create in seguito. Quando lo disattivi, il corriere riprende le sue zone precedenti.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi verso cui spedisci (paesi attivi). Viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra i calcoli delle tariffe e gli errori dell'API in logs/vfd_evc_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. La chiave API e gli indirizzi dei clienti non vengono registrati. Finché il log è disattivato non si scrive nulla. Disattivalo quando hai finito.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni Envioclick, il corriere, le tariffe in cache e i log. Il corriere salvato con i vecchi ordini viene mantenuto. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo Envioclick. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica prima le condizioni: i paesi di Ignore shipping zones, il peso del carrello e l'importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Envioclick.

Se è impostata una chiave API e la destinazione si trova nel paese dell'API, il modulo chiede a Envioclick le tariffe. In Messico la richiesta viene fatta quando il cliente ha inserito un codice postale a 5 cifre. In Colombia viene fatta quando dipartimento e comune sono riconosciuti (accenti e maiuscole non contano). Il modulo sceglie la tariffa più economica o quella più veloce che non sia un pagamento alla consegna e la converte nella valuta predefinita del tuo negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.

Il pacco è sempre un unico collo: il peso totale convertito in kg, la lunghezza e la larghezza dell'articolo più grande e un'altezza che mantiene il volume totale di tutti gli articoli. I prodotti senza dimensioni contano come 10 × 10 × 10 cm. Un carrello senza peso viene inviato come 0,5 kg. Il valore dichiarato è il subtotale del carrello.

Ogni tariffa viene memorizzata nella cache per 1 ora per la stessa tratta e lo stesso pacco. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così un'API non disponibile non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi. Se Envioclick restituisce un errore o nessun corriere per la tratta, il cliente non vede alcun errore: viene usato il prezzo fisso oppure il corriere viene nascosto. Il motivo viene scritto nel log di debug.

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

Il modulo calcola solo tariffe. Non crea guide di spedizione né etichette, non richiede ritiri e non traccia né annulla le spedizioni. Offre una sola tariffa, non una scelta tra corrieri, e non usa servizi di pagamento alla consegna né preventivi per più colli. Le tariffe in tempo reale valgono solo a livello nazionale.

Ordini

Quando un ordine viene effettuato con il corriere Envioclick, la tariffa calcolata per il suo carrello viene salvata con l'ordine e non cambia più. La pagina dell'ordine nell'amministrazione mostra il blocco Envioclick shipping con Envioclick carrier, Estimated delivery e Envioclick rate ID (per una tariffa in tempo reale), Price source (Envioclick live rate, Fixed price per country, Fallback cost oppure Free shipping threshold) e Calculated price (excl. tax). Per una tariffa in tempo reale la pagina dell'ordine del cliente mostra Shipping carrier. Crea la guida di spedizione nel tuo account Envioclick.

Gli ordini effettuati con un prezzo fisso non hanno un corriere Envioclick.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Envioclick è il primo blocco di Modules > Module Manager > VibeFox Envioclick > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 compaiono la riga Product: presta-shipping-envioclick 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 seguito da una data. Dopo una modifica dell'indirizzo del negozio, o dopo aver liberato un posto 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Envioclick 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 un 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

Envioclick non compare al checkout: verifica che la licenza sia attiva e che Enable Envioclick sia attivo. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore shipping zones e controlla Countries. Verifica i limiti di peso e il Minimum order amount. Senza una tariffa in tempo reale, il corriere ha bisogno di un prezzo fisso per il paese, di una riga * o di un Fallback cost. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in alto nella pagina del modulo, poi attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Motivi comuni: nessun tasso di cambio (la valuta del negozio non è MXN o COP), nessuno User-Agent (Messico), nessun codice postale o codice DANE di partenza, codice postale del cliente (Messico) o città (Colombia) non ancora inseriti, destinazione fuori dal paese dell'API oppure nessun corriere per la tratta.

Perché serve un tasso di cambio? Envioclick restituisce prezzi solo in pesos messicani o colombiani. Il modulo non mostra mai un importo in pesos come se fosse in un'altra valuta.

Colombia: la città non viene riconosciuta: clicca su Add Colombian departments nella pagina del modulo, così i clienti possono scegliere il dipartimento, e controlla che il nome del comune sia scritto correttamente. Funziona anche un codice DANE a 8 cifre inserito come codice postale.

Le tasse sulla spedizione vengono addebitate due volte: le tariffe Envioclick includono già le tasse dei corrieri. Imposta Tax su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo svuota le tariffe in cache.

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

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Envioclick e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre eliminati. Le tariffe in cache e le tariffe salvate dei carrelli senza ordine vengono sempre eliminate. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimossi impostazioni e log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere salvato riprende il suo stato precedente. I dati Envioclick degli ordini effettuati vengono conservati in entrambi i casi.

Envioclick è un marchio registrato del suo titolare. Questo modulo non è affiliato né approvato da Envioclick.