VibeFox Servientrega for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Account Servientrega (solo per le tariffe in tempo reale): le tariffe in tempo reale usano il Cotizador Corporativo di Servientrega (API di preventivo aziendale). Ti serve un account aziendale (di credito) Servientrega con accesso ad esso. Servono tre dati: l'utente, la password e il codice di fatturazione (código de facturación, di solito inizia con SER). Sono le tue credenziali SISCLINET, rilasciate dal tuo consulente commerciale Servientrega. Se usi solo prezzi fissi, non ti serve un account Servientrega.

Accesso al server (solo per le tariffe in tempo reale): il tuo server deve poter raggiungere web.servientrega.com via HTTP sulla porta 8058 (API di preventivo) e sulla porta 8081 (servizio web di cifratura delle password).

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. Estrailo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_servientrega-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_servientrega.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_servientrega-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions, scegli il tipo di estensione Shipping, trova VibeFox Servientrega e clicca su Install (il pulsante verde +).

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

4. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco di licenza in alto nella pagina Edit, e clicca su Activate (vedi Chiave di licenza).

5. Per le tariffe in tempo reale, inserisci l'utente, la password e il codice di fatturazione, scegli il prodotto Servientrega, inserisci il codice DANE dell'origine e, se la valuta del tuo negozio non è il COP, il tasso di conversione della valuta.

6. Facoltativamente, aggiungi prezzi fissi per paese e peso e un costo di riserva, attiva Enable Servientrega e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_servientrega.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, scegli il tipo di estensione Shipping, trova VibeFox Servientrega, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

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

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

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. Le sezioni sono elencate a sinistra. Valgono per tutte le zone geografiche. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella i preventivi Servientrega in cache e il token di accesso. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Se le tariffe in tempo reale non possono funzionare con le impostazioni salvate, un avviso sopra le impostazioni ti dice il motivo: manca l'utente, la password o il codice di fatturazione, manca il tasso di conversione o manca il codice DANE dell'origine. Un avviso compare anche se il negozio non ha una classe di peso in kg o una classe di lunghezza in cm e la sua unità predefinita non è nota all'estensione; in quel caso i pesi vengono letti come kg e le dimensioni come cm. Al salvataggio, un valore che non è un numero, un numero negativo, un tasso di conversione di 0, un peso minimo superiore al massimo, un prezzo errato nella tabella, un titolo del metodo vuoto, più lungo di 64 caratteri o contenente < > ; = # { }, oppure un ordinamento che non è un numero intero viene rifiutato con un errore, e non viene salvato nulla.

Generali

Enable Servientrega: mostra o nasconde Servientrega al checkout. Predefinito: disattivo.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Servientrega. Obbligatorio, massimo 64 caratteri.

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

API Servientrega (tariffe in tempo reale per la Colombia) (facoltativo; senza credenziali si usano solo i prezzi fissi)

User (login): il tuo utente Servientrega / SISCLINET. Svuotarlo rimuove anche la password salvata.

Password: la tua password Servientrega / SISCLINET, così come la digiti. L'estensione la fa cifrare dal servizio web di Servientrega prima dell'accesso. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Billing code: il codice di fatturazione (código de facturación) del tuo account Servientrega, come appare in SISCLINET. Di solito inizia con SER.

Tutti e tre i campi servono per le tariffe in tempo reale. Le tariffe in tempo reale vengono richieste solo per destinazioni in Colombia. Gli altri paesi usano i prezzi fissi.

Servientrega product: il servizio del tuo accordo con Servientrega che viene quotato.

Il peso fatturato è il maggiore tra peso reale e peso volumetrico.

Currency conversion rate: Servientrega quota in COP. Se la valuta predefinita del tuo negozio non è il COP, inserisci il valore di 1 COP nella valuta del tuo negozio, ad esempio 0.00023. Il valore dichiarato del pacco viene convertito in COP allo stesso modo. Se la valuta del tuo negozio è il COP, il campo indica che non serve alcuna conversione: lascialo vuoto. Se il tuo negozio usa un'altra valuta e questo campo è vuoto, le tariffe in tempo reale non vengono usate e si applicano i prezzi fissi. L'estensione non recupera i tassi di cambio. Sono accettati sia il punto sia la virgola come separatore decimale.

