VibeFox Coordinadora for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successiva. Il modulo non si installa su versioni precedenti di PHP.

Chiave API di Coordinadora (solo per le tariffe in tempo reale): le tariffe in tempo reale provengono dal Cotizador di Coordinadora tramite il servizio Coordinadora WooCommerce, 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 oppure consulta wc.coordinadora.com. Ti serve anche il codice DANE a 8 cifre della città da cui spedisci. Senza chiave il corriere funziona solo con prezzi fissi.

Prodotti: per una tariffa in tempo reale ogni prodotto nel carrello deve avere peso e dimensioni (larghezza, altezza, profondità).

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 cerca più tardi VibeFox Coordinadora 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. Inserisci la chiave API, il codice DANE della città di origine e, se la tua valuta predefinita non è il COP, il tasso di cambio in COP. Aggiungi almeno un prezzo fisso per la Colombia come alternativa (vedi Configurazione). Clicca su Save.

5. Assicurati che la Colombia sia attiva nel tuo negozio e che i tuoi prodotti abbiano peso e dimensioni.

All'installazione il modulo crea il corriere Coordinadora con il testo dei tempi di consegna Courier delivery in Colombia. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Coordinadora > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Coordinadora in cache. I numeri si possono scrivere con il punto o con la virgola (9,99 = 9.99).

La pagina non salva e mostra un errore quando un numero o un prezzo in tabella non è valido o è negativo, quando COP per 1 unit of store currency è 0, quando Min weight è maggiore di Max weight o quando Name supera i 64 caratteri. Non viene salvato nulla finché non correggi.

La pagina mostra avvisi in alto quando le tariffe in tempo reale non possono funzionare o il corriere verrebbe nascosto: Origin city (DANE code) è vuoto o non valido, manca COP per 1 unit of store currency mentre la tua valuta predefinita non è il COP, oppure non c'è un prezzo fisso per la Colombia (o *). Senza chiave API e senza un prezzo fisso del genere, il corriere non viene mai mostrato per gli indirizzi colombiani. Un avviso compare anche quando l'unità di peso o di dimensione del negozio in International > Localization (Local units) non è riconosciuta dal modulo; i pesi dei prodotti vengono allora letti come kg e le dimensioni come cm.

Generale

Enable Coordinadora: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del corriere mostrato al cliente al checkout. Predefinito: Coordinadora. Obbligatorio.

Tax: la regola fiscale del corriere, oppure No tax. Con una regola, PrestaShop aggiunge l'imposta di spedizione sopra la tariffa. Scegli No tax se i tuoi prezzi o la tariffa di Coordinadora includono già l'imposta.

Tariffe Coordinadora in tempo reale

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

API key: la tua chiave API di Coordinadora WooCommerce, fornita da 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 log.

Remove the saved API key: visibile solo quando una chiave è salvata. Attivalo e clicca su Save per eliminare la chiave; il corriere userà 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 municipio a 5 cifre, che viene completato a 8.

COP per 1 unit of store currency: Coordinadora quota in pesos colombiani. Se la tua valuta predefinita non è il 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 tariffe in tempo reale non vengono usate. Il tasso deve essere maggiore di 0. Se la tua valuta predefinita è il COP, lascialo vuoto.

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

Prices by country: una tabella di paesi con una colonna Price e prezzi opzionali per dimensione del pacco, nella tua valuta predefinita, IVA esclusa. La dimensione dipende dal peso del carrello: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL oltre 5 kg. Price viene usato quando la colonna di dimensione è 0 o vuota. Clicca su Add country per aggiungere una riga e sulla croce per eliminarne una. 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à spedizione gratuita.

Fixed price per: Order 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 tariffa Coordinadora in tempo reale copre sempre l'intero ordine.

Condizioni

Min weight: nasconde il corriere sotto questo peso del carrello, in kg. 0 significa nessun limite.

