VirtueMart: come calcolare automaticamente il costo delle spedizioni con UPS Online Tools

VirtueMart è la nota estensione per il content management system (CMS) opensource Joomla che permette di allestire, senza troppi mal di testa, un completo sito di e-commerce. Al momento VirtueMart non è ancora compatibile con le versioni più recenti di Joomla (i.e. la release 1.7) sebbene l’attesa sembri essere ormai destinata a terminare: a breve, infatti, come riportato sul sito ufficiale del progetto, dovrebbe essere finalmente pubblicata la versione 2.0 nella sua veste definitiva.

Per ora, però, chi volesse allestire un negozio virtuale basato su Joomla e VirtueMart deve necessariamente affidarsi all’accoppiata Joomla 1.5.23 + VirtueMart 1.1.9.
Qualche mese fa abbiamo dedicato una serie di articoli per guidare l’utente, passo passo, nella fase di allestimento di un sito di e-commerce con VirtueMart. Con gli ultimi articoli, tra l’altro, abbiamo aggiunto un tassello in più ossia abbiamo illustrato uno strumento che consente addirittura di fruire di un negozio online multilingua. Joom!Fish è un software non semplicissimo da configurare ma, con le nostre indicazioni, dovreste essere riusciti a superare gli scogli più comuni.

Joomla 1.7, giunto alla sua versione finale nel mese di luglio 2011, eredita dalla versione 1.6 la possibilità di allestire siti web multilingua ma in Joomla 1.5 ciò non era possibile facendo leva sulle funzionalità di default dell’applicazione.

Uno degli ostacoli che solitamente si frappongono prima del varo del sito di e-commerce, è la gestione delle spedizioni. Dopo aver effettuato il login all’area amministrativa di Joomla, si dovrà cliccare sul menù Componenti, VirtueMart, fare clic sul Amministrazione, Configurazione quindi sulla scheda Spedizione.

Questa sezione di VirtueMart indica l’elenco di tutti i moduli di spedizione che sono correntemente disponibili.
Il “Modulo di spedizione standard con corrieri e tariffe configurati individualmente” è quello che solitamente viene utilizzato con maggior frequenza. Attivandolo (basta spuntare la casella corrispondente e fare clic sul pulsante Salva, in alto), VirtueMart proporrà all’utente, prima della conferma del suo ordine, le tariffe ed i corrieri manualmente impostati nella sezione Spedizioni, Tariffe corrieri.

Di base, VirtueMart propone le tariffe di due corrieri piuttosto diffusi quali DHL ed UPS: cliccando sul nome della tariffa è facile verificare come essa è stata definita. In particolare, è possibile specificare a quale o quali nazioni di destino è riferita, i CAP interessati, la fascia di peso e così via. Per ciascuna spedizione, VirtueMart attingerà al database delle tariffe dei corrieri (altri corrieri possono essere aggiunti cliccando su Spedizioni, Corrieri) e, controllando peso dei prodotti richiesti e nazione di destinazione, proporrà al cliente una tariffa.

Il problema, però, è che non è affatto semplice gestire la preventivazione delle spese di spedizione per il mondo intero: le variabili in gioco sono infatti molteplici. I corrieri spesso applicano dei costi aggiuntivi per determinate aree, le tariffe proposte sono molte e non è facile trattarle in modo adeguato con un approccio “a lista” come quello utilizzabile facendo leva su Spedizioni, Tariffe corrieri.

Come risolvere? Gli “UPS Online Tools” possono rappresentare un’ottima soluzione. Il famoso corriere espresso, infatti, mette a disposizione degli sviluppatori un comodo strumento che permette di rendere qualunque applicazione web in grado di calcolare dinamicamente ed in tempo reale le spese di spedizione di qualunque prodotto, in qualsiasi Paese. L’offerta di UPS si traduce nella fornitura di alcune API (“Application Programming Interface“) che possono essere utilizzate dai vari linguaggi di programmazione per interagire con i server remoti del corriere espresso. Inviando delle interrogazioni ad un server remoto, utilizzando una particolare sintassi, si otterrà – per tutta risposta – l’elenco completo delle tariffe disponibili per la spedizione indicata.

