# Comparative Rate POST The RateComparativa endpoint allows a preliminary cost analysis of a shipment based on your active or passive price lists saved and managed on Gsped, such as: * Freight (base shipping cost) * Ancillary costs calculable in advance * Cash on delivery cost * Insurance cost * FUEL surcharge * Remote areas or islands * Additional services (floor delivery, Saturday delivery, etc.) * Oversize surcharges based on standard rules * Etc. Two types of rating are available: * **ACTIVE**: cost analysis based on active price lists, i.e. the ones you use to resell shipping to your customers * **PASSIVE**: cost analysis based on the price lists agreed with the courier during contract negotiation. This mode automatically includes the ACTIVE rating as well, allowing a quick comparison between purchasing and selling costs of the shipment *** ### RateComparativa - POST `POST` `https://api.gsped.it/[INSTANCE]/RateComparativa` **Headers** | Name | Type | Description | | -------------- | ------ | ------------------------- | | x-api-key\* | String | API key provided by Gsped | | Content-Type\* | String | `application/json` | **Request Body** | Name | Type | Description | | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client\_id\* | Integer | Client ID to use for rating | | colli\* | Integer | Number of parcels in the shipment | | peso\* | Float | Total shipment weight in KG | | volume\* | Float | Total shipment volume in cubic meters | | sender\_addr\* | String | Sender address | | sender\_city\* | String | Sender city | | sender\_cap\* | String | Sender postal code | | sender\_prov\* | String | Sender province/state abbreviation | | sender\_country\_code\* | String | Sender country ISO 2-char code | | rcpt\_addr\* | String | Recipient address | | rcpt\_city\* | String | Recipient city | | rcpt\_cap\* | String | Recipient postal code | | rcpt\_prov\* | String | Recipient province/state abbreviation | | rcpt\_country\_code\* | String | Recipient country ISO 2-char code | | tipo\_listino\* | String | `attivo` \| `passivo` — defines the type of rating to perform. **N.B.: Setting `passivo` returns both** | | invoiced\_client\_id | Integer | Client ID to use for ACTIVE rating in RESELLER instances | | departure\_date\_time | String | Estimated goods-ready date/time in `YYYY-MM-DD HH:MM:SS` format. If not provided, the request datetime is used. **N.B.: If the date provided is in the past, the call will return an error!** | | contrassegno | Float | Cash on delivery amount | | valore | Float | Insured value amount | | documenti | String | `0` \| `1` — identifies whether this is a documents-only shipment | | al\_piano | String | `0` \| `1` — identifies whether floor delivery service is requested (calculated only if the courier provides the service) | | al\_sabato | String | `0` \| `1` — identifies whether Saturday delivery service is requested (calculated only if the courier provides the service) | | preavviso\_telefonico | String | `S` \| `N` — identifies whether a phone pre-notification at delivery is requested | | gls\_exchange | String | `N` \| `S` — identifies whether the EXCHANGE service is requested for GLS courier | | corriereRichiesto | Integer | Identifies the Gsped courier ID for which results are requested | | servizioRichiesto | Integer | Identifies the Gsped service ID for which results are requested. Works in combination with `corriereRichiesto` | | corrieriEsclusi | Array | List of Gsped courier IDs to exclude from the calculation. **Cannot be used together with** `corriereRichiesto` | | serviziEsclusi | Array | List of Gsped service IDs to exclude from the calculation. **Can only be used when** `corriereRichiesto` **is present** and **cannot be used together with** `servizioRichiesto` | | daticolli | Array | Individual parcel data in CM \| KG \| cubic meters. Fields: `altezza`, `larghezza`, `lunghezza`, `peso`, `volume` | {% hint style="warning" %} #### **Filter parameter rules** * `corrieriEsclusi` and `corriereRichiesto` **cannot be used together** * `serviziEsclusi` and `servizioRichiesto` **cannot be used together** * `serviziEsclusi` can only be used **when** `corriereRichiesto` **is present** {% endhint %} #### Code snippets {% tabs %} {% tab title="PHP" %} ```php "https://api.gsped.it/sandbox/RateComparativa", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode([ "colli" => 1, "peso" => 3.81, "volume" => 0.01, "tipo_listino" => "passivo", "sender_addr" => "Via Ofanto snc", "sender_cap" => "04100", "sender_city" => "Latina", "sender_prov" => "LT", "sender_country_code" => "IT", "rcpt_addr" => "Corso Felice Cavallotti 15", "rcpt_cap" => "15121", "rcpt_city" => "Alessandria", "rcpt_prov" => "AL", "rcpt_country_code" => "IT", "client_id" => 390, "user_id" => 6 ]), CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "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="PYTHON" %} ```python import http.client import json conn = http.client.HTTPSConnection("api.gsped.it") payload = json.dumps({ "colli": 1, "peso": 3.81, "volume": 0.01, "tipo_listino": "passivo", "sender_addr": "Via Ofanto snc", "sender_cap": "04100", "sender_city": "Latina", "sender_prov": "LT", "sender_country_code": "IT", "rcpt_addr": "Corso Felice Cavallotti 15", "rcpt_cap": "15121", "rcpt_city": "Alessandria", "rcpt_prov": "AL", "rcpt_country_code": "IT", "client_id": 390, "user_id": 6 }) headers = { "Content-Type": "application/json", "x-api-key": "YOUR-API-KEY" } conn.request("POST", "/sandbox/RateComparativa", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` {% endtab %} {% tab title="GO" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://api.gsped.it/sandbox/RateComparativa" payload := strings.NewReader(`{ "colli": 1, "peso": 3.81, "volume": 0.01, "tipo_listino": "passivo", "sender_addr": "Via Ofanto snc", "sender_cap": "04100", "sender_city": "Latina", "sender_prov": "LT", "sender_country_code": "IT", "rcpt_addr": "Corso Felice Cavallotti 15", "rcpt_cap": "15121", "rcpt_city": "Alessandria", "rcpt_prov": "AL", "rcpt_country_code": "IT", "client_id": 390, "user_id": 6 }`) req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") req.Header.Add("x-api-key", "YOUR-API-KEY") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` {% endtab %} {% tab title="C#" %} ```csharp var client = new HttpClient(); var request = new HttpRequestMessage { Method = HttpMethod.Post, RequestUri = new Uri("https://api.gsped.it/sandbox/RateComparativa"), Headers = { { "x-api-key", "YOUR-API-KEY" }, }, Content = new StringContent(@"{ ""colli"": 1, ""peso"": 3.81, ""volume"": 0.01, ""tipo_listino"": ""passivo"", ""sender_addr"": ""Via Ofanto snc"", ""sender_cap"": ""04100"", ""sender_city"": ""Latina"", ""sender_prov"": ""LT"", ""sender_country_code"": ""IT"", ""rcpt_addr"": ""Corso Felice Cavallotti 15"", ""rcpt_cap"": ""15121"", ""rcpt_city"": ""Alessandria"", ""rcpt_prov"": ""AL"", ""rcpt_country_code"": ""IT"", ""client_id"": 390, ""user_id"": 6 }") { Headers = { ContentType = new MediaTypeHeaderValue("application/json") } } }; using (var response = await client.SendAsync(request)) { response.EnsureSuccessStatusCode(); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine(body); } ``` {% endtab %} {% tab title="cURL" %} ```shell curl --request POST \ --url https://api.gsped.it/sandbox/RateComparativa \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR-API-KEY' \ --data '{ "colli": 1, "peso": 3.81, "volume": 0.01, "tipo_listino": "passivo", "sender_addr": "Via Ofanto snc", "sender_cap": "04100", "sender_city": "Latina", "sender_prov": "LT", "sender_country_code": "IT", "rcpt_addr": "Corso Felice Cavallotti 15", "rcpt_cap": "15121", "rcpt_city": "Alessandria", "rcpt_prov": "AL", "rcpt_country_code": "IT", "client_id": 390, "user_id": 6 }' ``` {% endtab %} {% tab title="JSON" %} ```json { "colli": 1, "sender_country_code": "IT", "volume": 0.01, "peso": 3.81, "sender_prov": "LT", "sender_addr": "Via Ofanto snc", "sender_city": "Latina", "sender_cap": "04100", "client_id": 390, "tipo_listino": "passivo", "rcpt_country_code": "IT", "rcpt_addr": "Corso Felice Cavallotti 15", "rcpt_cap": "15121", "rcpt_city": "Alessandria", "rcpt_prov": "AL", "user_id": 6 } ``` {% endtab %} {% endtabs %} #### **Response examples** {% tabs %} {% tab title="200: OK" %} ```json { "status": 200, "response": { "passivo": { "UPS - Client": { "Nazionale UPS Express Saver": { "codice_corriere": 103, "codice_servizio": "0", "client_id": "2", "nolo": 5.75, "varie": 0.75, "totale": 7.94, "totale_tasse": "1.44", "totale_no_tax": 6.50, "cutoff": "2026-03-26T18:00:00", "arrivo": "2026-03-27T23:30:00", "tempo_transito": "1", "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "fuel_surcharge": "0.75" } }, "Nazionale UPS Standard": { "codice_corriere": 103, "codice_servizio": "3", "client_id": "2", "nolo": 5.43, "varie": 0.40, "totale": 7.11, "totale_tasse": "1.28", "totale_no_tax": 5.83, "cutoff": "2026-03-26T18:00:00", "arrivo": "2026-03-27T23:30:00", "tempo_transito": "1", "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "fuel_surcharge": "0.40" } } }, "DHL - Client": { "Domestic Express": { "codice_corriere": 104, "codice_servizio": "0", "client_id": "2", "nolo": 9.70, "varie": 1.77, "totale": 13.99, "totale_tasse": 2.52, "totale_no_tax": 11.47, "cutoff": "2026-03-26T17:00:00", "arrivo": "2026-03-27T23:59:00", "tempo_transito": "1", "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "fuel_surcharge": 1.77 } } }, "GLS - Client": { "Espresso Nazionale": { "codice_corriere": 101, "codice_servizio": "0", "client_id": "2", "nolo": 4.20, "varie": 0.05, "totale": 4.25, "totale_tasse": 0, "totale_no_tax": 4.25, "cutoff": null, "arrivo": null, "tempo_transito": 1, "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "Adeguamento autostrade e traghetti": 0.05 } } } } } } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="403: Forbidden" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} *** ### Lowest - POST `POST` `https://api.gsped.it/[INSTANCE]/RateComparativa/lowest` This endpoint works exactly like [RateComparativa POST](#ratecomparativa-post) but returns only the **cheapest** service for each active/passive price list as requested. #### **Headers** | Name | Type | Description | | -------------- | ------ | ------------------------- | | x-api-key\* | String | API key provided by Gsped | | Content-Type\* | String | `application/json` | #### **Response examples** {% tabs %} {% tab title="200: OK" %} ```json { "status": 200, "response": { "passivo": { "GLS - Client": { "Espresso Nazionale": { "codice_corriere": 101, "codice_servizio": "0", "client_id": "2", "nolo": 4.20, "varie": 0.05, "totale": 4.25, "totale_tasse": 0, "totale_no_tax": 4.25, "cutoff": null, "arrivo": null, "tempo_transito": 1, "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "Adeguamento autostrade e traghetti": 0.05 } } } } } } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="403: Forbidden" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} *** ### Fastest - POST `POST` `https://api.gsped.it/[INSTANCE]/RateComparativa/fastest` This endpoint works exactly like [RateComparativa POST](#ratecomparativa-post) but returns only the **fastest** courier for each active/passive price list as requested. **Headers** | Name | Type | Description | | -------------- | ------ | ------------------------- | | x-api-key\* | String | API key provided by Gsped | | Content-Type\* | String | `application/json` | #### **Response examples** {% tabs %} {% tab title="200: OK" %} ```json { "status": 200, "response": { "passivo": { "GLS - Client": { "Espresso Nazionale": { "codice_corriere": 101, "codice_servizio": "0", "client_id": "2", "nolo": 4.20, "varie": 0.05, "totale": 4.25, "totale_tasse": 0, "totale_no_tax": 4.25, "cutoff": null, "arrivo": null, "tempo_transito": 1, "arrivo_stimato": "2026-03-27", "varie_dettaglio": { "Adeguamento autostrade e traghetti": 0.05 } } } } } } ``` {% endtab %} {% tab title="400: Bad Request" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="403: Forbidden" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %}