VibeFox The Courier Guy for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Chiave API ShipLogic (per tariffe in tempo reale e locker): The Courier Guy opera sulla piattaforma ShipLogic. Crea una chiave API nel tuo portale corrieri The Courier Guy, alla voce Settings > API Keys (account business). Senza la chiave viene usata solo la tabella prezzi e non viene offerta l'opzione locker.

Spedizione in Sudafrica: le tariffe in tempo reale e i locker sono validi solo per indirizzi sudafricani. Il Sudafrica deve essere un paese abilitato del negozio (System > Localisation > Countries), e la tariffa corriere in tempo reale richiede le province sudafricane (zone), che OpenCart 3 include già.

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. Estrailo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_the_courier_guy-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_the_courier_guy.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_the_courier_guy-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella radice del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox The Courier Guy e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.

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

5. Attiva Courier to the door e/o TCG locker e 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 è lo ZAR, il ZAR conversion rate.

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

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_the_courier_guy.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 The Courier Guy, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come ai passaggi da 4 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione entrambe le opzioni restano disattivate finché non ne attivi una e salvi. L'estensione è attiva finché almeno una delle due opzioni è attiva. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni mantenute.

Configurazione

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

Se un nome di opzione, la classe fiscale, l'ordinamento o la zona geografica non sono validi, non viene salvato nulla e la pagina mostra il motivo, per esempio Enter a valid option name (1-64 characters, without < > ; = # { }). Un numero non valido (per esempio negativo) non viene salvato: la pagina indica il campo e mantiene il valore precedente, mentre il resto viene salvato. Finché almeno un'opzione è attiva, gli avvisi in cima alla pagina segnalano se il Sudafrica non è un paese abilitato, se manca la chiave API, il tasso di conversione in ZAR o l'indirizzo del mittente, se non ci sono né tabella prezzi né costo di riserva, se il Sudafrica non ha zone (province) o se l'ultima richiesta a ShipLogic è fallita (con data ed errore). Compare un avviso anche se il negozio non ha un'unità di peso in kg o un'unità di lunghezza in cm.

Generale

Ogni tipo di consegna è un'opzione a sé stante al checkout.

Courier to the door: offre la consegna a domicilio tramite corriere The Courier Guy all'indirizzo del cliente. Predefinito: disattivato.

Courier option name: il nome dell'opzione corriere al checkout. Predefinito: The Courier Guy. Obbligatorio, massimo 64 caratteri, senza < > ; = # { }.

TCG locker: il cliente sceglie un locker al checkout. È offerto solo per indirizzi sudafricani e solo con la chiave API ShipLogic. Predefinito: disattivato.

Locker option name: il nome dell'opzione locker al checkout. Predefinito: The Courier Guy locker. Stesse regole del nome del corriere.

Tax status: la classe fiscale di entrambe le opzioni. Con una classe fiscale, le tariffe in tempo reale vengono prese senza IVA e OpenCart aggiunge l'imposta della classe. None (live rates including VAT) (predefinito): le tariffe in tempo reale vengono prese IVA inclusa.

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

API ShipLogic

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 se vuoi 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 che non è un numero non viene salvato.

Tariffe in tempo reale (per indirizzi sudafricani; se non è disponibile alcuna tariffa in tempo reale, viene usata la tabella prezzi)

La tariffa in tempo reale è il servizio ShipLogic più economico dal tuo indirizzo di spedizione all'indirizzo del cliente (corriere) oppure al locker più vicino alla città del cliente (locker). Richiede la chiave API, l'indirizzo del mittente e, per i negozi che non usano i rand, un tasso di conversione.

Price source: da dove proviene il prezzo.

ZAR conversion rate: ShipLogic quota in rand sudafricani (ZAR). Se la valuta predefinita del tuo negozio non è lo ZAR, inserisci quanto vale 1 ZAR nella tua valuta, per esempio 0.05. Deve essere maggiore di 0. Senza di essa le tariffe in tempo reale non vengono usate e si applica la tabella prezzi. Se la valuta del negozio è lo ZAR, lascia il campo vuoto. Il tasso non viene aggiornato automaticamente.

Indirizzo del mittente (dove The Courier Guy ritira i pacchi, in Sudafrica)

L'indirizzo del negozio in OpenCart è testo libero, quindi l'indirizzo del mittente si inserisce qui. Via, città, provincia e codice postale sono necessari per le tariffe in tempo reale.

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 una delle 9 province sudafricane dall'elenco.

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

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

Calculation type: si applica solo alla tabella prezzi. Una tariffa in tempo reale riguarda sempre 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 sul pulsante di rimozione per eliminarne 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. Lascia il campo vuoto per nascondere le opzioni in quel caso.

