Webhooks

In questa sezione viene illustrato come utilizzare i Webhooks disponibili per ottenere informazioni degli ordini da GEL Proximity in real time.

I Webhooks sono una funzionalità che permette di essere informati in modo proattivo dalla piattaforma di GEL Proximity di eventi specifici che avvengono sugli ordini del Merchant.

Ogni Merchant può gestire tutte queste configurazioni accedendo alla sezione apposita del pannello di amministrazione di GEL Proximity.

Ogni Webhook su GEL Proximity richiede un endpoint dedicato per funzionare correttamente. Ogni volta che un evento si verifica, se configurato dal Merchant, richiamerà l’endpoint associato al Webhook specifico trasmettendo le informazioni relative all’evento e all’ordine relativo.

La piattaforma comunica le informazioni dell’evento in real time con un sistema di coda dinamica.

Ogni Webhook avrà associato un codice token dedicato (visibile nel pannello di amministrazione) che verrà comunicato all’endpoint specifico tramite il parametro X-GelProximity-Token presente nell’header della response. È quindi importante effettuare una validazione server-side del token per essere sicuri della bontà della sorgente dei dati trasmessi.

{
  ...
  "X-GelProximity-Token": "27at1waz-1r77-112e-945c-466zwq09kl67",
}

Permette di ottenere le informazioni di un ordine di spedizione o di reso non appena l’ordine viene importato su GEL Proximity.
Questo evento viene innescato ogni volta che viene creato un ordine, sia esso di spedizione o di reso, diretto ad un Punto di Ritiro di una Rete o proprietario.

Response

Nome Tipo Descrizione
event WebhookEvent Dati dell’evento verificato
customer WebhookCustomer Dati dell’utente associato all’ordine
order WebhookOrder Dati dell’ordine
pickupPoint WebhookPickupPoint Dati del Punto di Ritiro associato all’ordine
network WebhookNetwork Dati della Rete associata all’ordine
courier WebhookCourier Dati del corriere associato all’ordine
warehouse WebhookWarehouse Dati del magazzino associato all’ordine
parcel WebhookParcel[] Dati dei pacchi associati all’ordine

WebhookEvent

Nome Tipo Descrizione
code WebhookEventCode Codice dell’evento
description string Descrizione dell’evento
date string Data di verifica dell’evento in formato dd/MM/yyyy
time string Orario di verifica dell’evento in formato HH:mm

WebhookCustomer

Nome Tipo Descrizione
name string Nome dell’utente associato all’ordine
email string Email dell’utente associato all’ordine
phone string Telefono dell’utente associato all’ordine

WebhookOrder

Nome Tipo Descrizione
orderReferenceCode string Codice di riferimento univoco dell’ordine
orderNumber string Numero dell’ordine
orderDate string Data dell’ordine in formato dd/MM/yyyy
serviceCode ServiceCode Codice del servizio

WebhookPickupPoint

Nome Tipo Descrizione
code string Codice del Punto di Ritiro associato all’ordine
publicCode string Codice pubblico del Punto di Ritiro associato all’ordine
name string Nome del Punto di Ritiro associato all’ordine
address string Indirizzo del Punto di Ritiro associato all’ordine
city string Città del Punto di Ritiro associato all’ordine
zipcode string CAP del Punto di Ritiro associato all’ordine
department string Provincia del Punto di Ritiro associato all’ordine
country string Nazione del Punto di Ritiro associato all’ordine

WebhookNetwork

Nome Tipo Descrizione
code NetworkCode Codice della Rete associata all’ordine
name string Nome della Rete associata all’ordine

WebhookCourier

Nome Tipo Descrizione
name string Nome del corriere

WebhookWarehouse

Nome Tipo Descrizione
code string Codice del magazzino associato all’ordine
name string Nome del magazzino associato all’ordine
address string Indirizzo del magazzino associato all’ordine
city string Città del magazzino associato all’ordine
zipcode string CAP del magazzino associato all’ordine
department string Provincia del magazzino associato all’ordine
country string Nazione del magazzino associato all’ordine

WebhookParcel

Nome Tipo Descrizione
width number Larghezza del pacco in cm
height number Altezza del pacco in cm
depth number Profondità del pacco in cm
grossWeight number Peso lordo del pacco in Kg
netWeight number Peso netto del pacco in Kg
volume number Volume del pacco in cm³ 
{
  "event": {
    "code": "EV_00001",
    "description": "Creazione di un ordine di Spedizione",
    "date": "01/01/2022",
    "time": "14:30",
  },
  "customer": {
    "name": "Mario Rossi",
    "email": "mario.rossi@email.com",
    "phone": "3331535985",
  },
  "order": {
    "orderReferenceCode": "4a48926aarv76430e776e3w11pomuua2",
    "orderNumber": "19664",
    "orderDate": "01/01/2022",
    "serviceCode": "001",
  },
  "pickupPoint": {
    "code": "PUP_325389",
    "publicCode": "965512",
    "name": "TNT Point",
    "address": "Via Rossi 10",
    "city": "Milano",
    "zipcode": "20019",
    "department": "Milano",
    "country": "IT",
  },
  "network": {
    "code": "NET_000042",
    "name": "TNT Point",
  },
  "courier": {
    "name": "FedEx",
  },
  "warehouse": {
    "code": "PIN_543881",
    "description": "Magazzino principale",
    "address": "Via Rossi 10",
    "city": "Milano",
    "zipcode": "20019",
    "department": "Milano",
    "country": "IT",
  },
  "parcel": [
    {
      "width": 10,
      "height": 10,
      "depth": 10,
      "grossWeight": 1,
      "netWeight": 0.9,
      "volume": 1000,
    }
  ]
}

