VibeFox Andreani 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.
Account Andreani (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API di preventivi di Andreani. Andreani rilascia ai clienti business le credenziali API, un codice cliente e i numeri di contratto, di solito a partire da circa 300 spedizioni al mese. Consulta developers.andreani.com oppure scrivi a ventapyme@andreani.com. Ti servono nome utente e password dell'API, codice cliente e numero di contratto. Andreani rilascia un contratto separato per ogni servizio (consegna a domicilio, ritiro in filiale). Senza accesso all'API, usa i prezzi fissi. Il selettore della filiale funziona senza credenziali.
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_andreani in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Andreani, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Imposta il nome, la fonte delle tariffe, i prezzi per paese (per esempio AR=5000) e, per le tariffe in tempo reale, le credenziali API, il codice cliente e il numero di contratto (vedi Configurazione).
6. Vai su WooCommerce > Settings > Shipping > Shipping zones, apri o crea una zona per l'Argentina e aggiungi VibeFox Andreani. Nella finestra della zona puoi impostare il titolo, la modalità di consegna e un contratto diverso per questa opzione. Puoi anche attivare Ignore shipping zones e scegliere dei paesi.
Configurazione
Le impostazioni principali si trovano in WooCommerce > Settings > Shipping > VibeFox Andreani. Valgono per tutte le zone di spedizione. Gli avvisi su impostazioni mancanti (credenziali API, numero di contratto, tasso di cambio, nessun prezzo per l'Argentina) appaiono in cima alla pagina. Ogni volta che salvi le impostazioni, il token, l'elenco delle filiali e le tariffe memorizzati nella cache vengono cancellati.
Finestra della zona (quando aggiungi il metodo a una zona di spedizione)
Title: il nome di questa opzione al checkout. Lascialo vuoto per usare il Name globale.
Delivery modality: Use global setting oppure una delle quattro modalità (vedi sotto). Aggiungi il metodo due volte a una zona, per esempio porta a porta e ritiro in filiale, per offrirli entrambi.
Contract number: il contratto Andreani per questa opzione. Lascialo vuoto per usare il contratto globale.
Generale
Enable/Disable: attiva o disattiva la spedizione con Andreani in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Andreani.
Tax status: Taxable significa che WooCommerce aggiunge l'imposta al costo di spedizione, quindi la tariffa API viene presa senza IVA. None significa che la tariffa API viene presa con IVA inclusa.
API Andreani (necessaria per le tariffe in tempo reale)
Environment: Sandbox / QA (apisqa.andreani.com) (predefinito) oppure Production (apis.andreani.com). Usa l'ambiente a cui appartengono le tue credenziali.
API username: il nome utente della tua API Andreani.
API password: la password della tua API Andreani.
Client code: il codice cliente (código de cliente) fornito da Andreani, per esempio CL0000000.
Contract number: il contratto del servizio usato per le tariffe, per esempio consegna a domicilio. Una zona può usare un altro contratto, per esempio per il ritiro in filiale.
Origin branch code: filiale di origine facoltativa (sucursalOrigen) per i preventivi. Lascialo vuoto per usare la filiale configurata nel tuo contratto.
Consegna e tariffe
Delivery modality: la prima parte indica dove Andreani ritira il pacco (il tuo indirizzo o una filiale dove lo consegni). La seconda parte indica dove il cliente lo riceve.
Rate source: come viene calcolato il prezzo.
Country prices: un prezzo fisso per paese di destinazione nella valuta del tuo negozio, uno per riga nel formato CC=PRICE, per esempio AR=5000. Usato dalla modalità fissa e come alternativa in caso di errore dell'API. Le righe in un altro formato vengono ignorate, e al salvataggio un avviso le elenca.
ARS exchange rate: Andreani fa i preventivi in pesos argentini. Serve solo se la valuta del tuo negozio non è ARS: il prezzo di 1 ARS nella valuta del tuo negozio, per esempio 0.001. Senza questo valore, le tariffe API non vengono usate. I prezzi fissi sono sempre nella valuta del negozio.
Default product weight (kg): usato per i prodotti senza peso quando si richiedono le tariffe API e si verificano i limiti di peso. Predefinito: 0.5.
Calculation type: Per order addebita il prezzo una sola volta. Per item (price x number of items) moltiplica il prezzo fisso di Country prices per il numero di articoli nel carrello. Una tariffa Andreani in tempo reale vale già per l'intero carrello e non viene moltiplicata.
Disponibilità
Min weight (kg): il peso minimo del carrello perché il metodo appaia. 0 significa nessun limite.
Max weight (kg): il peso massimo del carrello. Il metodo viene nascosto se viene superato. Predefinito: 100. 0 significa nessun limite.
Minimum subtotal: mostra il metodo solo quando il subtotale del carrello è almeno pari a questo importo. Lascialo vuoto per mostrarlo sempre.
Excluded shipping classes: se un articolo del carrello appartiene a una classe di spedizione WooCommerce selezionata, il metodo viene nascosto.
Ignore shipping zones: offri il metodo per i paesi qui sotto anche se non è stato aggiunto a una zona di spedizione.
Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Usato solo quando Ignore shipping zones è attivo.
Spedizione gratuita
Free shipping: attiva la soglia per la spedizione gratuita.
Free shipping from: il subtotale del carrello a partire dal quale la spedizione è gratuita. Richiede che Free shipping sia attivo.
Selettore della filiale al checkout (mostrato per Door to branch e Branch to branch)
Province select width: la larghezza CSS dell'elenco delle province, per esempio 100% o 300px. Predefinito: 100%.
Branch select width: la larghezza CSS dell'elenco delle filiali, per esempio 100% o 400px. Predefinito: 100%.
Avanzate
Debug log: registra le richieste API e i calcoli delle tariffe in WooCommerce > Status > Logs (origine "vfd-andreani"). Gli errori vengono sempre registrati. Credenziali e token non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le sue impostazioni e i metodi nelle zone. La disattivazione non cancella nulla. I dati delle filiali salvati negli ordini vengono sempre conservati.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di spedizione, il plugin verifica il peso del carrello (i pesi dei prodotti vengono convertiti in kg; i prodotti senza peso usano Default product weight (kg)), il Minimum subtotal e le Excluded shipping classes.
In modalità fissa il prezzo viene preso da Country prices. In modalità in tempo reale il plugin accede all'API Andreani e richiede un preventivo con il codice postale di destinazione, il contratto, il codice cliente, il peso in kg, il volume calcolato dalle dimensioni dei prodotti e il valore dichiarato (il subtotale del carrello in ARS). Una tariffa in tempo reale viene richiesta solo per un codice postale argentino valido. L'importo in ARS viene convertito con ARS exchange rate quando la valuta del tuo negozio non è ARS.
Il token di accesso viene memorizzato nella cache per 23 ore e rinnovato automaticamente quando Andreani lo rifiuta. I preventivi vengono memorizzati nella cache per 1 ora. Una chiamata API non riuscita non viene ripetuta per 5 minuti. Gli errori dell'API non vengono mai mostrati al cliente: il metodo viene nascosto oppure, in modalità di riserva, si usa il prezzo fisso. Il motivo viene scritto nel log.
Se Free shipping è attivo e il subtotale del carrello raggiunge Free shipping from, la tariffa è 0. La spedizione gratuita vale solo dove il metodo ha un prezzo: se l'API Andreani non restituisce una tariffa (e non c'è un prezzo fisso di riserva), il metodo non viene mostrato. Con Per item il prezzo fisso viene moltiplicato per il numero di articoli.
Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con High-Performance Order Storage (HPOS) di WooCommerce.
Il plugin non crea spedizioni Andreani, non stampa etichette e non traccia i pacchi. Per questo usa il portale web di Andreani.
Punti di ritiro
Con Door to branch o Branch to branch, sotto l'opzione Andreani al checkout compaiono un elenco delle province e un elenco delle filiali, sia nel checkout classico sia nel blocco Checkout. La provincia viene preselezionata dall'indirizzo di spedizione. L'elenco delle filiali proviene dall'API pubblica delle filiali Andreani ed è memorizzato nella cache per 12 ore. Non vengono elencate le filiali che non consegnano pacchi. Se non ci sono filiali disponibili, il cliente vede un messaggio e può scegliere un altro metodo di spedizione.
L'ordine non può essere completato senza una filiale: il cliente vede Please select an Andreani pickup branch. Questo viene verificato sul server per entrambi i checkout.
La filiale scelta viene salvata nell'ordine. Nella schermata dell'ordine dell'amministrazione, la modalità e la filiale vengono mostrate sotto l'indirizzo di spedizione. Fai clic su Edit per scegliere un'altra provincia e filiale. Il cliente vede la filiale come Andreani pickup branch nella pagina dell'ordine e nelle e-mail degli ordini (HTML e testo semplice). Gli ordini esistenti mantengono i dati della filiale.
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 Andreani. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva e il tuo dominio. Usa Check now per verificare 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Andreani non viene mostrato ai clienti al checkout. Gli amministratori 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 Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma per aggiornamenti e supporto serve il rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Andreani non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona dell'indirizzo del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Verifica che Country prices contenga una riga per il paese (per i prezzi fissi o come alternativa), e controlla i limiti di peso, il Minimum subtotal e le Excluded shipping classes. Leggi gli avvisi in cima alla pagina delle impostazioni.
Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs (origine "vfd-andreani"). Mostra il motivo: credenziali o numero di contratto mancanti, accesso non riuscito (nome utente, password o ambiente errati), nessun codice postale argentino valido ancora, nessun tasso di cambio oppure un errore HTTP di Andreani. Con Andreani API, fixed price if the API fails i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.
Il mio negozio non è in pesos argentini: imposta ARS exchange rate sul valore di 1 ARS nella valuta del tuo negozio.
L'imposta sulla spedizione sembra sbagliata: con Tax status impostato su Taxable si usa la tariffa Andreani senza IVA e WooCommerce aggiunge la propria imposta. Con None si usa la tariffa con IVA e WooCommerce non aggiunge imposte. Se usi Taxable, verifica che le imposte di WooCommerce siano configurate.
Nessuna filiale nell'elenco: l'API delle filiali Andreani non ha risposto. Una richiesta non riuscita viene ripetuta dopo 5 minuti. Controlla il log.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella il token, l'elenco delle filiali e le tariffe memorizzati nella 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 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 mantiene tutte le impostazioni e cancella solo le cache. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugin. La chiave di licenza e lo stato della licenza di questo plugin, insieme al token, all'elenco delle filiali e alle tariffe in cache, vengono sempre rimossi. Impostazioni e metodi nelle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. I dati delle filiali salvati negli ordini non vengono mai eliminati.
Andreani è un marchio del rispettivo titolare. Questo plugin non è affiliato ad Andreani né approvato da essa.