VibeFox Andreani for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
Account Andreani (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API di preventivi Andreani. Andreani assegna ai clienti business credenziali API, un codice cliente e numeri di contratto, di solito a partire da circa 300 spedizioni al mese. Vedi developers.andreani.com oppure scrivi a ventapyme@andreani.com. Ti servono nome utente e password dell'API, codice cliente e numero di contratto. Andreani assegna 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.
VibeFox license key: si acquista su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Andreani nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).
4. Imposta il nome, la fonte delle tariffe, i prezzi per paese (ad esempio AR=5000) e, per le tariffe in tempo reale, le credenziali API, il codice cliente e il numero di contratto (vedi Configurazione). Fai clic su Save.
All'installazione il modulo crea due corrieri:
Entrambi i corrieri sono assegnati alla zona dell'Argentina e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Andreani > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Dopo il salvataggio vedi Settings saved. Cached token, branches and rates were cleared. Gli avvisi su impostazioni mancanti (credenziali API, numero di contratto, tasso di cambio ARS, nessun prezzo per l'Argentina, un corriere eliminato) compaiono in cima alla pagina. Compare un avviso anche se il modulo non riconosce l'unità di peso o di dimensione del negozio (in tal caso i pesi vengono letti come kg e le dimensioni come cm). Al salvataggio, un nome più lungo di 64 caratteri o un Min weight (kg) maggiore di Max weight (kg) vengono rifiutati e non viene salvato nulla. Un valore che non è un numero, un numero negativo o un ARS exchange rate pari o inferiore a 0 non viene salvato, e un avviso indica il campo.
General
Enable/Disable: attiva o disattiva la spedizione con Andreani. È lo stesso interruttore dello stato del corriere principale in Shipping > Carriers. La seconda opzione ha un proprio interruttore.
Name: il nome del corriere mostrato al cliente nel checkout. Predefinito: Andreani. Obbligatorio.
Tax status: None, oppure Taxable con una delle tue regole fiscali. Con una regola fiscale, il negozio aggiunge l'imposta al costo di spedizione, quindi la tariffa dell'API viene presa senza IVA. Con None, la tariffa dell'API viene presa con IVA inclusa. L'impostazione viene salvata su entrambi i corrieri Andreani.
Andreani API (necessario 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 tuo nome utente dell'API Andreani.
API password: la tua password dell'API Andreani. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Clearing the API username removes it too. Inserisci un nuovo valore solo se vuoi cambiarlo.
Client code: il codice cliente (código de cliente) fornito da Andreani, ad esempio CL0000000.
Contract number: il contratto del servizio usato per le tariffe, ad esempio consegna a domicilio. La seconda opzione può usare un altro contratto, ad 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 modalità del corriere principale. 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 ogni paese di destinazione nella valuta predefinita del negozio, IVA esclusa, una riga per paese nel formato CC=PRICE, ad esempio AR=5000. Viene usato dalla modalità fissa e come alternativa in caso di errore dell'API. I paesi senza riga non hanno un prezzo fisso. Le righe in un altro formato vengono ignorate e un avviso le elenca al salvataggio.
ARS exchange rate: Andreani emette preventivi in pesos argentini. Serve solo se la valuta predefinita del negozio non è ARS: il prezzo di 1 ARS nella valuta del negozio, ad esempio 0.001. Senza di esso, le tariffe dell'API non vengono usate.
Default product weight (kg): usato per i prodotti senza peso quando si richiedono le tariffe API e si verificano i limiti di peso. Se vuoto, vale 0,5 kg.
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 tutto il carrello e non viene moltiplicata.
Disponibilità
Min weight (kg): il peso minimo del carrello perché il corriere compaia. 0 significa nessun limite.
Max weight (kg): il peso massimo del carrello. Il corriere viene nascosto se viene superato. Vuoto significa 100 kg, 0 significa nessun limite.
Minimum subtotal: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, IVA esclusa) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Ignore shipping zones: offre Andreani per i paesi indicati di seguito senza configurare zone. Quando lo attivi, entrambi i corrieri vengono collegati a tutte le zone, e una zona creata in seguito viene collegata subito. Quando lo disattivi, i corrieri recuperano le zone precedenti.
Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Viene 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 da cui la spedizione è gratuita. Richiede che Free shipping sia attivo.
Seconda opzione
Un secondo corriere Andreani con nome, modalità di consegna e contratto propri, ad esempio "a domicilio" nel corriere principale e "retiro en sucursal" qui, per offrirle entrambe. Tutte le altre impostazioni sono condivise.
Enable second option: attiva o disattiva il secondo corriere. È lo stesso interruttore del suo stato in Shipping > Carriers. Predefinito: disattivato.
Second option name: il nome di questa opzione nel checkout. Predefinito: Andreani - branch pickup. Obbligatorio.
Delivery modality: Use global setting oppure una delle quattro modalità. Predefinito: Door to branch (Puerta a Sucursal).
Contract number: Andreani assegna un contratto separato per servizio (consegna a domicilio, ritiro in filiale). Lascialo vuoto per usare il contratto globale.
Selettore della filiale nel checkout (mostrato per door to branch e branch to branch)
Province select width: la larghezza CSS della lista delle province, ad esempio 100% o 300px. Predefinito: 100%.
Branch select width: la larghezza CSS della lista delle filiali, ad esempio 100% o 400px. Predefinito: 100%.
Avanzate
Debug log: registra le richieste API e i calcoli delle tariffe in logs/vfd_andr_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Credenziali e token non vengono mai registrati.
Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate tutte le sue impostazioni e i corrieri. Se disattivo, disinstallando si disattivano soltanto i corrieri. I dati delle filiali salvati negli ordini vengono sempre conservati.
Come funziona nel checkout
Nel passaggio di consegna PrestaShop chiede al modulo il prezzo di ogni corriere Andreani. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla i paesi (quando Ignore shipping zones è attivo), il peso del carrello (i pesi dei prodotti vengono convertiti in kg, e i prodotti senza peso usano Default product weight (kg)) e il Minimum subtotal.
In modalità fissa il prezzo viene preso da Country prices. Nelle modalità in tempo reale il modulo 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 ricavato 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 l'ARS exchange rate quando la valuta del negozio non è ARS. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.
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 corriere viene nascosto oppure, in modalità di alternativa, si usa il prezzo fisso. Il motivo viene scritto nel registro.
Se Free shipping è attivo e il subtotale del carrello raggiunge Free shipping from, il prezzo è 0. La spedizione gratuita si applica solo dove il corriere ha un prezzo: se l'API Andreani non restituisce alcuna tariffa e non c'è un prezzo fisso di riserva, il corriere non viene mostrato.
Se modifichi un corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Il modulo non crea spedizioni Andreani, non stampa etichette e non traccia i pacchi. Per questo usa il portale web di Andreani.
Punti di ritiro
Quando è selezionato un corriere con Door to branch o Branch to branch, sotto di esso compaiono nel passaggio di consegna un elenco delle province e un elenco delle filiali. 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 No Andreani branches available right now. Please try again later or choose another shipping method.
La scelta viene salvata nel carrello non appena il cliente la seleziona. Viene accettata solo una filiale dell'elenco Andreani attuale. Senza una filiale, Continue nel passaggio di consegna e il pulsante dell'ordine nel passaggio di pagamento non procedono, e il cliente vede Please select an Andreani pickup branch. Il server ricontrolla la filiale quando il cliente prosegue. Se la filiale non è più nell'elenco, il cliente vede The selected Andreani branch is not available. Please choose another one.
Una filiale scelta sotto Andreani prima che il cliente passasse a un altro corriere non appartiene all'ordine.
Ordini
L'ordine conserva la modalità di consegna e, per le modalità con filiale, la filiale scelta.
Admin order page: un blocco Andreani mostra la modalità e la filiale (nome, ID e provincia). Fai clic su Edit, scegli un'altra provincia e un'altra filiale e fai clic su Save per cambiarla. Vedi Branch updated. Si possono salvare solo filiali dell'elenco Andreani. Se l'elenco non è disponibile, la filiale non può essere cambiata.
Cliente: la filiale viene mostrata come Andreani pickup branch: nella pagina di conferma dell'ordine e nella pagina dei dettagli dell'ordine.
E-mail: nell'e-mail di conferma dell'ordine e nell'e-mail di nuovo ordine al negozio (modulo Mail alerts), la filiale viene aggiunta al nome del corriere. L'e-mail al negozio mostra anche l'ID della filiale.
Gli ordini esistenti mantengono i propri dati di filiale.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Andreani è il primo blocco della pagina Modules > Module Manager > VibeFox Andreani > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopodiché 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 si trovano la riga Product: presta-shipping-andreani e il collegamento 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, per 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, fai clic 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 solo dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, i corrieri Andreani non vengono mostrati ai clienti nel checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi i corrieri vengono nascosti anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Andreani non compare nel checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo (per il secondo corriere, anche Enable second option). In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo di clienti, oppure attiva Ignore shipping zones e controlla Countries. Verifica che Country prices abbia una riga per il paese (per i prezzi fissi o come alternativa), e controlla i limiti di peso e il Minimum subtotal. Leggi gli avvisi in cima alla pagina Configure. Inoltre, i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.
Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo: credenziali o numero di contratto mancanti, un 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 usa i pesos argentini: imposta ARS exchange rate sul valore di 1 ARS nella valuta predefinita del tuo negozio.
L'imposta sulla spedizione sembra errata: con una regola fiscale in Tax status viene usata la tariffa Andreani senza IVA e PrestaShop aggiunge la propria imposta. Con None viene usata la tariffa con IVA e non si aggiunge imposta. Verifica che le imposte siano attive e che la regola fiscale sia configurata per l'Argentina.
Nessuna filiale nell'elenco: l'API delle filiali Andreani non ha risposto. Una richiesta non riuscita viene ripetuta dopo 5 minuti. Controlla il registro.
Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo svuota il token, l'elenco delle filiali e le tariffe memorizzati nella cache.
La pagina dice che un corriere Andreani non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Andreani e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Anche il token, l'elenco delle filiali e le tariffe memorizzati nella cache vengono sempre rimossi. Se Remove data on uninstall è attivo, i corrieri vengono eliminati (gli ordini conservano la cronologia), e vengono rimosse le impostazioni, il registro e le scelte di filiale dei carrelli senza ordine. Se è disattivo, i corrieri vengono solo disattivati e tutte le impostazioni vengono conservate. Reinstallare il modulo oppure un Reset del modulo riporta entrambi i corrieri al loro stato precedente. I dati delle filiali salvati negli ordini non vengono mai eliminati.
Andreani è un marchio registrato del rispettivo proprietario. Questo modulo non è affiliato ad Andreani né approvato da Andreani.