# Rate Comparativa L'endpoint RateComparativa permette un analisi preventiva dei costi calcolabili a priori di una spedizione attraverso i Vostri listini (attivi o passivi) salvati e gestiti su Gsped, come ad esempio: * Nolo (costo base della spedizione) * Spese accessorie calcolabili a priori * Costo contrassegno * Costo assicurazione * FUEL * Zone disagiate o Isole * Servizi accessori (al piano, al sabato etc) * Addebiti per oversize su regole standard * Etc. Sono possibili due tipi di rating: * **ATTIVO**: richiede solo analisi costi in base ai listini attivi, ovvero quelli che usate per rivendere la spedizione ai vostri clienti * **PASSIVO**: analisi dei costi di spedizione in base ai listini sottoscritti con il corriere in fase di contrattazione. Questa modalità aggiunge in automatico anche il rating ATTIVO per permettere anche un'analisi rapida della differenza tra costi di acquisto e di vendita del trasporto. ## RateComparativa `GET` `https://api.gsped.it/istanza/RateComparativa` #### Path Parameters | Name | Type | Description | | ------- | ------ | ------------------------------------------------------------------------------------------ | | istanza | string | Istanza sul quale effetturare la chiamata, se non impostata rediretta su istanza condivisa | #### Query Parameters | Name | Type | Description | | | | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | departure\_date\_time | string |

Data ora della presunta pronta merce in formato YYYY-MM-DD HH:MM:SS
Se non valorizzato viene messo il datetime del momento della richiesta.
N.B.: Se la data fornita è nel passato, la chiamata restituirà un errore!

| | | | tipo\_listino | string |

{attivo | passivo} idetifica il tipo di rating da eseguire
N.B.: Se metti 'passivo' li restituisce entrambi

| | | gls\_exchange | string | {N\|S} Identifica la richiesta del servizio EXCHANGE per il corriere GLS | | | | al\_piano | string | {0\|1} Identifica se si è richiesto il servizio di consegna al piano (calcolato solo se corriere fornisce servizio) | | | | al\_sabato | string | {0\|1} Identifica la richiesta di servizio di consegna al sabato (calcolato solo se corriere fornisce servizio) | | | | client\_id | integer | Client ID sul quale si vuole fare il rating | | | | invoiced\_client\_id | integer | Client ID sul quale verrà fatto il rating ATTIVO nelle istanze RESELLER | | | | colli | integer | Numero di colliche formano la spedizione | | | | daticolli | array |

Dati dei colli in CM | KG | MC
- altezza
- larghezza
- lunghezza
- peso
- volume

