VibeFox Coordinadora for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Chiave API di Coordinadora (solo per le quotazioni in tempo reale): le quotazioni in tempo reale provengono dal Cotizador di Coordinadora tramite il servizio WooCommerce di Coordinadora, lo stesso usato dal plugin ufficiale di Coordinadora. Coordinadora rilascia la chiave API ai clienti con un accordo commerciale attivo. Chiedi al tuo account manager di Coordinadora o consulta wc.coordinadora.com. Ti serve anche il codice DANE a 8 cifre della città da cui spedisci. Senza chiave il metodo funziona solo con prezzi fissi.

Prodotti: per una quotazione in tempo reale ogni prodotto nel carrello deve avere un peso e tre dimensioni (lunghezza, larghezza, altezza).

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_coordinadora-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_coordinadora.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_coordinadora-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Coordinadora 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 licenza in alto nella pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Inserisci la chiave API, il codice DANE della città di origine e, se la valuta predefinita del negozio non è COP, il tasso di cambio in COP. Aggiungi almeno un prezzo fisso per la Colombia come alternativa (vedi Configurazione). Attiva Enable Coordinadora e clicca su Save.

6. Assicurati che i tuoi prodotti abbiano peso e dimensioni.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_coordinadora.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 sulla 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 Coordinadora, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

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

Dopo l'installazione il metodo è disattivato finché non attivi Enable Coordinadora e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Coordinadora che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. Le impostazioni valgono per tutte le zone geografiche; puoi limitare il metodo a una zona geografica e ai paesi in Conditions. Le sezioni sono elencate a sinistra. Un solo pulsante Save in fondo salva l'intera pagina senza ricaricarla. Dopo il salvataggio vedi Settings saved. Cached Coordinadora rates were cleared. I numeri si possono digitare con il punto o con la virgola (9,99 = 9.99). Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Non viene salvato nulla e la pagina elenca gli errori se Name è vuoto o supera 64 caratteri, se un numero o un prezzo della tabella non è valido o è negativo, se COP per 1 unit of store currency è 0, se Min weight (kg) è maggiore di Max weight (kg), o se Sort order non è un numero intero.

La pagina mostra avvisi sopra le impostazioni quando le quotazioni in tempo reale non possono funzionare o il metodo verrebbe nascosto: Origin city (DANE code) è vuoto o non valido; manca COP per 1 unit of store currency se la valuta predefinita non è COP; non c'è un prezzo fisso per la Colombia (né per *); non c'è una chiave API né un prezzo fisso per la Colombia, quindi il metodo non viene mai mostrato per gli indirizzi colombiani. Compare un avviso anche quando il negozio non ha una classe di peso in kg o una classe di lunghezza in cm e la sua unità predefinita non è riconosciuta dall'estensione; i pesi dei prodotti vengono letti come kg e le dimensioni come cm (usa kg, g, lb o oz e cm, mm, m o in in System > Localisation). Gli avvisi vengono aggiornati dopo ogni salvataggio.

Generale

Enable Coordinadora: mostra o nasconde Coordinadora al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Coordinadora. Obbligatorio, fino a 64 caratteri.

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

Quotazioni in tempo reale di Coordinadora

Le quotazioni in tempo reale vengono richieste per destinazioni in Colombia. Lascia la chiave vuota per usare solo prezzi fissi.

API key: la tua chiave API WooCommerce di Coordinadora. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarla. La chiave non viene mai scritta nel registro.

Remove the saved API key: compare solo quando una chiave è salvata. Attivalo e clicca su Save per eliminare la chiave; il metodo usa poi solo prezzi fissi.

Origin city (DANE code): il codice DANE a 8 cifre della città da cui spedisci, per esempio 11001000 Bogotá, 05001000 Medellín, 76001000 Cali o 08001000 Barranquilla. È accettato anche un codice di comune a 5 cifre, che viene completato a 8.

COP per 1 unit of store currency: Coordinadora quota in pesos colombiani. Se la valuta predefinita del negozio non è COP, indica quanti COP valgono 1 unità della tua valuta, per esempio 4300. Il tasso serve anche a inviare il valore dichiarato in COP. Se lo lasci vuoto, le quotazioni in tempo reale non vengono usate. Il tasso deve essere maggiore di 0. Se la valuta predefinita è COP, lascialo vuoto.

Prezzi fissi (usati quando non c'è una chiave API, per destinazioni fuori dalla Colombia e come alternativa quando una quotazione in tempo reale non è disponibile)

Prices by country: un elenco di paesi con una colonna Price e prezzi facoltativi per dimensione del pacco, nella valuta predefinita del negozio, IVA esclusa. La dimensione dipende dal peso del carrello: XS fino a 1 kg, S da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 5 kg, XL oltre 5 kg. Si usa Price quando la colonna della dimensione è 0 o vuota. Clicca su Add country per aggiungere una riga; una nuova riga parte con la Colombia. Il paese * All other countries si applica ai paesi senza una riga propria. Un paese senza riga (e senza *) non ha un prezzo fisso. Una riga con Price 0 e senza prezzo per dimensione dà la spedizione gratuita.

Fixed price per: Order (predefinito) addebita il prezzo una sola volta. Item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Questo vale solo per i prezzi fissi; una quotazione in tempo reale di Coordinadora copre sempre l'intero ordine.

Condizioni

Min weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).

Max weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 25 (usato anche quando il campo è vuoto). 0 significa nessun limite.

