VibeFox The Courier Guy for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Chiave API ShipLogic (per tariffe in tempo reale e locker): The Courier Guy funziona sulla piattaforma ShipLogic. Crea una chiave API nel tuo portale corrieri di The Courier Guy, in Settings > API Keys (account business). Senza la chiave viene usata solo la tabella dei prezzi e il corriere locker non viene offerto.

Spedizione in Sudafrica: le tariffe in tempo reale e i locker sono solo per indirizzi sudafricani. Il Sudafrica deve essere un paese attivo del negozio (International > Locations > Countries).

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

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox The Courier Guy nell'elenco dei moduli e clicca su Configure.

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

4. Inserisci la API key di ShipLogic. Per le tariffe in tempo reale compila l'indirizzo del mittente (via, città, provincia, codice postale) e, se la valuta del negozio non è ZAR, il ZAR conversion rate.

5. Compila la tabella dei prezzi e/o un costo di riserva e clicca su Save.

6. Per le tariffe corriere in tempo reale, clicca su Add South African provinces nella sezione Advanced se la pagina segnala che gli indirizzi sudafricani non hanno una provincia.

All'installazione il modulo crea due corrieri: The Courier Guy (testo dei tempi di consegna The Courier Guy courier delivery to your door) e The Courier Guy locker (Delivery to a TCG locker of your choice). Entrambi sono attivi, collegati alla zona del Sudafrica 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 lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox The Courier Guy > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella le tariffe e i locker in cache e l'ultimo errore di ShipLogic. Gli avvisi in cima alla pagina ti segnalano quando il Sudafrica non è un paese attivo, manca la chiave API, il tasso di conversione ZAR o l'indirizzo del mittente, non ci sono né tabella dei prezzi né costo di riserva, gli indirizzi sudafricani non hanno una provincia, l'unità di peso o di dimensione del negozio non è riconosciuta dal modulo, oppure l'ultima richiesta a ShipLogic è fallita (con data ed errore). Un numero non valido (per esempio negativo) non viene salvato: la pagina indica il campo e mantiene il valore precedente.

Generali

Courier to the door: attiva o disattiva il corriere a domicilio. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Courier carrier name: il nome del corriere a domicilio al checkout. Predefinito: The Courier Guy. Obbligatorio.

TCG locker: attiva o disattiva il corriere locker. Il cliente sceglie un locker al checkout. È offerto solo per indirizzi sudafricani e solo con la chiave API ShipLogic.

Locker carrier name: il nome del corriere locker al checkout. Predefinito: The Courier Guy locker. Obbligatorio.

Tax status: la regola fiscale di entrambi i corrieri. Taxable: <tax rule>: le tariffe in tempo reale vengono prese senza IVA e PrestaShop aggiunge l'imposta di spedizione della regola selezionata. None: le tariffe in tempo reale vengono prese IVA inclusa.

API ShipLogic (tariffe in tempo reale e locker)

API key: la tua chiave API ShipLogic del portale The Courier Guy. Non viene mai mostrata ai clienti né scritta nel log. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo per cambiarla. Spunta Remove the saved API key e salva per rimuoverla.

Account ID: facoltativo. L'ID numerico dell'account ShipLogic, solo se la tua chiave ha accesso a più account. Un valore non numerico non viene salvato.