Condizioni (entrambe le opzioni)

Min weight (kg): nasconde le opzioni sotto questo peso del carrello. 0 significa nessun limite (predefinito).

Max weight (kg): nasconde le opzioni sopra questo peso del carrello. 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 entrambi i limiti mantengono i valori precedenti.

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

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

Disponibilità

Geo zone: offre le opzioni solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa ogni indirizzo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: per il tipo di consegna qui sotto la zona geografica non viene verificata. L'opzione viene offerta invece nei paesi elencati qui sotto.

Delivery type without zones: Courier to the door (predefinito) oppure TCG locker (customer chooses a locker). Usato solo con Ignore shipping zones. L'altro tipo continua a seguire Geo zone.

Countries: i paesi di destinazione per quella modalità. Usato solo con Ignore shipping zones. Lascia vuoto per consentire tutti i paesi. I locker vengono offerti solo in Sudafrica.

Avanzate

Debug log: scrive i messaggi di debug in storage/logs/vfd_tcgr_debug.log.php. Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. La chiave API e i dati dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene avviato un nuovo log.

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

Remove data on uninstall: se attiva, la disinstallazione dell'estensione elimina le impostazioni, il log e le scelte di locker dei checkout senza ordine. Le tariffe e i locker in cache vengono sempre rimossi. I locker e i riferimenti di tracciamento 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 in un altro negozio. I valori vengono controllati come in un normale salvataggio. La chiave API salvata viene conservata.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di ogni opzione. L'opzione deve superare la Geo zone (oppure, con Ignore shipping zones, l'elenco dei paesi). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione verifica poi le condizioni: peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, prima delle imposte e dopo lo sconto del coupon. Se si applica la spedizione gratuita, il prezzo è 0.

Courier to the door: l'estensione chiede a ShipLogic il servizio più economico dal tuo indirizzo di spedizione all'indirizzo del cliente. L'indirizzo deve avere via, città, provincia e codice postale. Fino ad allora viene usata la tabella prezzi.

TCG locker: la tariffa in tempo reale è il servizio porta-locker più economico fino al locker più vicino alla città del cliente. Non viene ricalcolata per il locker scelto dal cliente. L'opzione 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 sommate. I prodotti senza dimensioni contano come cubi da 10 cm. Pesi e dimensioni vengono convertiti a partire dalle classi di peso e di lunghezza dei prodotti. L'importo in rand viene convertito nella valuta predefinita, arrotondato ai suoi decimali e mostrato al cliente nella sua valuta con l'imposta della classe fiscale selezionata.

Le richieste a ShipLogic scadono dopo 12 secondi. Le tariffe sono memorizzate 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 preso dalla tabella e poi da Fallback cost. Se nessuna delle due si applica, l'opzione viene nascosta. Gli errori API non vengono mai mostrati al cliente.

L'estensione non prenota spedizioni, non crea lettere di vettura o etichette e non aggiorna il tracciamento automaticamente. Non esiste una mappa dei locker: si scelgono da un elenco. Le tariffe in tempo reale e i locker valgono solo per il Sudafrica. Gli altri paesi usano la tabella prezzi. Per ogni opzione viene mostrata una sola tariffa (il livello di servizio più economico), senza scelta di livelli di servizio, assicurazioni o extra al checkout.

Con OpenCart 4, il cliente clicca su Choose nel blocco del metodo di spedizione del checkout e sceglie l'opzione corriere o locker nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Punti di ritiro

Quando il cliente sceglie l'opzione locker nel passaggio del metodo di spedizione, sotto compare un selettore dei locker: un campo di ricerca (per impostazione predefinita la città dell'indirizzo di consegna) e un elenco dei locker con nome, indirizzo e orari. Il cliente può digitare un'altra città, un quartiere o un codice postale e cliccare su Search. Un locker deve essere scelto prima che il cliente possa proseguire; altrimenti il passaggio mostra Please choose a The Courier Guy locker.

Il locker viene verificato sul server rispetto all'elenco di ShipLogic quando il cliente prosegue e di nuovo quando l'ordine viene effettuato. Nome e fornitore vengono presi da ShipLogic, mai dal browser. La scelta dipende dal paese e dalla città o dal codice postale dell'indirizzo: se cambia l'indirizzo di consegna, il cliente sceglie di nuovo.

Se ShipLogic non è raggiungibile, il selettore mostra Lockers cannot be loaded right now. You can place the order without choosing one - the store will contact you about the locker. L'ordine può quindi essere effettuato senza locker. Viene segnalato nella pagina dell'ordine in amministrazione: Not chosen - ShipLogic was unavailable at checkout. Agree the locker with the customer.

