VibeFox Correios 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 precedenti.

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 posting card. 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 posting card. Genera il codice di accesso nel portale Correios Web Services (cws.correios.com.br; per l'omologazione cwshom.correios.com.br). Ti serve anche il CEP da cui spedisci. Senza credenziali, il modulo funziona solo con tariffe fisse.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Correios nell'elenco dei moduli e clicca su Configure.

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

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

All'installazione il modulo crea il corriere Correios con il testo del tempo di consegna Correios (Brazilian Post). Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempo 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 Correios > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Correios e i token API memorizzati nella cache. I numeri possono essere inseriti con il punto o con la virgola.

La pagina mostra avvisi quando le tariffe in tempo reale o il corriere 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 corriere viene nascosto. Compare un avviso anche se l'unità di peso o di dimensione del negozio non è riconosciuta dal modulo (viene quindi letta come kg o cm); imposta kg, g, lb o oz e cm, mm, m o in in International > Localization (Local units).

Il salvataggio viene rifiutato con un messaggio se il titolo del metodo è vuoto o non valido (massimo 64 caratteri), 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 o se l'altro codice di servizio ha più di 5 cifre. Non si salva nulla finché non correggi il valore.

Generale

Enable Correios: attiva o disattiva il corriere in tutte le zone contemporaneamente. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

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

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

API Correios (tariffe in tempo reale in Brasile)

Per gli indirizzi in Brasile il prezzo proviene dall'API tariffaria di Correios. Se l'API non restituisce un prezzo (API non disponibile, CEP non servito, pacco troppo grande), si usa il prezzo fisso di Country prices, oppure il corriere viene nascosto se non ce n'è uno. I dettagli degli errori vanno nel log, mai al cliente.

API user: il tuo accesso al portale Meu Correios, di solito il CNPJ o il CPF del contratto.

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 sia API user sia Access code e salva.

Posting card: il numero della posting card (cartão de postagem) del tuo contratto: 10 cifre, di solito inizia con due zeri, ad 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 (omologazione) di Correios: le richieste vanno ad apihom.correios.com.br con un codice di accesso di omologazione. Disattivalo su un negozio in produzione.

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

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

Other service code: facoltativo, un codice di servizio a 5 cifre del tuo contratto che non è nell'elenco, ad 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: in kg, inviato a Correios per ogni prodotto senza peso. Predefinito: 0.3. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del tuo negozio (la descrizione del campo le mostra), e il carrello viene tariffato come un unico pacco.

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

Tariffe fisse (usate per i paesi al di fuori del Brasile, senza credenziali API e come alternativa quando l'API non restituisce un prezzo)

Country prices: una tabella di paesi con un prezzo Base e prezzi 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. Un prezzo di taglia vuoto o pari a zero usa il prezzo Base. Clicca su Add country per aggiungere una riga e sulla croce per rimuoverne una. La riga * Default (all other countries) imposta i prezzi per tutti i paesi senza una riga propria. Un paese senza riga (e senza *) non riceve una tariffa fissa. Una riga senza alcun prezzo non viene salvata. Un prezzo che non è un numero, o che è negativo, interrompe il salvataggio con un errore. Un prezzo base di 0 significa spedizione gratuita per quel paese.

Fixed price per: Order applica il prezzo una sola volta. Item (price × quantity) lo 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: in kg, nasconde il corriere sotto questo peso del carrello. 0 significa nessun limite. Non può essere maggiore di Max cart weight.

Max cart weight: in kg, nasconde il corriere sopra questo peso del carrello. Predefinito: 30. 0 significa nessun limite, un campo vuoto significa 30 kg. I pacchi PAC e SEDEX di Correios possono pesare fino a 30 kg.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono la spedizione, dopo gli sconti, prima delle tasse) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

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

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) a partire dal quale la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta all'API.

Disponibilità senza zone di spedizione

Normalmente il corriere viene mostrato nelle zone a cui è assegnato in Shipping > Carriers.

Ignore shipping zones: offre il corriere per i paesi indicati sotto, indipendentemente dalla zona corrispondente. Al salvataggio il corriere viene aggiunto a tutte le zone. Disattivando l'opzione si rimuovono le zone che ha aggiunto. Una zona creata successivamente, mentre l'opzione è attiva, viene aggiunta automaticamente.

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

Avanzate

