Widget Mappa

In questa sezione viene illustrato come effettuare l’integrazione del Widget Mappa interattivo di GEL Proximity per visualizzare e permettere la selezione di Punti di Ritiro.

GEL Proximity mette a disposizione un SDK dedicato per consentire la selezione di un Punto di Ritiro tramite l’utilizzo di una mappa interattiva, detto anche Widget Mappa. In questa sezione vengono presentate le funzionalità messe a disposizione dall’SDK, le sue caratteristiche e il suo funzionamento. Questo approccio è indicato per tutti i Merchant che hanno l’esigenza di integrare il servizio di GEL Proximity in modo rapido e senza effettuare interventi di sviluppo complessi sul proprio eCommerce.

Il componente dell’SDK si occupa in modo autonomo di ricavare ed adattare la mappa in base alla configurazione impostata dal Merchant nel pannello di amministrazione di GEL Proximity, come ad esempio dati delle Reti abilitate, i Punti di Ritiro disponibili, i prezzi da applicare ad ogni spedizione, lo stile della mappa ed eventuali funzionalità secondarie.

L’SDK si presenta come un singolo file JavaScript da includere nel frontend del proprio eCommerce, idealmente nella pagina di checkout all’interno del tag <head>. Il file contiene tutte le dipendenze di cui necessita per il suo corretto funzionamento.

È possibile includere il file utilizzando il seguente link:

https://platform.gelproximity.com/sdk/latest.js

Il link importa sempre l’ultima versione disponibile ed aggiornata dell’SDK.

Esempio

<script type="text/javascript" src="https://platform.gelproximity.com/sdk/latest.js"></script>

Una volta importato il file dell’SDK nel checkout dell’eCommerce del Merchant è necessario istanziare il componente principale GelSDK, detto anche Constructor.

Il Constructor è il componente principale dell’SDK: riceve le impostazioni di connessione all’applicazione GEL Proximity e permette di accedere direttamente a tutte le funzionalità.

Per inizializzare il Constructor è necessario passare i parametri indicati.

Particolare attenzione va posta durante la valorizzazione del parametro reference. Questo parametro è infatti l’identificativo univoco dell’ordine che viene memorizzato su GEL Proximity come ordine temporaneo una volta che l’utente ha scelto il Punto di Ritiro. Successivamente, quando si vorrà confermare l’ordine a GEL Proximity, dovrà essere riutilizzato lo stesso parametro reference.

 

Parametri

Nome Tipo Obbl. Default Descrizione
urlEndUser string Si – Link dell’applicativo, composto dall’URL dell’ambiente seguito da gel-enduser-client/
merchantCode string Si – Codice univoco del Merchant
apiKey string Si – Public Key del Merchant
reference string Si – Codice univoco dell’ordine
redirectMode string Si – Metodo di restituzione delle informazioni del Punti di Ritiro selezionato. Accetta i valori GET e POST
locale string No "en_GB" Lingua da utilizzare per del Widget Mappa
isReturnOrder boolean No false Specifica se l’ordine è un reso
width number No – Larghezza del pacco in cm
height number No – Altezza del pacco in cm
depth number No – Profondità del pacco in cm
networks NetworkCode[] No – Lista di Reti che si desidera abilitare
networkType NetworkType No – Tipologia di Reti che si desidera abilitare 
<script>
  const gelSDK = new GelSDK({
    urlEndUser: 'https://test-platform.gelproximity.com/gel-enduser-client/',
    merchantCode: "MER_PW2E5I",
    apiKey: '27at1waz-1r77-112e-945c-466zwq09kl67',
    reference: "orderRef-x8epO",
    redirectMode: "POST"
  })
</script>

Successivamente all’istanziamento del Constructor sarà possibile utilizzare l’apposito metodo che si occuperà di mostrare un popup in sovrimpressione al checkout dell’eCommerce, all’interno del quale verrà visualizzata la mappa interattiva.

Per mostrare il popup è necessario eseguire il metodo createUIModal() disponibile nel Constructor, idealmente al click su un pulsante dedicato.

Le informazioni relative al Punto di Ritiro selezionato o all’annullamento della selezione verranno restituite sotto forma di oggetto accessibile nelle funzioni di callback messe a disposizione dal metodo.