Tariffe in tempo reale (per indirizzi sudafricani; se non c'è una tariffa in tempo reale, si usa la tabella dei prezzi)

Price source: da dove proviene il prezzo.

ZAR conversion rate: ShipLogic quota in rand sudafricani (ZAR). Se la valuta predefinita del negozio non è ZAR, indica quanto vale 1 ZAR nella tua valuta, per esempio 0.05. Senza questo valore le tariffe in tempo reale non vengono usate e si applica la tabella dei prezzi. Se la valuta del negozio è ZAR, lascia il campo vuoto. Il tasso non viene aggiornato automaticamente.

Indirizzo del mittente (per tariffe in tempo reale) (dove The Courier Guy ritira i pacchi, in Sudafrica; per le tariffe in tempo reale servono via, città, provincia e codice postale)

Sender company: il nome della tua azienda.

Sender street address: per esempio 12 My Road.

Sender suburb: il quartiere dell'indirizzo del mittente.

Sender city: la città dell'indirizzo del mittente.

Sender province: scegli la provincia sudafricana dall'elenco.

Sender postal code: il codice postale dell'indirizzo del mittente.

Tabella dei prezzi (i tuoi prezzi nella valuta predefinita del negozio, IVA esclusa: usata con Price table only, fuori dal Sudafrica e ogni volta che non c'è una tariffa in tempo reale; sono accettati la virgola o il punto decimale)

Calculation type: si applica solo alla tabella dei prezzi. Una tariffa in tempo reale è sempre per l'intero ordine.

Prices by weight: una tabella di paesi con una colonna Price e le fasce di peso XS (fino a 1 kg), S (fino a 2 kg), M (fino a 3 kg), L (fino a 5 kg) e XL (oltre 5 kg). Clicca su Add row per aggiungere una riga (una nuova riga parte dal Sudafrica) e sull'icona del cestino per rimuoverne una. Una fascia vuota o pari a 0 usa la colonna Price. Un prezzo di 0 significa spedizione gratuita. La riga * Any country si applica ai paesi senza riga propria e a una riga di paese senza alcun prezzo. Un prezzo che non è un numero viene cancellato e la pagina lo segnala.

Fallback cost: usato quando non c'è né una tariffa in tempo reale né un prezzo in tabella. Lascialo vuoto per nascondere i corrieri in quel caso.

Condizioni (entrambi i corrieri)

Min weight (kg): nasconde i corrieri se il peso del carrello è inferiore a questo valore. 0 significa nessun limite.

Max weight (kg): nasconde i corrieri se il peso del carrello è superiore a questo valore. Predefinito: 30. 0 significa nessun limite, vuoto significa 30 kg. Se Min weight (kg) è maggiore di Max weight (kg), la pagina mostra un avviso e i due limiti mantengono i valori precedenti.

Minimum order amount: mostra i corrieri solo a partire da questo subtotale del carrello (prodotti che richiedono spedizione, IVA esclusa, dopo gli sconti). Lascia vuoto per mostrarli sempre.

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. Lascia vuoto per non offrire mai la spedizione gratuita. Quando il subtotale lo raggiunge, i corrieri vengono mostrati con prezzo 0 e non viene inviata alcuna richiesta a ShipLogic per la tariffa.

Disponibilità senza zone di spedizione

Normalmente i corrieri vengono offerti nelle zone di spedizione a cui sono collegati in Shipping > Carriers.

Ignore shipping zones: offre il corriere del tipo di consegna indicato sotto per i paesi indicati sotto, anche dove le sue zone non li includono. Il corriere è collegato a ogni zona attiva, anche a quelle create in seguito. Quando disattivi di nuovo l'opzione, riottiene le zone che aveva prima.

Delivery type without zones: Courier to the door oppure TCG locker (customer chooses a locker). Usato solo con Ignore shipping zones.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per consentire tutti i paesi. I locker sono offerti solo in Sudafrica.

Avanzate

South African provinces: PrestaShop non ha province sudafricane, ma la tariffa corriere in tempo reale richiede la provincia dell'indirizzo. Add South African provinces aggiunge le 9 province (EC, FS, GP, KZN, LP, MP, NC, NW, WC) come stati del Sudafrica e mostra il campo dello stato negli indirizzi sudafricani. Le province già esistenti non vengono aggiunte di nuovo. Fino ad allora il corriere riceve il prezzo della tabella.

Debug log: scrive i messaggi di debug in logs/vfd_tcgr_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. La chiave API e i dati dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attiva, disinstallando il modulo ne vengono eliminate le impostazioni e i corrieri. Se disattiva, disinstallando si disattivano soltanto i corrieri. I locker salvati sugli ordini vengono sempre conservati.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo di ciascun corriere. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non rientrano nell'importo dell'ordine. Il modulo verifica prima le condizioni: peso del carrello e importo minimo d'ordine. Se si applica la spedizione gratuita, il prezzo è 0.

Courier to the door: il modulo chiede a ShipLogic il servizio più economico dall'indirizzo del mittente a quello del cliente. L'indirizzo deve avere via, città, provincia e codice postale. Fino ad allora si usa la tabella dei prezzi.

TCG locker: la tariffa in tempo reale è il servizio più economico da porta a locker fino al locker più vicino alla città del cliente. Non viene ricalcolata per il locker scelto dal cliente. Il corriere locker compare solo per indirizzi sudafricani e solo con la chiave API.

L'intero ordine viene quotato come un unico pacco: il peso totale, la lunghezza e la larghezza maggiori e le altezze sovrapposte. I prodotti senza dimensioni contano come cubi da 10 cm. Pesi e dimensioni vengono convertiti dalle unità del tuo negozio. L'importo in rand viene convertito nella valuta predefinita e poi mostrato nella valuta del carrello del cliente.

Le richieste a ShipLogic scadono dopo 12 secondi. Le tariffe sono in cache per 1 ora, i locker per 6 ore e gli errori per 10 minuti, così un'API lenta non rallenta ogni aggiornamento del checkout. Se non c'è una tariffa in tempo reale, il prezzo viene dalla tabella, poi da Fallback cost. Se nessuno dei due si applica, il corriere viene nascosto. Gli errori dell'API non vengono mai mostrati al cliente.

I corrieri funzionano con i temi Classic e Hummingbird. Se modifichi un corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo non prenota spedizioni, non crea lettere di vettura o etichette e non aggiorna automaticamente il tracciamento. Non c'è una mappa dei locker: i locker si scelgono da un elenco. Le tariffe in tempo reale e i locker sono solo per il Sudafrica. Gli altri paesi ricevono la tabella dei prezzi. Per ciascun corriere viene mostrata una sola tariffa (il livello di servizio più economico), senza scelta di livelli di servizio, assicurazione o extra al checkout.

Punti di ritiro

Quando il cliente sceglie il corriere locker, sotto compare un selettore di locker. Elenca i locker che ShipLogic restituisce per la città dell'indirizzo di consegna, dal più vicino. Il cliente può digitare un'altra città, un quartiere o un codice postale e cliccare su Search. Un locker va scelto prima che il cliente possa proseguire: altrimenti il passaggio della spedizione mostra Please choose a The Courier Guy locker.

Il locker viene verificato di nuovo sul server contro l'elenco di ShipLogic, anche quando l'ordine viene inviato. Nome e fornitore vengono presi da ShipLogic, mai dal browser. La scelta viene mantenuta per il carrello e viene reimpostata quando cambia l'indirizzo di consegna.

Se ShipLogic non è raggiungibile, il selettore indica che i locker non possono essere caricati e che il negozio contatterà il cliente per il locker. L'ordine può quindi essere effettuato senza locker. Viene segnalato nella pagina dell'ordine nel back office: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Ordini

Il locker scelto (nome, ID e fornitore) viene salvato con l'ordine. Compare nel blocco The Courier Guy della pagina dell'ordine nel back office, nella pagina di conferma dell'ordine, nei dettagli dell'ordine del cliente e nell'e-mail di conferma dell'ordine. L'e-mail di "nuovo ordine" del negozio (modulo Mail alerts) mostra anche l'ID del locker, oppure che nessun locker è stato scelto perché ShipLogic non era disponibile.

Numero di tracciamento The Courier Guy: prenota il pacco nel tuo portale The Courier Guy e inserisci il riferimento come numero di tracciamento della spedizione nel blocco Shipping dell'ordine (Edit). Il blocco The Courier Guy lo mostra. Il cliente lo vede nei dettagli dell'ordine e riceve l'e-mail "in transito" di PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox ottenuta su vibefox.net. Il blocco licenza License — VibeFox The Courier Guy è il primo blocco della pagina Modules > Module Manager > VibeFox The Courier Guy > Configure, sopra le impostazioni. Incolla 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: presta-shipping-the-courier-guy 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 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 un cambio 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: il dominio 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, nessuno dei due corrieri The Courier Guy (courier to the door o TCG locker) 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 i corrieri sono nascosti 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 ricontrollato 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. La disinstallazione del modulo rimuove sempre la chiave di licenza e lo stato della licenza. Il Reset di questo modulo non elimina i dati, quindi la chiave e lo stato vengono mantenuti.

Risoluzione dei problemi

The Courier Guy non compare al checkout: verifica che la licenza sia attiva e che il corriere sia acceso (Courier to the door o TCG locker). In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Controlla i limiti di peso e il Minimum order amount. Verifica che la tabella o il Fallback cost abbiano un prezzo. Il corriere locker compare solo per indirizzi sudafricani e con la chiave API. Inoltre, nella pagina del prodotto i prodotti possono essere limitati a determinati corrieri.

I clienti non vedono l'elenco dei locker: i locker richiedono la chiave API, il corriere TCG locker attivo e un indirizzo di consegna sudafricano. La pagina delle impostazioni mostra l'ultimo errore di ShipLogic, se presente, per esempio una chiave rifiutata.

Il prezzo è sempre quello della tabella: controlla gli avvisi nella pagina delle impostazioni. Una tariffa in tempo reale richiede la chiave API, l'indirizzo del mittente completo e, per i negozi non in rand, il tasso di conversione ZAR. Per la consegna a domicilio, l'indirizzo del cliente deve avere via, città, provincia e codice postale: aggiungi le province sudafricane nella sezione Advanced. Per i locker, ShipLogic deve trovare un locker vicino alla città del cliente. Attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo.

ShipLogic non è disponibile: viene mostrato il prezzo della tabella o il costo di riserva. Gli ordini con locker possono essere effettuati senza locker e vengono segnalati sull'ordine.

Dopo una modifica le tariffe sembrano obsolete: clicca su Save nella pagina del modulo. Questo cancella le tariffe e i locker in cache.

La pagina segnala che un corriere The Courier Guy non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Il ripristino mantiene le impostazioni e lo stato attivo/disattivo dei corrieri esistenti.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox The Courier Guy e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe e i locker in cache e l'ultimo errore di ShipLogic vengono sempre rimossi. Se Remove data on uninstall è attivo, i corrieri vengono eliminati (gli ordini conservano la cronologia), e vengono rimossi le impostazioni, il log e i locker dei carrelli senza ordine. Se è disattivo, i corrieri vengono solo spenti e tutte le impostazioni vengono mantenute. Reinstallando il modulo, i corrieri riprendono lo stato che avevano. I locker salvati sugli ordini non vengono mai rimossi.

The Courier Guy e ShipLogic sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da The Courier Guy o da ShipLogic.