VibeFox Correios for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
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 posting card. Servono tre dati: 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 plugin funziona solo con tariffe fisse.
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 fai clic su Install Now. Puoi anche caricare la cartella vfd_correios in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Correios, oppure fai clic 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 fai clic su Activate.
5. Inserisci l'utente API Correios, il codice di accesso, il numero della posting card, il CEP di origine e il servizio. Se la valuta del tuo negozio non è BRL, inserisci il tasso in BRL. Compila le tariffe fisse per gli altri paesi e come alternativa (vedi Configurazione).
6. Aggiungi VibeFox Correios a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Correios. Si applicano a ogni zona di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome mostrato al cliente per questa zona. Lascialo vuoto per usare il Method title globale.
La pagina delle impostazioni 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 altra valuta, oppure non ci sono né credenziali né tariffe fisse. Ogni volta che salvi le impostazioni, vengono cancellati le tariffe in cache e il token API. I numeri si possono scrivere con il punto o con la virgola.
Generali
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: Correios. Una zona può sostituirlo con un proprio titolo.
Tax status: Taxable aggiunge l'imposta WooCommerce al costo della spedizione, None non la aggiunge.
API Correios (tariffe in tempo reale in Brasile)
Per gli indirizzi in Brasile il prezzo viene dall'API tariffaria di Correios. Se l'API non restituisce un prezzo (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.
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.
Posting card: il numero della posting card (cartão de postagem) del tuo contratto: 10 cifre, di solito con due zeri all'inizio, per esempio 0012345678. I numeri più corti vengono completati con zeri iniziali. Puoi verificare il numero nella pagina Correios Fácil del sito Correios.
Homologation: usa l'ambiente di test (omologazione) di Correios con un codice di accesso di omologazione. Disattivalo su un negozio attivo.
Origin CEP: il CEP (8 cifre) da cui vengono spediti i pacchi, per esempio 01001-000.
Service: il servizio Correios per cui si calcola la tariffa 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 includa il servizio.
Other service code: facoltativo, un codice di servizio a 5 cifre del tuo contratto che non è nell'elenco, per esempio 03085. 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 senza peso. Default: 0.3. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del tuo negozio, e il carrello viene tariffato come un unico pacco.
BRL → store currency rate: il nome del campo mostra la valuta del tuo negozio. Le tariffe Correios sono in BRL. Se la valuta del tuo negozio non è BRL, inserisci quante unità della tua valuta vale 1 BRL, per esempio 0.17. Senza questo valore non si usano le tariffe in tempo reale. Se la valuta del tuo negozio è BRL, lascialo vuoto.
Tariffe fisse (per i paesi fuori dal 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 del tuo negozio: 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. Fai clic 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 ha tariffa fissa. Un prezzo base di 0 significa spedizione gratuita per quel paese.
Fixed price per: Order addebita 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 (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite.
Max cart weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 30. 0 significa nessun limite. I pacchi Correios PAC e SEDEX possono pesare fino a 30 kg.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo se un articolo del carrello ha una di queste classi di spedizione WooCommerce.
Free shipping: attiva la consegna gratuita a partire dall'importo indicato sotto.
Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. In quel caso non viene fatta alcuna richiesta all'API.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre il metodo per i paesi indicati sotto, qualunque zona corrisponda.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui il negozio spedisce. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra i calcoli delle tariffe in WooCommerce > Status > Logs, origine vfd-correios. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. L'utente API, il codice di accesso, la posting card, il token e i CEP dei clienti non vengono registrati.
Remove data on uninstall: se attivo, eliminando il plugin si rimuovono le sue impostazioni, i metodi delle zone e le tariffe in cache. La disattivazione del plugin non cancella mai nulla.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente ottiene una tariffa gratuita e non viene inviata alcuna richiesta a Correios.
Per un indirizzo in Brasile con le credenziali impostate, il plugin ottiene prima un token API per la tua posting card. Il token fornisce anche i numeri di contratto e di 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 alle dimensioni del pacco in cm. Il prezzo viene richiesto solo se il CEP di destinazione ha 8 cifre. Se tutti i prodotti hanno le dimensioni, la dimensione del pacco viene stimata da queste; 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 servizio viene salvato con la riga di spedizione dell'ordine come Correios service ed è visibile nella gestione dell'ordine.
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 la tariffa fissa, oppure il metodo viene nascosto se non c'è una tariffa fissa. Il cliente non vede mai i dettagli degli errori dell'API; finiscono nel log di WooCommerce.
Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin calcola solo le tariffe. Non ottiene le tariffe internazionali Correios (Exporta Fácil, Packet), stime dei tempi di consegna, etichette, pre-spedizioni, dichiarazioni o tracciamento. I clienti non possono scegliere un'agenzia o un armadietto Correios. Non vengono aggiunti servizi aggiuntivi (valore dichiarato, consegna in mano propria, avviso di ricevimento). Viene mostrato un solo servizio Correios per negozio, e i tassi di cambio non vengono aggiornati automaticamente.
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 Correios. Incolla la chiave in License key e fai clic 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 ricontrollare 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Correios non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. 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 ricontrollato automaticamente in background.
Risoluzione dei problemi
Correios non appare 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 sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. Senza una tariffa in tempo reale, deve esistere una tariffa fissa per il paese o per *.
Il metodo mostra una tariffa fissa invece della tariffa Correios: apri WooCommerce > Status > Logs, origine vfd-correios. Lì è registrato l'errore Correios: codice di accesso errato, servizio non presente nel tuo contratto, CEP non servito, pacco oltre 30 kg o oltre i limiti di dimensione. Controlla anche che il CEP di origine sia impostato e, se la valuta del negozio non è BRL, il tasso in BRL. Attiva Debug log per vedere ogni calcolo.
La richiesta del token non riesce: controlla 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 questa opzione disattivata.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe in cache e il token API.
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 fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic 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
La disattivazione del plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini non vengono mai toccati.
Correios è un marchio registrato del suo legittimo titolare. Questo plugin non è affiliato né approvato da Correios.