| | peso | number | Peso totale della spedizione in KG | | | | volume | number | Volume totale della spedizione in Mc | | | | sender\_addr | string | Indirizzo del MITTENTE | | | | sender\_city | string | Città del MITTENTE | | | | sender\_prov | string | Sigla della provincia MITTENTE | | | | sender\_cap | string | Codice postale MITTENTE | | | | sender\_country\_code | string | Sigla ISO 2 char nazione MITTENTE | | | | rcpt\_addr | string | Indirizzo del DESTINATARIO | | | | rcpt\_city | string | Città DESTINATARIO | | | | rcpt\_prov | string | Sigla della provincia DESTINATARIO | | | | rcpt\_cap | string | Codice postale DESTINATARIO | | | | rcpt\_country\_code | string | Sigla ISO 2 char nazione DESTINATARIO | | | | contrassegno | number | Ammontare del contrassegno spedizione | | | | valore | number | Cifra del valore assicurato | | | | documenti | string | {0\|1} identifica se si tratta di una spedizione di documenti | | | | preavviso\_telefonico | string | {S\|N} Identifica se richiesto preavviso telefonico alla consegna | | | | corriereRichiesto | number | identifica l'ID del corriere specifico di cui si vogliono i risultati | | | | servizioRichiesto | number | Identifica l'ID del servizio di cui si vuole il risultato. Funziona in combinata con corriereRichiesto | | | | corrieriEsclusi | array | Lista di ID corrieri Gsped da escludere dal calcolo. Passare ogni valore come elemento separato: `corrieriEsclusi[]=101&corrieriEsclusi[]=2`. **Non può essere usato insieme a `corriereRichiesto`** | | | | serviziEsclusi | array | Lista di ID servizi Gsped da escludere dal calcolo. Passare ogni valore come elemento separato: `serviziEsclusi[]=0&serviziEsclusi[]=1`. **Può essere usato solo in presenza di `corriereRichiesto`** e **non può essere usato insieme a `servizioRichiesto`**. | | | #### Headers | Name | Type | Description | | --------- | ------ | -------------------------------------------- | | accept | string | Gzip,deflate | | x-api-key | string | Chiave di autenticazione rilasciata da Gsped | **Risposta** {% tabs %} {% tab title="200 - elaborazione corretta" %} In caso di elaborazione corretta il sistema vi restituirà una rispota in JSON formattato come quella sotto riportata. Questo è un esempio di risposta ad una chiamata con il flag TIPO\_LISTINO = passivo, questo significa che vi verranno fornite :\ \- QUOTAZIONI PASSIVE : al prezzo di costo in base ai listini sottoscritti con il corriere.\ \- QUOTAZIONI ATTIVE: al prezzo di vendita veicolato dai listini attivi porposti ai vostri clienti Ogni tipo di quotazione racchiude l'analisi di ogni corriere strutturata in modo da fornire le informazioni necessarie: \- Nome corriere\ \- Nome Servizio\ \- Codice Corriere Gsped\ \- Codice Servizio Gsped\ \- Client ID (identificativo univoco cliente su Gsped)\ \- Nolo (costo base del trasporto)\ \- Varie (totale dei costi accessori calcolabili a priori es. costo COD, AC Plus, etc)\ \- Totale (costo totale della spedizione)\ \- Tempo\_transito (tempo di transito della spedizione)\ \- Arrivo\_stimato (data di arrivo stimata) ```json { "passivo": { "DHL": { "Domestic Express": { "codice_corriere": "104", "codice_servizio": "0", "client_id": "1", "nolo": 28.55, "varie": 0, "totale": 28.55, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "TNT": { "Nazionale Express": { "codice_corriere": "2", "codice_servizio": "0", "client_id": "2", "nolo": 25.85, "varie": 0, "totale": 25.85, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" }, "Nazionale 12:00 Express": { "codice_corriere": "2", "codice_servizio": "1", "client_id": "2", "nolo": 258.5, "varie": 0, "totale": 258.5, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "UPS": { "Nazionale UPS Standard": { "codice_corriere": "103", "codice_servizio": "3", "client_id": "3", "nolo": 6.07, "varie": 0, "totale": 6.07, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "GLS - contratto 1": { "Espresso Nazionale": { "codice_corriere": "101", "codice_servizio": "0", "client_id": "7", "nolo": 22.58, "varie": 0, "totale": 22.58, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "GLS - contratto 2": { "Espresso Nazionale": { "codice_corriere": "101", "codice_servizio": "0", "client_id": "8", "nolo": 22.58, "varie": 0, "totale": 22.58, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } } }, "attivo": { "TNT": { "Nazionale Express": { "codice_corriere": "2", "codice_servizio": "0", "client_id": "2", "nolo": 26.68, "varie": 0, "totale": 26.68, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" }, "Nazionale 12:00 Express": { "codice_corriere": "2", "codice_servizio": "1", "client_id": "2", "nolo": 47.5, "varie": 0, "totale": 47.5, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" }, "Nazionale 10:00 Express": { "codice_corriere": "2", "codice_servizio": "2", "client_id": "2", "nolo": 52.5, "varie": 0, "totale": 52.5, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "GLS": { "Espresso Nazionale": { "codice_corriere": "101", "codice_servizio": "0", "client_id": "7", "nolo": 28.08, "varie": 0, "totale": 28.08, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } }, "GLS": { "Espresso Nazionale": { "codice_corriere": "101", "codice_servizio": "0", "client_id": "8", "nolo": 28.08, "varie": 0, "totale": 28.08, "tempo_transito": "1", "arrivo_stimato": "2025-09-24" } } } } ``` {% endtab %} {% tab title="400 - errore input" %} In caso di campi INPUT errati o mancanti verrete informati con un messaggio di errore come questo: ```json { "error": "client_id: dato obbligatorio" } ``` {% endtab %} {% endtabs %} {% hint style="danger" %} **Nota:** I campi `tempo_transito` e `arrivo_stimato` possono essere presenti nella risposta, se disponibili.\ Le stime sono elaborate da Gsped utilizzando i dati a disposizione (es. data di partenza, CAP di destinazione, festività), ma **non devono essere considerate come tempi ufficiali comunicati dai corrieri**. {% endhint %} {% hint style="danger" %} **Regole di utilizzo parametri di filtro** I parametri `corriereRichiesto`/`servizioRichiesto` e `corrieriEsclusi`/`serviziEsclusi` seguono queste regole: * `corrieriEsclusi` e `corriereRichiesto` **non possono essere usati insieme** * `serviziEsclusi` e `servizioRichiesto` **non possono essere usati insieme** * `serviziEsclusi` è utilizzabile **solo in presenza di `corriereRichiesto`** {% endhint %} A seguire dei piccoli snippet di esempio in diversi linguaggi: {% tabs %} {% tab title="PHP" %} ```php "https://api.gsped.it/sandbox/RateComparativa?colli=1&contrassegno=&documenti=&peso=104&preavviso_telefonico=&rcpt_addr=via%20felrina%20sud%20172&rcpt_cap=31044&rcpt_city=Montebelluna&rcpt_country_code=IT&rcpt_prov=BG&sender_addr=VIA%20FERRANTE%20CARACCIOLO&sender_cap=24040&sender_city=LECCE&sender_country_code=IT&sender_prov=BG&tipo_listino=passivo&valore=&volume=0&invoiced_client_id=1249", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Accept: */*", "Cache-Control: no-cache", "Connection: keep-alive", "Host: apigsped.it", "accept-encoding: gzip, deflate", "cache-control: no-cache", "x-api-key: YOUR_API_KEY" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` {% endtab %} {% tab title="GO" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.gsped.it/sandbox/RateComparativa?colli=1&contrassegno=&documenti=&peso=104&preavviso_telefonico=&rcpt_addr=via%20felrina%20sud%20172&rcpt_cap=31044&rcpt_city=Montebelluna&rcpt_country_code=IT&rcpt_prov=BG&sender_addr=VIA%20FERRANTE%20CARACCIOLO&sender_cap=24040&sender_city=LECCE&sender_country_code=IT&sender_prov=BG&tipo_listino=passivo&valore=&volume=0&invoiced_client_id=1249" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "YOUR_API_KEY") req.Header.Add("Accept", "*/*") req.Header.Add("Cache-Control", "no-cache") req.Header.Add("Host", "api.gsped.it") req.Header.Add("accept-encoding", "gzip, deflate") req.Header.Add("Connection", "keep-alive") req.Header.Add("cache-control", "no-cache") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` {% endtab %} {% tab title="PYTHON" %} ```python import requests url = "https://api.gsped.it/sandbox/RateComparativa" querystring = {"colli":"1","contrassegno":"","documenti":"","peso":"104","preavviso_telefonico":"","rcpt_addr":"via%20felrina%20sud%20172","rcpt_cap":"31044","rcpt_city":"Montebelluna","rcpt_country_code":"IT","rcpt_prov":"BG","sender_addr":"VIA%20FERRANTE%20CARACCIOLO","sender_cap":"24040","sender_city":"LECCE","sender_country_code":"IT","sender_prov":"BG","tipo_listino":"passivo","valore":"","volume":"0","invoiced_client_id":"1249"} headers = { 'x-api-key': "YOUR_API_KEY", 'Accept': "*/*", 'Cache-Control': "no-cache", 'Host': "api.gsped.it", 'accept-encoding': "gzip, deflate", 'Connection': "keep-alive", 'cache-control': "no-cache" } response = requests.request("GET", url, headers=headers, params=querystring) print(response.text) ``` {% endtab %} {% tab title="C#" %} ```csharp var client = new RestClient("https://api.aws.gsped.it/sandbox/RateComparativa?colli=1&contrassegno=&documenti=&peso=104&preavviso_telefonico=&rcpt_addr=via%20felrina%20sud%20172&rcpt_cap=31044&rcpt_city=Montebelluna&rcpt_country_code=IT&rcpt_prov=BG&sender_addr=VIA%20FERRANTE%20CARACCIOLO&sender_cap=24040&sender_city=LECCE&sender_country_code=IT&sender_prov=BG&tipo_listino=passivo&valore=&volume=0&invoiced_client_id=1249"); var request = new RestRequest(Method.GET); request.AddHeader("cache-control", "no-cache"); request.AddHeader("Connection", "keep-alive"); request.AddHeader("accept-encoding", "gzip, deflate"); request.AddHeader("Host", "api.gsped.it"); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Accept", "*/*"); request.AddHeader("x-api-key", "YOUR_API_KEY"); IRestResponse response = client.Execute(request); ``` {% endtab %} {% tab title="JAVA" %} ```java OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url("http://api.gsped.it/sandbox/RateComparativa?client_id=0000002&colli=1&contrassegno=&documenti=&peso=104&preavviso_telefonico=&rcpt_addr=via%20felrina%20sud%20172&rcpt_cap=31044&rcpt_city=Montebelluna&rcpt_country_code=IT&rcpt_prov=BG&sender_addr=VIA%20FERRANTE%20CARACCIOLO&sender_cap=24040&sender_city=LECCE&sender_country_code=IT&sender_prov=BG&tipo_listino=passivo&valore=&volume=0&invoiced_client_id=1249") .get() .addHeader("x-api-key", "YOUR_API_KEY") .addHeader("Accept", "*/*") .addHeader("Cache-Control", "no-cache") .addHeader("Host", "apistaging.aws.gsped.it") .addHeader("accept-encoding", "gzip, deflate") .addHeader("Connection", "keep-alive") .addHeader("cache-control", "no-cache") .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% endtabs %} ## Lowest `GET` `https://api.gsped.it/istanza/RateComparativa/lowest` L'utilizzo di questo endpoint è uguale a quello della [rateComparativa GET](#ratecomparativa) ma in risposta si ottiene solo il servizio più economico rispettivamente per listino attivo/passivo come da richiesta effettuata. Esempi di risposta: {% tabs %} {% tab title="200 In caso di elaborazione corretta" %} 
{
    "passivo": {
        "DHL": {
            "Domestic Express": {
                "codice_corriere": "104",
                "codice_servizio": "0",
                "client_id": "1",
                "nolo": 28.55,
                "varie": 0,
                "totale": 28.55,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    },
    "attivo": {
        "TNT": {
            "Nazionale Express": {
                "codice_corriere": "2",
                "codice_servizio": "0",
                "client_id": "2",
                "nolo": 26.68,
                "varie": 0,
                "totale": 26.68,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    }
}
{% endtab %} {% tab title="400 In caso di campi INPUT errati o mancanti" %} ```json { "Error": "client_id: dato obbligatorio" } ``` {% endtab %} {% endtabs %} ## Fastest `GET` `https://api.gsped.it/istanza/RateComparativa/fastest` L'utilizzo di questo endpoint è uguale a quello della [rateComparativa GET](#ratecomparativa) ma in risposta si ottiene solo il corriere più veloce rispettivamente per listino attivo/passivo come da richiesta effettuata. Esempi di risposta: {% tabs %} {% tab title="200 In caso di elaborazione corretta" %} ```json { "passivo": { "DHL - GSPED DHL": { "Domestic Express": { "codice_corriere": 104, "codice_servizio": "0", "client_id": "390", "nolo": 8.91, "varie": 1.67, "totale": 12.91, "totale_tasse": 2.33, "totale_no_tax": 10.58, "cutoff": "2025-09-16T17:00:00", "arrivo": "2025-09-17T23:59:00", "tempo_transito": "1", "varie_dettaglio": { "fuel_surcharge": 1.67 } } } } } ``` {% endtab %} {% tab title="400 In caso di campi INPUT errati o mancanti" %} ```json { "Error": "client_id: dato obbligatorio" } ``` {% endtab %} {% endtabs %}