VibeFox 99Minutos 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.
Chiave API 99minutos (solo per la verifica della copertura): richiedila al tuo account manager 99minutos o nel portale per sviluppatori 99minutos (developers.99minutos.com). Le chiavi sandbox e quelle di produzione sono diverse. Se usi solo la matrice dei prezzi, non ti serve una chiave API.
Paesi: 99minutos consegna in Messico, Colombia, Cile e Perù. I paesi verso cui spedisci devono essere attivi in International > Locations.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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 99Minutos nell'elenco dei moduli e clicca su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e clicca su Activate (vedi Chiave di licenza).
4. Compila la Price matrix (almeno una riga, per esempio «* Default») e, facoltativamente, la chiave API e la modalità di verifica della copertura (vedi Configurazione). Clicca su Save.
All'installazione il modulo crea il corriere 99Minutos con il testo dei tempi di consegna Courier delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Le zone di Messico, Colombia, Cile e Perù devono restare attive per il corriere. 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 99Minutos > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i risultati di copertura in cache. Dopo il salvataggio, la pagina ti avvisa se la matrice dei prezzi è vuota, se contiene righe per paesi che 99minutos non serve, se è scelta una modalità di verifica della copertura senza chiave API, o se il modulo non riconosce l'unità di peso del negozio (in tal caso i pesi sono considerati in chilogrammi). Non viene salvato nulla e compare un errore se Method title supera 64 caratteri, se un campo di peso o di importo non è un numero pari o superiore a 0, o se Min weight (kg) è maggiore di Max weight (kg). Se la pagina mostra The 99Minutos carrier was not found — reset the module to create it again., consulta Risoluzione dei problemi.
Generale
Enable 99Minutos: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Method title: il nome del corriere mostrato al cliente nel carrello e al checkout. Predefinito: 99Minutos. Obbligatorio, fino a 64 caratteri.
Tax: la regola fiscale del corriere, oppure No tax. Con una regola fiscale, PrestaShop aggiunge l'imposta al prezzo di spedizione della matrice.
API 99minutos (verifica della copertura) (facoltativo)
L'API serve solo a verificare se 99minutos consegna al CAP del cliente. Il prezzo arriva sempre dalla matrice.
Coverage check: se e come viene verificato il CAP.
Con la verifica della copertura, il corriere compare solo dopo che il cliente ha inserito un CAP. I risultati vengono memorizzati nella cache: coperto per 6 ore, non coperto per 30 minuti, errore API per 5 minuti. A 99minutos viene inviato solo il CAP, in maiuscolo e con sole lettere e cifre.
API key: la tua chiave API 99minutos, inviata come token Bearer all'endpoint di copertura di 99minutos. Obbligatoria quando la verifica della copertura è attiva. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo. La chiave viene salvata come l'hai digitata; vengono rimossi solo gli spazi attorno.
Remove the saved API key: visibile solo quando una chiave è salvata. Attivalo e clicca su Save per eliminare la chiave.
Environment: Sandbox (test) (predefinito) oppure Production. Sandbox e produzione usano chiavi API diverse, quindi scegli l'ambiente che corrisponde alla tua chiave.
Tariffe
I prezzi sono nella valuta predefinita del negozio, tasse escluse, e vengono usati così come inseriti. Il prezzo finale viene mostrato nella valuta del carrello del cliente.
Price matrix: una tabella di paesi di destinazione e prezzi. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. Ogni riga ha un Country (* Default, Messico, Colombia, Cile o Perù), un Base price e i prezzi per le dimensioni XS (fino a 1 kg), S (fino a 2 kg), M (fino a 3 kg), L (fino a 5 kg) e XL (oltre 5 kg). Un prezzo di dimensione vuoto o pari a 0 ricorre al Base price. La riga * Default si applica ai paesi senza una riga propria. Se un paese ha più righe, si usa la prima. Sono accettati sia il punto sia la virgola come separatore decimale; i prezzi vuoti, non validi o negativi vengono salvati come 0. Finché la matrice non ha almeno una riga, il corriere non viene mostrato al checkout.
Calculation: Per order — size by the total cart weight (predefinito) addebita un unico prezzo per la dimensione del pacco dell'intero carrello. Per item — each unit priced by its own weight valuta ogni unità in base alla dimensione del proprio peso e somma i prezzi.
Free shipping: attiva la spedizione gratuita da un subtotale del carrello.
Free shipping from: il subtotale del carrello (dopo sconti, tasse escluse) a partire dal quale la tariffa è 0. Usato solo quando Free shipping è attivo.
Restrizioni
Min weight (kg): nasconde il corriere se il carrello è più leggero. 0 significa nessun limite. Non può essere maggiore di Max weight (kg). I pesi dei prodotti vengono convertiti dall'unità di peso del negozio.
Max weight (kg): nasconde il corriere se il carrello è più pesante. Predefinito: 25. 0 significa nessun limite; un campo vuoto significa 25 kg.
Minimum subtotal: mostra il corriere solo se il subtotale del carrello (dopo sconti, tasse escluse) è almeno questo importo. Lascia vuoto per mostrarlo sempre.
Restrict countries: offre il corriere solo per i paesi sotto indicati. È un filtro aggiuntivo rispetto alle zone del corriere. Utile quando una zona copre più paesi.
Countries: una scelta dei paesi di 99minutos (Messico, Colombia, Cile, Perù). Tieni premuto Ctrl (Cmd) per selezionarne più di uno. Usato solo quando Restrict countries è attivo. Lascia vuoto per consentire tutti i paesi di 99minutos.
Avanzate
Debug log: scrive i calcoli delle tariffe in logs/vfd_99m_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono registrati anche quando è disattivato. Le chiavi API e i nomi e gli indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito.
Log: mostra la dimensione e le ultime voci del log di debug. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminati impostazioni, corriere, cache della copertura e log. Se disattivo, tutto viene conservato per una reinstallazione. Gli ordini vengono sempre conservati.
Come funziona al checkout
Al passaggio di spedizione PrestaShop chiede al modulo il prezzo 99Minutos. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale del carrello. Il corriere viene offerto solo quando il paese di consegna è Messico, Colombia, Cile o Perù (ed è nell'elenco Countries se Restrict countries è attivo). Il modulo poi verifica i limiti di peso e il Minimum subtotal.
Se è attiva una modalità di verifica della copertura, il modulo chiede all'API 99minutos se il CAP è coperto. La richiesta ha un timeout di 10 secondi e la risposta viene memorizzata nella cache, quindi lo stesso CAP non genera una nuova richiesta. Gli errori API non vengono mai mostrati al cliente: in modalità Strict il corriere viene nascosto, in modalità Soft si usa il prezzo della matrice. La spedizione gratuita non aggira la verifica della copertura.
Il prezzo viene preso dalla riga della matrice del paese di consegna, o dalla riga * Default. Se non esiste nessuna delle due, il corriere viene nascosto. Se Free shipping è attivo e il subtotale del carrello raggiunge Free shipping from, la tariffa è 0. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.
Se modifichi il 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 ottiene tariffe in tempo reale da 99minutos: i prezzi arrivano sempre dalla tua matrice. Non crea spedizioni o ordini in 99minutos, non stampa etichette (guide), non traccia i pacchi, non offre punti di ritiro Punto99 e non gestisce il contrassegno alla consegna. Crea le spedizioni nel tuo account 99minutos come di consueto.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox 99Minutos è il primo blocco della pagina Modules > Module Manager > VibeFox 99Minutos > Configure, 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 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-99minutos 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, 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 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, il corriere 99Minutos 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 viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al 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
99Minutos non compare al checkout: verifica che la licenza sia attiva e che Enable 99Minutos sia attivo. Il paese di consegna deve essere Messico, Colombia, Cile o Perù e risultare attivo in International > Locations. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo. Controlla che la Price matrix abbia una riga per quel paese o una riga * Default, poi verifica i limiti di peso, il Minimum subtotal e Restrict countries. Anche i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.
Il corriere compare solo dopo l'inserimento di un CAP: è normale con la verifica della copertura. In modalità Strict compare solo quando l'API conferma la copertura.
Il corriere è sempre nascosto in modalità Strict: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Un errore HTTP 401 o 403 significa che la chiave API è stata rifiutata: controlla la chiave e che Environment corrisponda (le chiavi sandbox e di produzione sono diverse). Usa la modalità Soft se i clienti devono comunque vedere il prezzo della matrice quando l'API non è disponibile.
Il prezzo non è quello che ti aspettavi: controlla Calculation (per ordine o per articolo), i pesi dei prodotti e l'unità di peso del negozio (International > Localization). Un prezzo di dimensione vuoto o pari a 0 ricorre al Base price. Con una regola fiscale in Tax, l'imposta si aggiunge al prezzo della matrice.
I risultati di copertura sembrano obsoleti dopo una modifica: clicca su Save nella pagina del modulo. Questo svuota i risultati di copertura in cache.
La pagina dice che il corriere 99Minutos non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo. Lo stesso vale per il messaggio The settings were saved, but the carrier could not be updated. Reset the module to create it again.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox 99Minutos e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Anche la cache della copertura viene sempre rimossa. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e impostazioni e log vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere salvato riprende lo stato che aveva prima della disinstallazione, quindi Reset non attiva un corriere disattivato.
99minutos è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da 99minutos.