Ship from (usato per le tariffe in tempo reale)

Origin city (DANE code): il codice DANE a 8 cifre del comune da cui spedisci, ad esempio 11001000 Bogotá, 05001000 Medellín, 76001000 Cali o 08001000 Barranquilla. Viene accettato anche un codice comunale a 5 cifre. L'indirizzo del negozio in OpenCart è testo libero, quindi l'origine non viene mai presa da lì: senza questo campo non ci sono tariffe in tempo reale.

Fixed prices (usati quando non c'è una tariffa in tempo reale: nessuna credenziale, destinazione fuori dalla Colombia, comune sconosciuto, tasso di conversione mancante, errore dell'API o nessuna copertura per la tratta)

Price per country: una tabella di paesi e prezzi nella valuta predefinita del tuo negozio, IVA esclusa. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per cancellarne una. Price vale per qualsiasi peso. Le colonne di peso XS (fino a 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) e XL (oltre 5 kg) lo sostituiscono per quel peso quando sono superiori a 0. La riga * Default vale per tutti i paesi senza una riga propria. Una nuova riga inizia come * Default. Una riga senza alcun prezzo non viene salvata.

Fallback cost: usato quando non c'è una tariffa in tempo reale e nessuna riga della tabella corrisponde. Lascialo vuoto per nascondere il metodo in quel caso.

Fixed price applies: come vengono addebitati i prezzi fissi.

Le tariffe Servientrega in tempo reale sono sempre per spedizione.

Conditions

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

Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 50. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono la spedizione (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: la spedizione è gratuita quando quel subtotale raggiunge questo importo, e non viene inviata alcuna richiesta a Servientrega. Vale per ogni destinazione in cui il metodo è offerto, anche per paesi senza riga nella tabella dei prezzi. Lascialo vuoto per non offrire mai la spedizione gratuita.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). I preventivi di Servientrega (ValorTotal) includono già i costi del vettore. Scegli No tax se non vuoi aggiungere imposte sopra.

Geo zone: offri Servientrega solo per indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene verificata quando Ignore shipping zones è attivo.

Availability without geo zone

Normalmente il metodo viene offerto nella zona geografica selezionata in Conditions, oppure ovunque.

Ignore shipping zones: offri Servientrega per i paesi qui sotto, a prescindere dalla zona geografica.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi attivi del tuo negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Advanced

Debug log: scrive i calcoli delle tariffe e gli errori dell'API in storage/logs/vfd_svtg_debug.log.php. Il file non può essere letto dal web. Credenziali, token e indirizzi dei clienti non vengono registrati. Quando il log è disattivato non viene scritto nulla, inclusi gli errori dell'API. Quando il file raggiunge 5 MB, viene spostato in vfd_svtg_debug.old.log.php e si avvia un nuovo log. 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: quando è attivo, disinstallare l'estensione elimina tutte le impostazioni di Servientrega e il log. Quando è disattivo (predefinito), vengono conservate per una reinstallazione. I preventivi in cache vengono sempre eliminati.

Import / Export

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

Import: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La password salvata viene mantenuta finché l'utente è impostato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Servientrega. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, Servientrega non viene offerto (a meno che Ignore shipping zones sia attivo). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nell'importo dell'ordine. L'importo dell'ordine è il prezzo di questi prodotti dopo lo sconto del coupon e prima delle imposte. Buoni regalo e punti fedeltà non vengono considerati. L'estensione controlla prima le condizioni: il paese di consegna (con Ignore shipping zones), il peso del carrello e l'importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Servientrega. Poi cerca un prezzo: la tariffa in tempo reale di Servientrega, quindi la tabella dei prezzi e, infine, il costo di riserva. Se non c'è un prezzo, il metodo viene nascosto per quel carrello.