Il primo passo consiste nella richiesta ad UPS, di un codice cliente personale. Chi spedisce pacchi in modo abituale, ha necessariamente bisogno di tale informazione. Al codice cliente vengono infatti associati di solito sconti o particolari tariffe.
In primis, quindi, si dovrà attivare un account utente sul sito web di UPS cliccando su questo link e compilando i campi proposti.
Facendo riferimento a questa pagina, quindi, si dovrà richiedere il codice cliente UPS quindi associarlo al proprio account utente usando, successivamente, questa pagina.
Nel campo “Numero codice cliente UPS si dovrà digitare il codice cliente (generalmente ricevuto via e-mail) avendo cura di eliminare eventualmente gli zeri iniziali che dovessero essere presenti (il codice cliente deve essere composto solo da sei caratteri alfanumerici).

Terminate queste operazioni iniziali, si potrà visitare questa sezione del sito di UPS in modo da ottenere subito una speciale chiave d’accesso. Tale (lungo) identificativo alfanumerico dovrà essere poi utilizzato in VirtueMart.

Utilizzo del codice d’accesso UPS e definizione delle tariffe

Così com’è, VirtueMart è già in grado di usare le API di UPS per interfacciarsi con i server della società. Tra il sistema ove è stato installato e configurato il negozio virtuale ed i server di UPS verrà automaticamente posto in essere uno scambio di dati nel momento in cui un acquirente ordina qualunque prodotto a catalogo ed arriva a definire la fase di spedizione della merce.

Per procedere, è sufficiente verificare di aver attivato la voce Calcolo spedizione con UPS Online Tools nella sezione Amministrazione, Configurazione, Spedizione di VirtueMart.
A questo punto cliccando sulla voce Negozio quindi su Lista moduli spedizione, si dovrà scegliere il link Configura un tipo di spedizione posto immediatamente sotto la dizione “UPS“:

La chiave di accesso precedentemente ottenuta sul sito di UPS, deve essere inserita nella casella Codice d’accesso UPS mentre immediatamente sotto (ID utente UPS e Password UPS), si dovranno digitare le credenziali dell’account utente creato sul sito del corriere espresso.

Come modalità di ritiro dei pacchi abbiamo specificato “One time pickup” mentre, per quanto concerne l’imballaggio adoperato “Unknown“. Quest’ultima scelta corrisponde ad un imballaggio preparato autonomamente dal venditore, cliente di UPS.
Lasciando vuoto il campo Ship from Zip Code, VirtueMart comunicherà, come CAP di spedizione (località dalla quale i pacchi debbono partire) quello specificato nella sezione Negozio, Modifica negozio (indirizzo del negozio). Per maggior sicurezza, però, è possibile impostarlo manualmente anche qui.

Per richiedere la spesa per l’invio di una spedizione, infatti, il modulo UPS di VirtueMart comunicherà sempre, ai server del corriere espresso, una località di partenza ed un CAP (oltre alle informazioni sulla città e sulla nazione di destinazione). E’ quindi importantissimo verificare che il CAP e la località del mittente siano corrette.

Suggeriamo poi di attivare tutti i profili tariffari successivamente enumerati:

Così facendo, VirtueMart proporrà tutte le soluzioni tariffarie possibili. UPS identifica ciascuna tipologia di spedizione, a seconda della tariffa applicata (alcune sono più convenienti ma più “lente”) con un codice numerico a due cifre (di solito tra 01 e 65).
Spuntando tutte le tariffe in VirtueMart, di volta in volta – in modo iterativo – si verificherà quali tra di esse potranno essere utilizzate.

Dopo aver confermato l’intervento premendo il pulsante Salva, si potrà uscire dall’amministrazione di VirtueMart e provare ad ordinare un prodotto. Inserito del materiale nel “carrello virtuale”, arrivati alla scelta del metodo di spedizione, VirtueMart – in calce alla schermata – visualizzerà la lista delle tariffe disponibili:

La “magia” avviene grazie all’operato del file \administrator\components\com_virtuemart\classes\shipping\ups.php. Tale elemento s’incarica di verificare i pesi di ogni prodotto posto nel carrello (effettuando le dovute moltiplicazioni allorquando l’utente avesse scelto di ordinare più esemplari), di trasmettere ai server di UPS una speciale richiesta preparata in formato XML, attendere la risposta ed elaborarla analizzando il file XML ottenuto.

Controllo dei dati scambiati e sistemazione degli errori di calcolo

Per verificare quali dati vengono scambiati è sufficiente accedere all’amministrazione di VirtueMart, cliccare su Amministrazione, Configurazione e spuntare la casella DEBUG, contenuta nel riquadro Impostazioni base.

