VibeFox The Courier Guy for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Chiave API ShipLogic (per le tariffe in tempo reale e i 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 non si può offrire la consegna in locker.

Spedizione in Sudafrica: le tariffe in tempo reale e i locker sono solo per indirizzi sudafricani. Il tuo negozio deve spedire in Sudafrica (WooCommerce > Settings > General > Shipping location(s)).

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella vfd_the_courier_guy in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox The Courier Guy, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

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

6. Compila la tabella dei prezzi e/o un costo di riserva.

7. Aggiungi VibeFox The Courier Guy a una zona di spedizione per il Sudafrica in WooCommerce > Settings > Shipping > Shipping zones, scegli il Delivery type (courier o TCG locker) e, se vuoi, un titolo. Aggiungilo una seconda volta per l'altro tipo di consegna.

Configurazione

Le impostazioni principali si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona contiene due campi:

Title (zone): il nome di questa tariffa al checkout in questa zona. Lascialo vuoto per usare il Method name globale.

Delivery type (zone): Courier to the door (predefinito) oppure TCG locker (customer chooses a locker). Aggiungi il metodo due volte per offrirli entrambi. I locker richiedono la chiave API ShipLogic e sono disponibili solo in Sudafrica.

Ogni volta che salvi le impostazioni, le tariffe e i locker in cache vengono cancellati. Gli avvisi sopra le impostazioni ti segnalano quando il negozio non spedisce in Sudafrica, manca la chiave API, manca il tasso di conversione ZAR o l'indirizzo del mittente, non ci sono né tabella dei prezzi né costo di riserva, oppure l'ultima richiesta a ShipLogic non è riuscita (con data ed errore).

Generale

Enable/Disable: disattiva il metodo ovunque, comprese le zone di spedizione.

Method name: il nome mostrato al checkout. Per la consegna in locker viene aggiunto "locker", per esempio "The Courier Guy locker". Una zona può sostituirlo con il proprio titolo. Predefinito: The Courier Guy.

Tax status: Taxable: le tariffe in tempo reale vengono prese senza IVA e WooCommerce aggiunge la propria imposta. None: le tariffe in tempo reale vengono prese con IVA inclusa.

API ShipLogic (tariffe in tempo reale e locker)

API key: la tua chiave API ShipLogic dal portale The Courier Guy.

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

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 del negozio non è lo ZAR, indica quanto vale 1 ZAR nella valuta del negozio, 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 è lo ZAR, lascia il campo vuoto. Il tasso non viene aggiornato automaticamente.

Indirizzo del mittente (per le 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 del negozio: usati 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 vale 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 inizia con il Sudafrica) e sulla croce per rimuoverla. Una fascia vuota o 0 usa la colonna Price. Un prezzo di 0 significa spedizione gratuita. La riga * Any country si applica ai paesi senza una riga propria e a una riga di paese senza alcun prezzo.

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

Condizioni

Min weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite.

Max weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 30. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo a partire da questo subtotale del carrello. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello da cui questo metodo è gratuito. La spedizione gratuita viene offerta solo dove il metodo ha un prezzo per la destinazione: una tariffa in tempo reale, un prezzo di tabella o il Fallback cost. Se la tabella o il Fallback cost hanno un prezzo, non viene inviata alcuna richiesta a ShipLogic per la tariffa. Lascialo vuoto per non offrire mai la spedizione gratuita.

Excluded shipping classes: nasconde il metodo se il carrello contiene prodotti di queste classi di spedizione di WooCommerce.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati di seguito, anche dove nessuna zona lo contiene.

Delivery type without zones: courier o TCG locker per questa modalità. Si usa solo con Ignore shipping zones.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. I locker sono offerti solo in Sudafrica.

Avanzate

Debug log: scrive i messaggi di debug in WooCommerce > Status > Logs, origine vfd-the-courier-guy. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. La chiave API e i dati dei clienti non vengono mai registrati.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le impostazioni e le tariffe per zona di questo metodo. Disattivare il plugin non cancella mai le impostazioni. Locker e tracciamento salvati negli ordini vengono conservati.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di spedizione, WooCommerce chiede al plugin una tariffa. Il plugin verifica prima le condizioni: peso del carrello, importo minimo d'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita e la destinazione ha un prezzo, il metodo viene mostrato con prezzo 0.

Courier to the door: il plugin chiede a ShipLogic il servizio più economico dal tuo indirizzo del mittente a quello del cliente. Prima devono essere compilati via, città, provincia e codice postale del cliente. Fino ad allora viene mostrato il prezzo della tabella.

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 che il cliente sceglie.

L'intero ordine viene quotato come un unico pacco: peso totale, lunghezza e larghezza maggiori e altezze sommate. I prodotti senza dimensioni contano come cubi da 10 cm. L'importo in rand viene convertito nella valuta del negozio. Il livello di servizio, per esempio ECO, viene salvato sulla riga di spedizione.

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 e poi dal Fallback cost. Se nessuno dei due si applica, il metodo viene nascosto.

Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin non prenota le spedizioni, non crea lettere di vettura o etichette e non aggiorna automaticamente il tracciamento. Non c'è una mappa dei locker: si scelgono da un elenco. Le tariffe in tempo reale e i locker sono solo per il Sudafrica. Gli altri paesi usano la tabella dei prezzi. Per ogni istanza di zona 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 una tariffa TCG locker nel checkout classico o in quello a blocchi, sotto di essa compare un selettore di locker. Elenca i locker che ShipLogic restituisce per la città dell'indirizzo di spedizione, dal più vicino. Il cliente può digitare un'altra città, un quartiere o un codice postale e cliccare su Search. Un locker deve essere scelto prima che l'ordine possa essere completato.

Il locker viene verificato di nuovo sul server rispetto all'elenco di ShipLogic. Nome e fornitore vengono presi da ShipLogic, mai dal browser. La scelta resta valida durante gli aggiornamenti del checkout e viene reimpostata quando cambia l'indirizzo.

Se ShipLogic non è raggiungibile, il selettore indica che i locker non possono essere caricati e l'ordine può essere completato senza locker. In questo caso l'ordine viene segnalato: "Not chosen — ShipLogic was unavailable at checkout. Agree the locker with the customer." (Non scelto: ShipLogic non era disponibile al checkout. Concorda il locker con il cliente.)

Ordini

Il locker scelto (nome, ID e fornitore) viene salvato nell'ordine. Viene mostrato nella schermata dell'ordine nel backend, nelle pagine "Grazie" e "Il mio account" e nelle e-mail d'ordine (HTML e testo semplice). L'e-mail per l'amministratore mostra anche l'ID del locker.

Nella schermata dell'ordine nel backend, gli ordini di questo metodo hanno un campo The Courier Guy tracking reference. Inserisci il riferimento dal tuo portale The Courier Guy e clicca su Save. Il riferimento viene mostrato al cliente nella pagina dell'ordine e nelle e-mail inviate successivamente.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox The Courier Guy. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il suo dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, The Courier Guy non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

The Courier Guy non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Controlla i limiti di peso, il Minimum order amount e le Excluded shipping classes. Verifica che la tabella o il Fallback cost abbiano un prezzo. Le tariffe dei locker compaiono solo per indirizzi sudafricani.

I clienti non vedono l'elenco dei locker: i locker richiedono la chiave API, un metodo di zona con Delivery type "TCG locker" e un indirizzo di spedizione 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 completo del mittente e, per i negozi che non usano il rand, il tasso di conversione ZAR. Per la consegna a domicilio devono essere compilati via, città, provincia e codice postale del cliente. Per i locker ShipLogic deve trovare un locker vicino alla città del cliente. Attiva Debug log e apri WooCommerce > Status > Logs, origine vfd-the-courier-guy.

ShipLogic non funziona: viene mostrato il prezzo della tabella o quello di riserva. Gli ordini con locker possono essere completati senza locker e vengono segnalati nell'ordine.

Dopo una modifica le tariffe sembrano obsolete: salva la pagina delle impostazioni. Questo cancella le tariffe e i locker in cache.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene le impostazioni e cancella solo le tariffe e i locker in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, le tariffe e i locker in cache e l'ultimo errore vengono sempre rimossi. Impostazioni e tariffe per zona vengono rimosse solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Locker e riferimenti di tracciamento salvati negli ordini non vengono mai rimossi, e gli ordini esistenti mantengono le proprie righe di spedizione.

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