Per una destinazione in Colombia con credenziali impostate, l'estensione trova il codice DANE del comune del cliente. Usa un codice DANE inserito nel campo del codice postale o della città, oppure confronta dipartimento e città con la tabella integrata di circa 1.130 comuni. Il dipartimento è la Region / State dell'indirizzo: OpenCart ha già tutti i 33 dipartimenti colombiani. Accenti e "D.C." vengono ignorati. Una città che esiste in un solo dipartimento viene trovata anche senza il dipartimento.

L'estensione invia poi a Servientrega un unico collo per ordine: il peso totale convertito dalla classe di peso del prodotto in kg, e una scatola con la lunghezza e la larghezza dell'articolo più grande e il volume totale di tutti gli articoli, convertito in cm. I prodotti senza dimensioni contano come 10 × 10 × 10 cm. Il valore dichiarato è l'importo dell'ordine convertito in COP, con un minimo di 6.000 COP. Servientrega restituisce il totale in COP. L'estensione lo converte nella valuta predefinita del tuo negozio e lo arrotonda alle sue cifre decimali. Il cliente lo vede nella sua valuta con l'imposta della Tax class selezionata.

Il token di accesso viene mantenuto fino alla scadenza, al massimo 4 giorni. Un token rifiutato viene rinnovato automaticamente una volta. Ogni preventivo viene memorizzato nella cache per 1 ora per tratta e pacco, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita (cifratura, accesso o preventivo) viene memorizzata nella cache per 10 minuti, così il checkout non attende Servientrega a ogni aggiornamento. Il timeout è di 10 secondi per richiesta.

Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log di debug, quando è attivo.

L'estensione calcola solo tariffe. Non crea guide (guías), etichette o adesivi, non richiede ritiri, non traccia né annulla spedizioni e non permette al cliente di scegliere un ufficio Servientrega (Centro de Soluciones). Crea la guida in SISCLINET o nel tuo portale Servientrega. Il contrassegno (logística de recaudo) non viene quotato. I preventivi in tempo reale riguardano solo le spedizioni nazionali all'interno della Colombia. 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.

In OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Servientrega nella finestra Shipping method options, dove il nome del metodo è mostrato con il prezzo. Il metodo funziona allo stesso modo che in OpenCart 3.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Servientrega è il primo blocco di Extensions > Extensions > Shipping > VibeFox Servientrega > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (ad 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 ci sono la riga Product: opencart-shipping-servientrega 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 inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad 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 il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione Servientrega non viene mostrato ai clienti al checkout e non viene richiesta né calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. In 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 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

Servientrega non compare al checkout: verifica che la licenza sia attiva e che Enable Servientrega sia attivo. Controlla Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum order amount. Senza tariffa in tempo reale, verifica che il paese o * Default abbia un prezzo, oppure che Fallback cost sia impostato. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Motivi comuni: manca il tasso di conversione (la valuta del negozio non è il COP), manca il codice DANE dell'origine, il dipartimento o la città del cliente non sono ancora inseriti o non sono un comune noto, credenziali errate, nessuna copertura per la tratta, oppure il server non riesce a raggiungere web.servientrega.com sulle porte 8058 e 8081. I prezzi fissi coprono questi casi, se li hai impostati.

L'accesso non riesce: verifica utente, password e codice di fatturazione con il tuo consulente commerciale Servientrega. Dopo un accesso fallito, l'estensione attende 10 minuti prima del tentativo successivo. Salva le impostazioni per riprovare subito.

La città del cliente non viene riconosciuta: il cliente deve scegliere il dipartimento nel campo Region / State. Per le grafie rare, il cliente può inserire il codice DANE a 8 cifre come codice postale.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella i preventivi Servientrega in cache e il token.

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

Per gli sviluppatori: gli eventi di OpenCart vfd_servientrega/dane_code e vfd_servientrega/quote_request permettono a un'altra estensione di modificare il codice DANE di destinazione e la richiesta di preventivo.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Servientrega. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Servientrega, Sort order, Tax class e Geo zone. I preventivi in cache, i token e la password cifrata vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il log. Se è disattivo, vengono conservate e riutilizzate alla reinstallazione dell'estensione. Gli ordini esistenti conservano 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 Servientrega nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

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