VibeFox Correios for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Contratto Correios (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API tariffaria di Correios Web Services (CWS) e richiedono le credenziali di un contratto Correios con una carta di spedizione. Servono tre valori: il tuo utente Meu Correios (di solito il CNPJ o il CPF del contratto), il codice di accesso API e il numero della carta di spedizione. Genera il codice di accesso nel portale Correios Web Services (cws.correios.com.br; per l'ambiente di test cwshom.correios.com.br). Ti serve anche il CEP da cui spedisci. Senza credenziali l'estensione funziona solo con le tariffe fisse.

Chiave di licenza VibeFox: acquistata 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. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_correios-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_correios.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_correios-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer puoi anche copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

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

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

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

5. Inserisci l'utente API Correios, il codice di accesso, il numero della carta di spedizione, il CEP di origine e il servizio. Se la valuta predefinita del tuo negozio non è BRL, inserisci il tasso in BRL. Compila le tariffe fisse per gli altri paesi e come alternativa (vedi Configurazione), attiva Enable Correios e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_correios.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 a esso.

3. Vai su Extensions > Extensions, scegli il tipo di estensione Shipping. Trova VibeFox Correios, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable Correios e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Correios che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Correios > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Correios e i token API in cache. I numeri si possono digitare con il punto o con la virgola. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

La pagina mostra avvisi quando le tariffe in tempo reale o il metodo non possono funzionare: sono compilate solo alcune delle tre credenziali, manca il CEP di origine, manca il tasso in BRL per un negozio con un'altra valuta, oppure non ci sono né credenziali né tariffe fisse. Ogni avviso indica se nel frattempo si usano le tariffe fisse o se il metodo è nascosto. Compare un avviso anche se il negozio non ha una classe di peso con unità kg o una classe di lunghezza con unità cm; le unità dei prodotti vengono allora convertite in base al nome dell'unità della loro classe (le unità sconosciute vengono lette come kg o cm). Controlla System > Localisation > Weight Classes e Length Classes.

Il salvataggio viene rifiutato con un messaggio se il titolo del metodo è vuoto o non valido (massimo 64 caratteri, senza < > ; = # { }), se un campo numerico o un prezzo in Country prices non è un numero pari o superiore a 0, se il tasso in BRL è 0, se Min cart weight è maggiore di Max cart weight, se il CEP di origine non ha 8 cifre, se il codice dell'altro servizio ha più di 5 cifre, o se Sort order non è un numero intero. Non viene salvato nulla finché non correggi il valore.

Generale

Le impostazioni si applicano a tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Conditions, oppure a un elenco di paesi con Ignore shipping zones.

Enable Correios: mostra o nasconde Correios al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Correios. Obbligatorio.

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

API Correios (tariffe in tempo reale in Brasile)

Per gli indirizzi in Brasile la tariffa proviene dall'API tariffaria di Correios. Se l'API non restituisce una tariffa (API non disponibile, CEP non servito, pacco troppo grande), si usa la tariffa fissa di Country prices, oppure il metodo viene nascosto se non ce n'è una. I dettagli degli errori vanno nel registro, mai al cliente.

API user: il tuo accesso al portale Meu Correios, di solito il CNPJ o il CPF del contratto. Svuotarlo cancella anche il codice di accesso salvato.

Access code: il codice di accesso API (código de acesso) generato nel portale Correios Web Services. Non è la password del portale. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it (empty the API user as well to remove it). Inserisci un nuovo valore solo se vuoi cambiarlo. Per rimuovere il codice salvato, svuota API user e salva.

Posting card: il numero della carta di spedizione (cartão de postagem) del tuo contratto: 10 cifre, di solito inizia con due zeri, per esempio 0012345678. I numeri più corti vengono completati con zeri iniziali. Puoi verificare il numero nella pagina Correios Fácil del sito di Correios.

Homologation: usa l'ambiente di test (homologation) di Correios: le richieste vanno a apihom.correios.com.br con un codice di accesso di test. Disattivalo in un negozio live.

Origin CEP: il CEP (8 cifre) da cui vengono spediti i pacchi, per esempio 01001-000.

Service: il servizio Correios tariffato al checkout. Codici standard: PAC (04510, predefinito), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Codici di contratto: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). I codici di contratto richiedono una carta di spedizione di un contratto che include il servizio.

Other service code: facoltativo, un codice servizio di 5 cifre del tuo contratto che non è nell'elenco, per esempio 03085. Un codice più corto viene completato con zeri iniziali. Se compilato, viene usato al posto di Service.

Package format: il tipo di oggetto inviato a Correios.

Default product weight (kg): inviato a Correios per ogni prodotto che non ha un peso. Predefinito: 0.3. I pesi e le dimensioni dei prodotti vengono convertiti dalle loro classi di peso e di lunghezza, e il carrello viene tariffato come un unico pacco.

BRL → store currency rate: il nome del campo mostra la valuta predefinita del tuo negozio, per esempio BRL → EUR rate. Le tariffe Correios sono in BRL. Se la valuta predefinita non è BRL, inserisci quante unità della tua valuta vale un BRL, per esempio 0.17. Senza questo valore le tariffe in tempo reale non vengono usate. Il tasso deve essere maggiore di 0. Se la valuta predefinita è BRL, lascia il campo vuoto.

Tariffe fisse (usate per i paesi fuori dal Brasile, senza credenziali API e come alternativa quando l'API non restituisce una tariffa)

Country prices: una tabella di paesi con una tariffa Base e tariffe in base al peso del carrello nella valuta predefinita del tuo negozio, IVA esclusa: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL oltre 5 kg. Una tariffa di taglia vuota o pari a zero usa la tariffa Base. Clicca su Add country per aggiungere una riga e sul pulsante × per rimuoverla. La riga * All other countries imposta le tariffe per tutti i paesi che non hanno una riga propria. Un paese senza riga (e senza *) non ha una tariffa fissa. Una riga richiede almeno una tariffa. Una tariffa base di 0 significa spedizione gratuita per quel paese.

Fixed price per: Order (predefinito) addebita la tariffa una sola volta. Item (price × quantity) la moltiplica per il numero di articoli nel carrello. Questo vale solo per le tariffe fisse. Le tariffe in tempo reale vengono sempre calcolate per l'intero pacco.

Condizioni

Min cart weight (kg): nasconde il metodo se il carrello pesa meno di questo valore. 0 significa nessun limite. Non può essere maggiore di Max cart weight.

Max cart weight (kg): nasconde il metodo se il carrello pesa più di questo valore. Predefinito: 30. 0 significa nessun limite, un campo vuoto significa 30 kg. I pacchi Correios PAC e SEDEX possono pesare fino a 30 kg.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) raggiunge questo importo. Lascia il campo vuoto per mostrarlo sempre.

Free shipping: attiva la spedizione gratuita a partire dall'importo indicato sotto.

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) a partire dal quale la spedizione è gratuita. In quel caso non viene fatta nessuna richiesta all'API.

Tax class: la classe fiscale aggiunta al costo di spedizione, oppure No tax (predefinito).

Geo zone: offri Correios solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non si usa con Ignore shipping zones.

Disponibilità senza zone di spedizione

Normalmente il metodo viene offerto nella zona geografica selezionata in Conditions (in tutte le zone se non ne è selezionata nessuna).

Ignore shipping zones: offre il metodo per i paesi indicati sotto, indipendentemente dalla zona geografica corrispondente. La Geo zone in Conditions non viene quindi verificata.

Countries: i paesi di destinazione per questa modalità. Lascia il campo vuoto per usare tutti i paesi abilitati nel negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_crr_debug.log.php (in OpenCart 4 system/storage/logs/vfd_crr_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche quando questa opzione è disattivata. Utente API, codice di accesso, carta di spedizione, token e CEP dei clienti non vengono registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_crr_debug.old.log.php e si inizia un nuovo registro.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni Correios e il registro. Se disattivo (predefinito), vengono conservati per una nuova installazione. I servizi Correios salvati con gli ordini restano sempre.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il codice di accesso non viene esportato.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio in un altro negozio. I valori vengono verificati come in un normale salvataggio. Il codice di accesso salvato viene conservato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione la tariffa Correios. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, Correios non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione verifica poi le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle tasse. Se si applica la spedizione gratuita, la tariffa è 0 e nessuna richiesta viene inviata a Correios.

Per un indirizzo in Brasile con le credenziali impostate, l'estensione ottiene prima un token API per la tua carta di spedizione. Il token fornisce anche i numeri di contratto e di ufficio regionale, quindi la tariffa è quella del tuo contratto. Poi richiede la tariffa del servizio scelto in base al CEP di origine e di destinazione, al peso del pacco in grammi e alle dimensioni del pacco in cm. Una tariffa viene richiesta solo quando il CEP di destinazione ha 8 cifre. Quando tutti i prodotti hanno le dimensioni, quelle del pacco vengono stimate da esse; altrimenti viene inviata la dimensione minima di Correios. I pacchi oltre 30 kg non vengono inviati all'API. La tariffa in BRL viene convertita con il tuo tasso. La tariffa viene calcolata nella valuta predefinita del negozio, arrotondata ai decimali di quella valuta, e mostrata al cliente nella sua valuta con la tassa della Tax class selezionata.

Ogni tariffa viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata per 10 minuti, così un'interruzione dell'API non rallenta ogni aggiornamento del checkout. Il token viene memorizzato nella cache fino a poco prima della scadenza (al massimo per la durata della cache di OpenCart, 1 ora per impostazione predefinita) e rinnovato automaticamente; se Correios lo rifiuta, ne viene richiesto uno nuovo e la richiesta della tariffa viene ripetuta una volta. Il timeout dell'API è di 12 secondi.

Se l'API non restituisce una tariffa, si usa la tariffa fissa, oppure il metodo viene nascosto quando non c'è una tariffa fissa. Il cliente non vede mai i dettagli degli errori API; questi vanno nel registro di debug.

L'estensione calcola solo le tariffe. Non ottiene le tariffe internazionali di Correios (Exporta Fácil, Packet), le stime dei tempi di consegna, le etichette, le prenotazioni preventive, le dichiarazioni o il tracciamento. I clienti non possono scegliere un ufficio o un punto di ritiro Correios. Non vengono aggiunti servizi aggiuntivi (valore dichiarato, consegna in mani proprie, avviso di ricevimento). Mostra un solo servizio Correios per negozio, e i tassi di cambio non vengono aggiornati automaticamente.

In OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione nella pagina del checkout e sceglie Correios nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con Correios, l'estensione salva come è stato calcolato il prezzo della spedizione. La pagina dell'ordine in Sales > Orders mostra quindi un blocco Correios con Correios service (per esempio PAC — contract (03298)) e Price: Live price (Correios API), Fixed price oppure Free shipping. Il blocco viene mostrato solo nell'amministrazione, non nelle email ai clienti, e resta visibile quando l'estensione è disattivata.

In OpenCart 4 il checkout mantiene un solo ordine e lo aggiorna quando il cliente conferma di nuovo. I dati Correios dell'ordine vengono aggiornati insieme ad esso e, se il cliente passa a un altro metodo di spedizione, il blocco Correios non viene più mostrato per quell'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Correios è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox Correios > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: opencart-shipping-correios 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 cambiare 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 o License expired on seguito da 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 dalla 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, Correios non viene mostrato ai clienti al checkout e non viene calcolata nessuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione dallo stesso browser vede ancora il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. In OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, quindi senza una chiave attiva il metodo è nascosto per 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 aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve un cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Correios non compare al checkout: verifica che la licenza sia attiva e che Enable Correios sia attivo. Controlla Geo zone (o Ignore shipping zones e Countries), i limiti di peso e Minimum order amount. Senza una tariffa in tempo reale, deve esistere una tariffa fissa per il paese o per *. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Il metodo mostra una tariffa fissa al posto della tariffa Correios: guarda il campo Log nella pagina dell'estensione. Lì vengono registrati gli errori Correios: codice di accesso errato, servizio non nel tuo contratto, CEP non servito, pacco oltre 30 kg o oltre i limiti di dimensione. Verifica anche che il CEP di origine sia impostato, che il CEP del cliente abbia 8 cifre e, se la valuta predefinita non è BRL, il tasso in BRL. Attiva Debug log per vedere ogni calcolo.

La richiesta del token non riesce: verifica utente API, codice di accesso, carta di spedizione e ambiente. Un codice di accesso di test funziona solo con Homologation attivo, e un codice di produzione solo con esso disattivato.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe in cache e il token API.

La pagina dice "Warning: You do not have permission to modify VibeFox Correios!": il tuo gruppo di utenti amministratori potrebbe avere solo il permesso di visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_correios (OpenCart 3) o extension/vfd_correios/shipping/vfd_correios (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'host dell'API Correios può essere sostituito con l'impostazione vfd_crr_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 Correios. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Correios, Sort order, Tax class e Geo zone. Le tariffe e i token in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni Correios e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I servizi Correios salvati con gli ordini restano sempre, e gli ordini esistenti mantengono il loro metodo e costo di spedizione.

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

Correios è un marchio del suo rispettivo titolare. Questa estensione non è affiliata né approvata da Correios.