Debug log: scrive i calcoli dei prezzi in logs/vfd_crr_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. L'utente API, il codice di accesso, la posting card, il token e i CEP dei clienti non vengono registrati.

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

Remove data on uninstall: se attiva, disinstallando il modulo vengono eliminati le impostazioni, il corriere, i servizi degli ordini, le tariffe in cache e il log. Se disattiva, tutto viene conservato per una reinstallazione.

Come funziona al checkout

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

Per un indirizzo in Brasile con le credenziali impostate, il modulo ottiene prima un token API per la tua posting card. Il token fornisce anche i numeri del contratto e dell'ufficio regionale, quindi il prezzo è quello del tuo contratto. Poi richiede il prezzo del servizio scelto in base al CEP di origine e di destinazione, al peso del pacco in grammi e alla dimensione del pacco in cm. Un prezzo viene richiesto solo quando il CEP di destinazione ha 8 cifre. Quando tutti i prodotti hanno le dimensioni, la dimensione del pacco viene stimata da esse; altrimenti viene inviata la dimensione minima Correios. I pacchi oltre 30 kg non vengono inviati all'API. Il prezzo in BRL viene convertito con il tuo tasso. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.

Ogni prezzo viene memorizzato nella cache per 1 ora per pacco. Una richiesta non riuscita viene memorizzata nella cache 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 e rinnovato automaticamente; se Correios lo rifiuta, ne viene richiesto uno nuovo e la richiesta di prezzo viene ripetuta una volta. Il timeout dell'API è di 12 secondi.

Se l'API non restituisce un prezzo, si usa il prezzo fisso, oppure il corriere viene nascosto se non c'è un prezzo fisso. Il cliente non vede mai i dettagli degli errori dell'API; questi vanno nel log di debug.

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

Il modulo calcola solo le tariffe. Non ottiene le tariffe internazionali Correios (Exporta Fácil, Packet), le stime dei tempi di consegna, le etichette, le pre-spedizioni, le dichiarazioni o il tracciamento. I clienti non possono scegliere un'agenzia o un armadietto Correios. I servizi aggiuntivi (valore dichiarato, consegna in mano propria, avviso di ricevimento) non vengono aggiunti. Mostra un solo servizio Correios per negozio, e i tassi di cambio non vengono aggiornati automaticamente.

Ordini

Quando un ordine viene effettuato con il corriere Correios, il modulo salva come è stato calcolato il prezzo della spedizione. La pagina dell'ordine nel back office mostra quindi un blocco Correios con Correios service (per una tariffa in tempo reale, ad esempio PAC — contract (03298)) e Price source: Live price (Correios API), Fixed price o Free shipping.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Correios è il primo blocco di Modules > Module Manager > VibeFox Correios > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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 di essi ci sono la riga Product: presta-shipping-correios 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, ad 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 uno slot di 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 dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Correios non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è 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 influenzati.

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 alcuna attività cron. Disinstallare o reimpostare il modulo 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. 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 sia consentito). Controlla i limiti di peso e Minimum order amount. Senza una tariffa in tempo reale, deve esistere una tariffa fissa per il paese o per *. I prodotti possono inoltre essere limitati a determinati corrieri nella pagina del prodotto.

Il corriere mostra una tariffa fissa invece della tariffa Correios: guarda il campo Log nella pagina del modulo. Lì vengono registrati gli errori di Correios: codice di accesso errato, servizio non presente 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 è il BRL, il tasso in BRL. Attiva Debug log per vedere ogni calcolo.

La richiesta del token fallisce: verifica l'utente API, il codice di accesso, la posting card e l'ambiente. Un codice di accesso di omologazione funziona solo con Homologation attivo, e un codice di produzione solo con l'opzione disattivata.

Le tariffe sembrano non aggiornate dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le tariffe in cache e il token API.

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

Il salvataggio indica che non hai i permessi: il tuo profilo dipendente può visualizzare il modulo ma non configurarlo. Salvare le impostazioni e svuotare il log richiedono il permesso di configurazione del modulo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Correios e scegli Uninstall. La chiave di licenza, lo stato della licenza, le tariffe e i token in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono la loro cronologia) e vengono rimosse le impostazioni, i servizi salvati degli ordini e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere viene ripristinato con lo stato che aveva prima.

Correios è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato a Correios né approvato da Correios.