Parametri

Nome Tipo Obbl. Default Descrizione
callbackOk func Si – Funzione richiamata alla selezione del Punto di Ritiro. Restituisce come argomento i dati relativi al Punto di Ritiro selezionato sotto forma di oggetto di tipo WidgetPickupPoint
callbackKo func Si – Funziona richiamata alla chiusura del Widget Mappa

WidgetPickupPoint

Nome Tipo Descrizione
reference string Codice univoco dell’ordine
isReturnOrder boolean Indica se è un ordine di reso
pickupPointId number ID del Punto di Ritiro
code string Codice del Punto di Ritiro
description string Descrizione del Punto di Ritiro
address string Indirizzo del Punto di Ritiro
city string Città del Punto di Ritiro
zipCode string CAP del Punto di Ritiro
department string Provincia del Punto di Ritiro
country string Nazione del Punto di Ritiro
lat number Latitudine del Punto di Ritiro
lon number Longitudine del Punto di Ritiro
networkCode NetworkCode Codice della Rete a cui appartiene il Punto di Ritiro
networkName string Nome della Rete a cui appartiene il Punto di Ritiro
serviceType NetworkType Tipologia del servizio associato alla Rete a cui appartiene il Punto di Ritiro
serviceName string Nome del servizio associato alla Rete a cui appartiene il Punto di Ritiro
serviceCode ServiceCode Codice del servizio associato alla Rete a cui appartiene il Punto di Ritiro
openingTimes PickupPointDay[] Giorni di apertura del Punto di Ritiro
shouldUseGELProximityPrices boolean Indica se deve essere utilizzato il prezzo della spedizione fornito da GEL Proximity
costPickupPoint number Prezzo per la spedizione al Punto di Ritiro
costZone number Prezzo relativo ai surcharge di zona della spedizione al Punto di Ritiro
costInsurance number Prezzo relativo all’assicurazione della spedizione al Punto di Ritiro
cost number Prezzo totale per la spedizione al Punto di Ritiro
costCurrencyCode string Valuta del prezzo in formato ISO4217
insuranceEnabled boolean Indica se l’assicurazione è abilitata per il Merchant
insuranceAccepted boolean Indica se l’assicurazione è stata accettata dall’utente
insurancePaidByMerchant boolean Indica se l’assicurazione è a carico del Merchant

PickupPointDay

Nome Tipo Descrizione
day CalendarDay Giorno della settimana
dayDescription string Nome del giorno della settimana
isClosed boolean Indica se il Punto di Ritiro è chiuso
amOpeningTimeFrom string Orario di apertura al mattino
amOpeningTimeTo string Orario di chiusura al mattino
pmOpeningTimeFrom string Orario di apertura al pomeriggio
pmOpeningTimeTo string Orario di chiusura al pomeriggio 
<script>
  const gelSDK = new GelSDK({
    ...
  })

  function openGELProximityModal() {
    gelSDK.createUIModal({
      callbackOk: (data) => {
        // Utilizzare 'data' per ottenere le informazioni del Punto di Ritiro selezionato.
      },
      callbackKo: () => {
        // Gestire eventuali errori o la chiusura del widget mappa.
      }
    })
  }
</script>

Una volta che è stato selezionato e confermato un Punto di Ritiro dal Widget Mappa è necessario generare l’ordine di spedizione o reso utilizzando l’API dedicata, che permette di confermare l’ordine su GEL Proximity ricavando automaticamente dalla selezione effettuata dall’utente tutte le informazioni necessarie.

Per identificare l’ordine specifico da confermare è necessario valorizzare il parametro reference utilizzato in fase di inizializzazione del Widget Mappa.

Dopo che è stato confermato l’ordine l’API restituirà il codice di riferimento dell’ordine tramite il parametro orderReferenceCode, che deve essere utilizzato in ogni richiesta successiva per effettuare operazioni sull’ordine.

In alternativa, è possibile confermare un ordine anche tramite API di creazione di un ordine di spedizione o di reso. Questo metodo richiede che le informazioni relative al Punto di Ritiro scelto dall’utente così come eventuali dati sui servizi aggiuntivi ad esso connessi siano forniti esplicitamente.