Minimum order subtotal: mostra il metodo solo se il subtotale dei prodotti da spedire (dopo il coupon, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping: attiva la spedizione gratuita dal subtotale sotto indicato.

Free shipping from: il subtotale (dopo il coupon, prima delle tasse) da cui la spedizione è gratuita. Usato solo quando Free shipping è attivo. In quel caso non viene fatta nessuna richiesta all'API.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Con una classe fiscale OpenCart aggiunge l'imposta sulla spedizione sopra la tariffa. Scegli No tax se i tuoi prezzi o la quotazione di Coordinadora includono già le imposte.

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

Countries: offri Coordinadora solo per questi paesi di destinazione. Lascialo vuoto per consentire tutti i paesi. Questo limite si applica insieme a Geo zone.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_crd_debug.log.php (su OpenCart 4 system/storage/logs/vfd_crd_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API e le impostazioni incomplete vengono sempre registrati, anche con questa opzione disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_crd_debug.old.log.php e si inizia un nuovo registro.

Log: mostra la dimensione e le ultime voci del registro di debug. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni di Coordinadora, le quotazioni in cache e i registri. Se disattivo (predefinito), tutto viene conservato per una reinstallazione.

Importazione / Esportazione

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 in 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 Coordinadora. Se è impostata una Geo zone e l'indirizzo è fuori da essa, Coordinadora non viene offerta. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nella quotazione. Il subtotale è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima delle tasse. Buoni regalo, punti premio e credito del negozio non vengono considerati. L'estensione controlla prima le condizioni: paesi consentiti, peso del carrello e subtotale minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata nessuna richiesta a Coordinadora.

Per un indirizzo in Colombia con una chiave API, l'estensione cerca il codice DANE della città di destinazione in quest'ordine: un codice DANE nel campo città (i moduli di checkout colombiani per dipartimenti e città lo scrivono, per esempio MEDELLIN (ANT) (05001000)), un CAP a 8 cifre oppure l'elenco integrato dei capoluoghi di dipartimento e di circa 40 città più grandi. Se l'indirizzo ha una regione (dipartimento), una città dell'elenco viene verificata rispetto ad essa. Accenti e maiuscole vengono ignorati.

Poi l'estensione invia a Coordinadora il codice DANE di destinazione e ogni prodotto con la città di origine, il suo peso (kg), le sue dimensioni (cm), la quantità e il valore dichiarato (COP). Il valore dichiarato è il totale della riga del prodotto prima delle tasse, dopo lo sconto del coupon. Le classi di peso e di lunghezza dei prodotti vengono convertite automaticamente. Coordinadora restituisce il prezzo in COP; l'estensione lo converte nella valuta predefinita del negozio, lo arrotonda alle cifre decimali di quella valuta e lo mostra nella valuta del cliente con l'imposta della Tax class selezionata. Ogni quotazione è memorizzata in cache per 1 ora. Una richiesta non riuscita viene ricordata per 10 minuti, così un guasto di Coordinadora non rallenta mai ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi.

Quando una quotazione in tempo reale non è disponibile (errore dell'API, città sconosciuta, prodotto senza peso o dimensioni, impostazioni incomplete), si usa il prezzo fisso. Se non ce n'è uno, il metodo viene nascosto per quel carrello. I dettagli degli errori vanno nel registro di debug, mai al cliente.

L'estensione calcola solo le tariffe. Non crea spedizioni o guías, non stampa etichette, non prenota ritiri (recogidas), non traccia i pacchi, non riscuote il contrassegno (recaudo) né offre punti di ritiro Droop; per questo usa il portale di Coordinadora. Non aggiunge nulla agli ordini: l'ordine mostra il nome del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart. Le destinazioni internazionali usano i prezzi fissi.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Coordinadora 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 di vibefox.net. Il blocco licenza License — VibeFox Coordinadora è il primo blocco in Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit, 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 a cui 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 ci sono la riga Product: opencart-shipping-coordinadora e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono incluse le lingue inglese e russa).

Se la chiave non viene accettata, il blocco spiega il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con 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 della configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Coordinadora non viene mostrata ai clienti al checkout e non viene calcolata nessuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, 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 il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve nessun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Coordinadora non compare al checkout: verifica che la licenza sia attiva e che Enable Coordinadora sia attivo. Controlla gli avvisi in alto nella pagina dell'estensione, Geo zone, Countries, i limiti di peso e Minimum order subtotal. Senza una quotazione in tempo reale deve esistere un prezzo fisso per il paese o per *. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

La tariffa in tempo reale non viene mostrata, si vede solo il prezzo fisso: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Cause tipiche: la città di destinazione non è riconosciuta, un prodotto non ha peso o dimensioni, mancano il codice DANE di origine o il tasso di cambio in COP, oppure Coordinadora ha restituito un errore.

La città di destinazione non è riconosciuta: installa un modulo di checkout colombiano per dipartimenti e città che scriva il codice DANE nel campo città. Gli sviluppatori possono aggiungere altre città o cambiare l'indirizzo dell'API con gli eventi di OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane e vfd_coordinadora/api_url; l'indirizzo dell'API può anche essere sostituito con l'impostazione vfd_crd_api_url (per i test), che non ha un campo nella pagina delle impostazioni.

La tariffa include le imposte? La tariffa è quella quotata da Coordinadora. Con una Tax class OpenCart aggiunge l'imposta sulla spedizione sopra la tariffa; scegli No tax se la quotazione la include già.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota le quotazioni in cache.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Coordinadora. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Coordinadora, Sort order, Tax class e Geo zone. Le quotazioni in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni di Coordinadora e i registri. Se è disattivo, le altre impostazioni restano e vengono riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il 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 Coordinadora nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Coordinadora è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da Coordinadora.