Con OpenCart 4, il selettore dei locker compare nella finestra Shipping method options, sotto l'opzione locker, e viene ricaricato ogni volta che la finestra si apre, perché l'indirizzo può cambiare nel checkout in un'unica pagina. Il pulsante Continue della finestra non procede senza un locker dell'elenco, con lo stesso messaggio, e un ShipLogic non disponibile non blocca comunque l'ordine. OpenCart 4 mantiene un ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e il locker dell'ordine viene aggiornato con esso.

Ordini

Il locker scelto viene aggiunto al metodo di spedizione dell'ordine, per esempio "The Courier Guy locker: nome — indirizzo". Questo testo compare in Sales > Orders, nella pagina dell'ordine del cliente, nella fattura e nelle e-mail d'ordine.

La pagina dell'ordine in Sales > Orders ha un pannello The Courier Guy sopra la cronologia per ogni ordine spedito con The Courier Guy. Per un ordine con locker mostra nome, ID e fornitore del locker, con not verified (ShipLogic was unavailable at checkout) quando il locker non è stato verificato, oppure il messaggio Not chosen quando ShipLogic non era disponibile. Il pannello viene mostrato anche quando l'estensione è disattivata.

The Courier Guy tracking reference: prenota il pacco nel tuo portale The Courier Guy, inserisci il suo riferimento in questo campo del pannello e clicca su Save. Svuota il campo e salva per rimuoverlo. Gli utenti amministratori senza il permesso di modificare gli ordini vedono il riferimento in sola lettura. Il cliente vede il riferimento nella pagina dell'ordine del proprio account (clienti registrati) e nelle e-mail di stato dell'ordine quando avvisi il cliente. L'e-mail di nuovo ordine non contiene il riferimento, perché viene inserito in seguito.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox The Courier Guy è il primo blocco di Extensions > Extensions > Shipping > VibeFox The Courier Guy > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Poi 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: opencart-shipping-the-courier-guy 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 modificare 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 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, 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 nella 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, nessuna delle due opzioni The Courier Guy (consegna a domicilio con corriere o TCG locker) viene mostrata ai clienti al checkout, e non viene calcolata alcuna tariffa. Un utente amministratore connesso all'amministrazione nello stesso browser vede ancora le opzioni nel negozio, contrassegnate 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 il login dell'amministrazione, quindi senza una chiave attiva le opzioni sono nascoste 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 sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma gli aggiornamenti e l'assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente all'apertura della Dashboard dell'amministrazione o della pagina Edit: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

The Courier Guy does not appear at checkout: verifica che la licenza sia attiva e che l'opzione sia attivata (Courier to the door o TCG locker). Controlla Geo zone (oppure Ignore shipping zones e Countries), i limiti di peso e Minimum order amount. Verifica che la tabella o Fallback cost abbiano un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes. L'opzione locker compare solo per indirizzi sudafricani e con la chiave API.

Customers see no locker list: i locker richiedono la chiave API, TCG locker attivato e un indirizzo di consegna sudafricano. La pagina delle impostazioni mostra l'ultimo errore di ShipLogic, se presente, per esempio una chiave rifiutata.

The price is always the table price: 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 i rand, il tasso di conversione in ZAR. Per la consegna a domicilio, l'indirizzo del cliente deve avere via, città, provincia (zona) e codice postale. Per i locker, ShipLogic deve trovare un locker vicino alla città del cliente. Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione.

ShipLogic is down: viene mostrato il prezzo della tabella o di riserva. Gli ordini con locker possono essere effettuati senza locker e vengono segnalati nell'ordine.

Rates look outdated after a change: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe e i locker in cache.

The page says "Warning: You do not have permission to modify VibeFox The Courier Guy!": il tuo gruppo utenti amministratori potrebbe poter solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_the_courier_guy (OpenCart 3) o extension/vfd_the_courier_guy/shipping/vfd_the_courier_guy (OpenCart 4) in System > Users > User Groups.

For developers: l'indirizzo dell'API ShipLogic può essere sostituito con l'impostazione vfd_tcgr_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 The Courier Guy. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre lo stato dell'estensione, Sort order, Tax status e Geo zone. Le tariffe e i locker in cache e l'ultimo errore di ShipLogic vengono sempre rimossi. Se Remove data on uninstall è attiva, vengono eliminati anche le impostazioni, il log e le scelte di locker dei checkout senza ordine. Se è disattivata, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I locker e i riferimenti di tracciamento salvati negli ordini non vengono mai rimossi, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

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

The Courier Guy e ShipLogic sono marchi dei rispettivi proprietari. Questa estensione non è affiliata né approvata da The Courier Guy o ShipLogic.