VibeFox 99Minutos for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivo (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Chiave API di 99minutos (solo per il controllo della copertura): ottienila dal tuo referente account di 99minutos o nel portale sviluppatori di 99minutos (developers.99minutos.com). Le chiavi sandbox e 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 abilitati in System > Localisation > Countries.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_99minutos-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_99minutos.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_99minutos-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox 99Minutos e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Compila la Price matrix (almeno una riga, per esempio "* Default") e, facoltativamente, la chiave API e la modalità di controllo della copertura (vedi Configurazione). Attiva Enable 99Minutos e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_99minutos.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox 99Minutos, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable 99Minutos e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni di 99minutos che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche i risultati della copertura in cache. Se un valore è errato, non viene salvato nulla e la pagina mostra il motivo, per esempio Enter a method title (1 to 64 characters)., un messaggio che indica che un campo deve essere un numero pari o superiore a 0, oppure che Min weight (kg) non può essere maggiore di Max weight (kg). Dopo il salvataggio, gli avvisi sopra le impostazioni indicano quando il metodo non può funzionare con la configurazione attuale: la matrice dei prezzi è vuota, è scelta una modalità di controllo della copertura senza chiave API, la matrice ha righe per paesi che 99minutos non serve, oppure il negozio non ha una classe di peso "kg" e la sua unità di peso non è riconosciuta dall'estensione (i pesi vengono allora letti come chilogrammi). Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Generali

Le impostazioni valgono per tutte le zone geografiche. 99Minutos viene offerto solo per Messico, Colombia, Cile e Perù come paesi di destinazione.

Enable 99Minutos: mostra o nasconde 99Minutos al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: 99Minutos. Obbligatorio, fino a 64 caratteri.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Con una classe fiscale, OpenCart aggiunge l'imposta al prezzo della matrice.

Sort order: la posizione di 99Minutos tra i metodi di spedizione al checkout. Un numero intero.

API di 99minutos (controllo 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 un controllo della copertura, il metodo compare solo dopo che il cliente ha inserito un CAP. I risultati vengono memorizzati in cache: coperto per 6 ore, non coperto per 30 minuti, errore dell'API per 5 minuti, ma mai più a lungo della durata della cache di OpenCart (1 ora per impostazione predefinita). A 99minutos viene inviato solo il CAP, in maiuscolo e con sole lettere e cifre.

API key: la tua chiave API di 99minutos, inviata come token Bearer all'endpoint di copertura di 99minutos. È obbligatoria quando il controllo della copertura è attivo. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. La chiave viene salvata così come la digiti; vengono rimossi solo gli spazi attorno.

Remove the saved API key: compare 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, al netto delle imposte, e vengono usati così come inseriti. Il prezzo finale viene mostrato nella valuta del cliente.

Price matrix: una tabella di paesi di destinazione e prezzi. Clicca su Add country per aggiungere una riga e sul pulsante × per rimuoverla. Ogni riga ha un Country (* Default, Messico, Colombia, Cile o Perù), un Base price e 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 usa il Base price. La riga * Default vale per i paesi senza una riga propria. Se un paese ha più righe, viene usata 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 metodo non viene mostrato al checkout.

Calculation: Per order — size by the total cart weight (predefinito) applica un unico prezzo in base alla dimensione del pacco dell'intero carrello. Per item — each unit priced by its own weight prezza ogni unità in base alla dimensione del proprio peso e somma i prezzi.

Free shipping: attiva la spedizione gratuita da un importo dell'ordine.

Free shipping from: il subtotale dei prodotti da spedire (dopo il coupon, al netto delle imposte) da cui la tariffa è 0. Viene usato solo se Free shipping è attivo.

Restrizioni

Min weight (kg): nasconde il metodo se il carrello è più leggero. 0 significa nessun limite (predefinito). Non può essere maggiore di Max weight (kg). I pesi dei prodotti vengono convertiti dalla loro classe di peso.

Max weight (kg): nasconde il metodo se il carrello è più pesante. Predefinito: 25. 0 significa nessun limite; un campo vuoto significa 25 kg.

Minimum subtotal: mostra il metodo solo se il subtotale dei prodotti da spedire (dopo il coupon, al netto delle imposte) è pari ad almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Geo zone: offre 99Minutos solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Restrict countries: offre il metodo solo per i paesi indicati qui sotto. È un filtro aggiuntivo rispetto alla Geo zone.

Countries: una scelta dei paesi di 99minutos (Messico, Colombia, Cile, Perù). Viene usata solo quando Restrict countries è attivo. Lasciala vuota per consentire tutti i paesi di 99minutos.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_99m_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono registrati anche quando l'opzione è disattivata. Le chiavi API e i nomi e gli indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_99m_debug.old.log.php e si avvia un nuovo log.

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 l'estensione vengono eliminate le impostazioni di 99minutos, la cache della copertura e il log. Se disattivo (predefinito), vengono conservati per una reinstallazione. Gli ordini vengono comunque conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di 99Minutos. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, 99Minutos non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il metodo viene offerto solo quando il paese di consegna è Messico, Colombia, Cile o Perù (ed è nell'elenco Countries se Restrict countries è attivo). L'estensione controlla poi i limiti di peso e il Minimum subtotal. L'importo dell'ordine è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e al netto delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati.

Se è attivo un controllo della copertura, l'estensione chiede all'API di 99minutos se il CAP è coperto. Il timeout della richiesta è di 10 secondi e la risposta viene memorizzata in cache, quindi lo stesso CAP non genera una nuova richiesta. Gli errori dell'API non vengono mai mostrati al cliente: nella modalità Strict il metodo viene nascosto, nella modalità Soft viene usato il prezzo della matrice. La spedizione gratuita non aggira il controllo della copertura.

Il prezzo viene preso dalla riga della matrice del paese di consegna, oppure dalla riga * Default. Se non esiste nessuna delle due, il metodo viene nascosto. Se Free shipping è attivo e l'importo dell'ordine raggiunge Free shipping from, la tariffa è 0. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

L'estensione non ottiene tariffe in tempo reale da 99minutos: i prezzi arrivano sempre dalla tua matrice. Non crea spedizioni né ordini in 99minutos, non stampa etichette (guide), non traccia i pacchi, non offre i punti di ritiro Punto99 e non gestisce il contrassegno. Non aggiunge nulla agli ordini: l'ordine mostra il nome del metodo e il costo di spedizione come qualsiasi altro metodo di OpenCart. Crea le spedizioni nel tuo account 99minutos come al solito.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina del checkout e sceglie 99Minutos nella finestra Shipping method options. Il metodo funziona allo stesso modo che su OpenCart 3.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox 99Minutos è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit, sopra le impostazioni. Inserisci 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto ci sono la riga Product: opencart-shipping-99minutos e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (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 aver cambiato l'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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera lo slot del suo dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione 99Minutos non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore connesso al pannello nello stesso browser vede ancora il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione 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ù ed essere abilitato in System > Localisation > Countries. Controlla Geo zone e Restrict countries. Verifica che la Price matrix abbia una riga per quel paese o una riga * Default, poi controlla i limiti di peso e il Minimum subtotal. Verifica che i prodotti abbiano Requires Shipping impostato su Yes. Gli avvisi mostrati dopo Save indicano le impostazioni che nascondono il metodo.

Il metodo compare solo dopo aver inserito un CAP: è normale con un controllo della copertura. Nella modalità Strict compare solo quando l'API conferma la copertura.

Nella modalità Strict il metodo è sempre nascosto: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Un errore HTTP 401 o 403 significa che l'API ha rifiutato la chiave: controlla la chiave e che Environment corrisponda (le chiavi sandbox e di produzione sono diverse). Usa la modalità Soft se i clienti devono comunque ottenere il prezzo della matrice quando l'API non è disponibile.

Il prezzo non è quello previsto: controlla Calculation (per ordine o per articolo) e i pesi e le classi di peso dei prodotti. Un prezzo di dimensione vuoto o pari a 0 usa il Base price. Con una Tax class, l'imposta si aggiunge al prezzo della matrice.

I risultati della copertura sembrano superati dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota i risultati della copertura in cache.

La pagina dice "Warning: You do not have permission to modify VibeFox 99Minutos!": il tuo gruppo di utenti amministratori potrebbe poter solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_99minutos (OpenCart 3) o extension/vfd_99minutos/shipping/vfd_99minutos (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API di 99minutos può essere sostituito con l'impostazione vfd_99m_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox 99Minutos. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable 99Minutos, Sort order, Tax class e Geo zone. I risultati della copertura in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni di 99minutos e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla successiva installazione dell'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox 99Minutos nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

99minutos è un marchio del rispettivo proprietario. Questa estensione non è affiliata né approvata da 99minutos.