Max weight: nasconde il corriere sopra questo peso del carrello, in kg. Predefinito: 25 (usato anche quando il campo è vuoto). 0 significa nessun limite. Non può essere inferiore a Min weight.

Minimum order subtotal: mostra il corriere solo se il subtotale del carrello (dopo gli sconti, prima delle imposte) è almeno questo importo. Lascia vuoto per mostrarlo sempre.

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

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

Countries: offri Coordinadora solo per questi paesi di destinazione. Sono elencati solo i paesi attivi. Lascia vuoto per consentire tutti i paesi delle zone del corriere.

Avanzate

Debug log: scrive i calcoli delle tariffe in logs/vfd_crd_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API e le impostazioni incomplete vengono sempre registrati, anche quando questa opzione è disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni di Coordinadora, il corriere, le tariffe in cache e i log. Se disattivo, tutto viene conservato per una nuova installazione.

Come funziona al checkout

Al passaggio di spedizione PrestaShop chiede al modulo il prezzo di Coordinadora. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nella tariffa. Il modulo 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 alcuna richiesta a Coordinadora.

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

Poi il modulo 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 imposte e prima degli sconti del carrello. Le unità del negozio vengono convertite automaticamente. Coordinadora restituisce il prezzo in COP, e il modulo lo converte nella tua valuta predefinita e poi nella valuta del carrello del cliente. Ogni tariffa viene memorizzata in cache per 1 ora. Una richiesta non riuscita viene ricordata per 10 minuti, così un'interruzione di Coordinadora non rallenta mai ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi.

Quando una tariffa in tempo reale non è disponibile (errore dell'API, città sconosciuta, prodotto senza peso o dimensioni, impostazioni mancanti), si usa il prezzo fisso. Se non ce n'è uno, il corriere viene nascosto per quel carrello. I dettagli degli errori vanno nel log di debug, mai al 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 calcola solo le tariffe. Non crea spedizioni o guías (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. Le destinazioni internazionali usano i prezzi fissi.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Coordinadora è il primo blocco della pagina Modules > Module Manager > VibeFox Coordinadora > Configure, 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi ci sono la riga Product: presta-shipping-coordinadora e il link 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 cambiare 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 una modifica 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: il dominio 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 Coordinadora non viene mostrato ai clienti al checkout e non viene calcolata nessuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i 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

Coordinadora non compare al checkout: verifica che la licenza sia attiva e che Enable Coordinadora sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo. Controlla Countries, i limiti di peso e Minimum order subtotal. Senza tariffa in tempo reale deve esistere un prezzo fisso per il paese o per *. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

La tariffa in tempo reale non viene mostrata, solo il prezzo fisso: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Motivi tipici: la città di destinazione non viene riconosciuta, un prodotto non ha peso o dimensioni, manca il codice DANE di origine o il tasso in COP, oppure Coordinadora ha restituito un errore.

La città di destinazione non viene riconosciuta: installa un modulo di checkout per dipartimenti e città colombiani che scrive il codice DANE nel campo città. Gli sviluppatori possono associare altre città con gli hook del modulo actionVfdCrdDaneCities e actionVfdCrdDestinationDane, oppure cambiare l'indirizzo dell'API con actionVfdCrdApiUrl.

La tariffa include l'imposta? La tariffa è quella calcolata da Coordinadora. Con una regola Tax, PrestaShop aggiunge l'imposta di spedizione sopra; scegli No tax se la tariffa la include già.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo svuota le tariffe in cache.

La pagina dice che il corriere Coordinadora non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Coordinadora e scegli Uninstall. La chiave di licenza, lo stato della licenza e le tariffe in cache vengono sempre eliminate. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono lo storico) e vengono rimosse impostazioni e log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo, o un Reset, ridà al corriere salvato lo stato che aveva prima: un corriere che avevi disattivato resta disattivato.

Coordinadora è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato né approvato da Coordinadora.