La richiesta di conferma di un ordine è asincrona: prima dell’avvenuta importazione dell’ordine in piattaforma non sarà possibile effettuare ulteriori azioni sull’ordine. Per maggiori informazioni sul funzionamento delle automazioni visitare la sezione Caratteristiche di Sistema.

Per motivi di sicurezza la richiesta deve essere necessariamente eseguita tramite una chiamata Server e non Client. Eventuali abusi o integrazioni errate possono portare alla sospensione o al ban dell’account.

Parametri

Endpoint gel-enduser-server/api/confirmOrder
Metodo POST
Encoding x-www-form-urlencoded

Request

Nome Tipo Obbl. Default Descrizione
merchantCode string Si – Codice univoco del Merchant
apiKey string Si – Secret Key del Merchant
reference string Si – Codice univoco dell’ordine
isReturnOrder boolean No false Indica se l’ordine è un reso
orderDataJson WidgetOrder Si – Dati dell’ordine

WidgetOrder

Nome Tipo Obbl. Default Descrizione
customer string Si – Nome completo dell’utente
customerEmail string Si – Email dell’utente
customerPhone string Si – Numero di telefono dell’utente
orderNumber string Si – Numero dell’ordine
orderNumberRif string Si – Nel caso l’ordine sia un reso valorizzare con il numero d’ordine di spedizione, altrimenti valorizzare come il parametro orderNumber
orderDate string Si – Data dell’ordine in formato yyyyMMdd
description string Si – Descrizione dell’ordine
notes string No – Note dell’ordine
codePickingPoint string No – Codice del magazzino del Merchant dove ritirare l’ordine
width number No – Larghezza del pacco in cm
height number No – Altezza del pacco in cm
depth number No – Profondità del pacco in cm
grossWeight number No – Peso lordo del pacco in Kg
netWeight number No – Peso netto del pacco in Kg
volume number No – Volume del pacco in cm³
goodsValue number No – Valore dell’ordine
proximityPrice number Si – Prezzo di spedizione definito dal Merchant
currencyGoodsValue string No – Codice valuta del valore ordine in formato ISO4217
orderCountInCurrentYear number Si – Numero totale di ordini dell’eCommerce confermati nell’anno solare corrente. Nel caso di ordine di spedizione valorizzare con il numero totale di spedizioni, nel caso di ordine di reso valorizzare con il numero totale di resi
piecesCount number No – Numero di prodotti contenuti nell’ordine
rows OrderItem Si – Lista di prodotti contenuti nell’ordine

OrderItem

Nome Tipo Obbl. Default Descrizione
productCode string No – Codice del prodotto
typeProduct string No – Tipologia del prodotto
description string Si – Descrizione del prodotto
notes string No – Note del prodotto
width number No – Larghezza del prodotto in cm
height number No – Altezza del prodotto in cm
depth number No – Profondità del prodotto in cm
grossWeight number No – Peso lordo del prodotto in Kg
netWeight number No – Peso netto del prodotto in Kg
volume string No – Volume del prodotto in cm³ 
{
  "merchantCode": "MER_PW2E5I",
  "apiKey": "27at1waz-1r77-112e-945c-466zwq09kl67",
  "reference": "orderRef-x8epO",
  "orderDataJson": {
    "customer": "Mario Rossi",
    "customerEmail": "mario.rossi@email.com",
    "customerPhone": "3331535985",
    "orderNumber": "19664",
    "orderNumberRif": "19664",
    "orderDate": "20220101",
    "description": "Descrizione dell'ordine",
    "proximityPrice": 4.99,
    "orderCountInCurrentYear": 5344,
    "rows": [
      {
        "description": "Giacca di pelle nera",
      },
      ...
    ]
  }
}

Response

Nome Tipo Descrizione
success boolean Esito della richiesta
message string Messaggio di risposta
data OrderIdentifier Dati restituiti

OrderIdentifier

Nome Tipo Descrizione
orderReferenceCode string Codice di riferimento dell’ordine
pickupPointPublicCode string Codice pubblico del Punto di Ritiro associato all’ordine 
{
  "success": true,
  "message": "Operazione completata",
  "data": {
    "orderReferenceCode": "4a48926aarv76430e776e3w11pomuua2",
    "pickupPointPublicCode": "965512"
  }
}