Permette di ottenere le informazioni di un ordine di Spedizione o di Reso non appena lo stato dell’ordine viene aggiornato su GEL Proximity.

Response

Nome Tipo Descrizione
event WebhookEvent Dati dell’evento verificato
customer WebhookCustomer Dati dell’utente associato all’ordine
order WebhookOrder Dati dell’ordine
pickupPoint WebhookPickupPoint Dati del Punto di Ritiro associato all’ordine
network WebhookNetwork Dati della Rete associata all’ordine
courier WebhookCourier Dati del corriere associato all’ordine
warehouse WebhookWarehouse Dati del magazzino associato all’ordine
parcel WebhookParcel[] Dati dei pacchi associati all’ordine
tracking WebhookTracking Dati del tracking associato all’ordine

WebhookEvent

Nome Tipo Descrizione
code WebhookEventCode Codice dell’evento
description string Descrizione dell’evento
date string Data di verifica dell’evento in formato dd/MM/yyyy
time string Orario di verifica dell’evento in formato HH:mm

WebhookCustomer

Nome Tipo Descrizione
name string Nome dell’utente associato all’ordine
email string Email dell’utente associato all’ordine
phone string Telefono dell’utente associato all’ordine

WebhookOrder

Nome Tipo Descrizione
orderReferenceCode string Codice di riferimento univoco dell’ordine
orderNumber string Numero dell’ordine
orderDate string Data dell’ordine in formato dd/MM/yyyy
serviceCode ServiceCode Codice del servizio

WebhookPickupPoint

Nome Tipo Descrizione
code string Codice del Punto di Ritiro associato all’ordine
publicCode string Codice pubblico del Punto di Ritiro associato all’ordine
name string Nome del Punto di Ritiro associato all’ordine
address string Indirizzo del Punto di Ritiro associato all’ordine
city string Città del Punto di Ritiro associato all’ordine
zipcode string CAP del Punto di Ritiro associato all’ordine
department string Provincia del Punto di Ritiro associato all’ordine
country string Nazione del Punto di Ritiro associato all’ordine

WebhookNetwork

Nome Tipo Descrizione
code NetworkCode Codice della Rete associata all’ordine
name string Nome della Rete associata all’ordine

WebhookCourier

Nome Tipo Descrizione
name string Nome del corriere

WebhookWarehouse

Nome Tipo Descrizione
code string Codice del magazzino associato all’ordine
name string Nome del magazzino associato all’ordine
address string Indirizzo del magazzino associato all’ordine
city string Città del magazzino associato all’ordine
zipcode string CAP del magazzino associato all’ordine
department string Provincia del magazzino associato all’ordine
country string Nazione del magazzino associato all’ordine

WebhookParcel

Nome Tipo Descrizione
width number Larghezza del pacco in cm
height number Altezza del pacco in cm
depth number Profondità del pacco in cm
grossWeight number Peso lordo del pacco in Kg
netWeight number Peso netto del pacco in Kg
volume number Volume del pacco in cm³

WebhookTracking

Nome Tipo Descrizione
status ShippingStatusCode | ReturnStatusCode Codice GEL dello stato associato all’ordine
statusDescription string Descrizione dello stato associato all’ordine
externalStatusCode string Codice di stato personalizzato
externalStatusDescription
 string Descrizione di stato personalizzata
number string Codice di tracking della Rete associata all’ordine
lastUpdateDate string Data di ultimo aggiornamento del tracking in formato dd/MM/yyyy
lastUpdateTime string Orario di ultimo aggiornamento del tracking in formato HH:mm
deliveryDate string Data di consegna dell’ordine in formato dd/MM/yyyy
deliveryTime string Orario di consegna dell’ordine in formato HH:mm 
{
  "event": {
    "code": "EV_00002",
    "description": "Aggiornamento di un ordine di Spedizione",
    "date": "01/01/2022",
    "time": "14:30",
  },
  "customer": {
    "name": "Mario Rossi",
    "email": "mario.rossi@email.com",
    "phone": "3331535985",
  },
  "order": {
    "orderReferenceCode": "4a48926aarv76430e776e3w11pomuua2",
    "orderNumber": "19664",
    "orderDate": "01/01/2022",
    "serviceCode": "001",
  },
  "pickupPoint": {
    "code": "PUP_325389",
    "publicCode": "965512",
    "name": "TNT Point",
    "address": "Via Rossi 10",
    "city": "Milano",
    "zipcode": "20019",
    "department": "Milano",
    "country": "IT",
  },
  "network": {
    "code": "NET_000042",
    "name": "TNT Point",
  },
  "courier": {
    "name": "FedEx",
  },
  "warehouse": {
    "code": "PIN_543881",
    "description": "Magazzino principale",
    "address": "Via Rossi 10",
    "city": "Milano",
    "zipcode": "20019",
    "department": "Milano",
    "country": "IT",
  },
  "parcel": [
    {
      "width": 10,
      "height": 10,
      "depth": 10,
      "grossWeight": 1,
      "netWeight": 0.9,
      "volume": 1000,
    }
  ],
  "tracking": {
    "status": "ST_0003",
    "statusDescription": "In transito",
    "externalStatusCode": "TRANSIT",
    "externalStatusDescription": "Il pacco è in transito",
    "number": "056010930020137843"
    "lastUpdateDate": "01/01/2022",
    "lastUpdateTime": "15:30",
    "deliveryDate": null,
    "deliveryTime": null
  }
}