Ricaricando la pagina che contiene la lista delle tariffe di spedizione, ci si troverà dinanzi a qualcosa di simile:

La prima casella di testo contiene la struttura XML che VirtueMart ha trasmesso al server di UPS. Scorrendo i dati in essa memorizzati, è facile riconoscere il codice d’accesso personale, nome utente, password, CAP della località di partenza, CAP di quella di arrivo, unità di misura del peso, peso complessivo degli articoli nel cartello.
Nella seconda casella di testo, di dimensioni più grandi, è invece incollata la risposta ricevuta dal server di UPS. Oltre al peso dei prodotti da spedire, vengono “snocciolati” i costi di tutte le tariffe di spedizione, indicate con un codice numerico a due cifre. Il codice 11, ad esempio, è la tariffa UPS “standard”.
Suggeriamo, a questo punto, di tornare nell’amministrazione di VirtueMart disattivando la casella DEBUG, precedentemente abilitata. Ricaricando, lato sito, la pagina del carrello, tutte le informazioni di debug dovrebbero essere così scomparse.

C’è comunque un problema. Le tariffe rilasciate via XML dai server di UPS sono già in Euro mentre il file ups.php, ritenendosi si tratti di Dollari americani, provvede ad effettuare una conversione assolutamente non necessaria.
Per risolvere questo problema, è sufficiente aprire il file \administrator\components\com_virtuemart\classes\shipping\ups.php con un editor di testo e, in corrispondenza della riga 300, digitare $convert = false;. Il blocco di codice precedente e successivo dovrebbe apparire così:

In realtà, si sarebbe potuto eliminare tutto il precedente blocco if ma abbiamo preferito lasciarlo in vista di ulteriori future modifiche al codice.
Come si vede, VirtueMart ritiene che la valuta usata da UPS siano sempre i Dollari statunitensi e, nel caso in cui la valuta impostata sul negozio virtuale sia diversa da USD, viene richiesta una conversione. La linea che si è aggiunta evita, in ogni caso, che la conversione venga effettuata dal momento che i prezzi sono forniti da UPS già in Euro.

Con l’intento di verificare che il tariffario di spedizione proposto ai clienti del negozio online sia effettivamente quello offerto da UPS, suggeriamo caldamente di effettuare il login col proprio account utente sul sito del corriere espresso, cliccare sul menù Spedizione quindi Calcola tempi e costi, attivare l’opzione Dettagli tempi e costi, scegliere il codice cliente assegnato quindi impostare una spedizione. Gli importi indicati cliccando sul pulsante Avanti dovranno ovviamente coincidere al centesimo, a parità di peso, con quelli esposti ai clienti da VirtueMart.
Si tenga infine presente che nel caso di alcuni Paesi, il CAP (o “Zip Code”) non esiste.

E’ importante notare, esaminando il codice PHP del file \administrator\components\com_virtuemart\classes\shipping\ups.php, che se – per una qualsiasi ragione – il server di UPS non dovesse essere disponibile (down dello stesso, irraggiungibilità dovuta a problemi di rete,…), VirtueMart ripiegherà (riga 184, Switch to StandardShipping on Error !!!) sulla spedizione standard, anche se questa è stata disabilitata dall’amministrazione.
Nel nostro caso, commentando alcune righe presenti all’interno del blocco if alla riga 184 di ups.php, abbiamo preferito generare la visualizzazione di un errore personalizzato (aggiunta della linea echo $VM_LANG->_('PHPSHOP_ERROR_UPSDOWN');).

La nuova variabile di lingua andrà manualmente aggiunta nei file contenuti nel percorso \administrator\components\com_virtuemart\languages\common (ad esempio italian.php, english.php, french.php e così via).
Esempio: 'PHPSHOP_ERROR_UPSDOWN' => '<b>ATTENZIONE. Al momento, per motivi non imputabili alla nostra volontà, ci è impossibile proporvi le tariffe di spedizione.<br />La procedura d\'ordine non può essere completata.<br />Vi invitiamo a voler cortesemente riprovare più tardi.<br />Grazie per la collaborazione.</b>',

Il meccanismo di preventivazione per le spedizioni mediante il corriere UPS dovrebbe essere così pienamente funzionante. Il vantaggio è quello di poter concentrarsi sulla gestione spicciola del negozio online evitando di dover aggiornare o comunque verificare periodicamente le tariffe impostate.