> For the complete documentation index, see [llms.txt](https://apidocs.gsped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.gsped.com/gsped-api-english-version/rating/master.md). # Comparative Rate POST Preliminary shipment cost analysis The RateComparativa endpoint lets you run a preliminary analysis of the costs of a shipment that can be calculated in advance, using your price lists (selling or purchase) saved and managed on Gsped, such as: * Freight (base shipping cost) * Ancillary charges calculable in advance * Cash on delivery (COD) cost * Insurance cost * FUEL * Remote areas or islands * Additional services (floor delivery, Saturday delivery, etc.) * Oversize charges based on standard rules * Etc. Two types of rating are available: * **ACTIVE**: cost analysis based only on selling price lists, i.e. the ones you use to resell the shipment to your customers * **PASSIVE**: shipping cost analysis based on the price lists agreed with the courier during contract negotiation. This mode automatically adds the ACTIVE rating as well, so you can also quickly analyse the difference between the purchase and selling costs of the transport. *** ### 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 on which you want to run the rating | | colli\* | Integer | Number of parcels in the shipment | | peso\* | Float | Total shipment weight in KG | | volume\* | Float | Total shipment volume in m³ | | sender\_addr\* | String | SENDER address | | sender\_city\* | String | SENDER city | | sender\_cap\* | String | SENDER postal code | | sender\_prov\* | String | SENDER province code | | 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 code | | rcpt\_country\_code\* | String | RECIPIENT country ISO 2-char code | | tipo\_listino\* | String | `attivo` \| `passivo` — identifies the type of rating to perform. **N.B.: If you set `passivo`, both are returned** | | invoiced\_client\_id | Integer | Client ID on which the ACTIVE rating will be run in RESELLER instances | | departure\_date\_time | String | Date and time the goods are expected to be ready, in `YYYY-MM-DD HH:MM:SS` format. If not set, the request datetime is used. **N.B.: If the date provided is in the past, the call returns an error!** | | contrassegno | Float | Shipment cash on delivery (COD) amount | | valore | Float | Insured value amount | | documenti | String | `0` \| `1` — identifies whether this is a documents shipment | | al\_piano | String | `0` \| `1` — identifies whether the floor delivery service has been requested (calculated only if the courier provides the service) | | al\_sabato | String | `0` \| `1` — identifies the request for the Saturday delivery service (calculated only if the courier provides the service) | | preavviso\_telefonico | String | `S` \| `N` — identifies whether a phone notice before delivery is requested | | gls\_exchange | String | `N` \| `S` — identifies the request for the EXCHANGE service for the GLS courier | | corriereRichiesto | Integer | Identifies the ID of the specific courier you want results for | | servizioRichiesto | Integer | Identifies the ID of the service you want the result for. 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 | Data of the individual parcels in CM \| KG \| MC. Fields: `altezza`, `larghezza`, `lunghezza`, `peso`, `volume` | {% hint style="warning" %} ### **Filter parameter usage rules** * `corrieriEsclusi` and `corriereRichiesto` **cannot be used together** * `serviziEsclusi` and `servizioRichiesto` **cannot be used together** * `serviziEsclusi` can be used **only when** `corriereRichiesto` **is present** {% endhint %} {% hint style="info" %} ### **Permissions and price lists** * The user associated with the API key must be enabled for active or passive rating: otherwise the call responds **401** with `"error": "Permessi insufficienti"`. * With `tipo_listino` = `passivo`, the passive rating is returned only to users enabled for passive rating; for the others, only the active rating is calculated. * With `tipo_listino` = `attivo`, the call responds **400** with `"Errori durante procedura di rating, verificare i dati inseriti."` even when the data is correct but no selling price list is available for the given client: in this case, use `passivo`. {% endhint %} #### Example code snippets {% tabs %} {% tab title="PHP" %} ```javascript "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" %} ```javascript 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" %} ```shellscript 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 %} #### **Example responses** {% tabs %} {% tab title="200: OK Shipment information" %} ```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 Input error" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="401: Unauthorized User not enabled for rating" %} ```json { "error": "Permessi insufficienti" } ``` {% endtab %} {% tab title="403: Forbidden Invalid API key" %} ```json { "status": false, "error": "Invalid API key " } ``` {% endtab %} {% tab title="404: Not Found Shipment not found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} *** ### Lowest - POST `POST` `https://api.gsped.it/[INSTANCE]/RateComparativa/lowest` This endpoint is used the same way as RateComparativa POST, but the response contains only the **cheapest** service for the selling/purchase price list respectively, according to the request made. #### **Headers** | Name | Type | Description | | -------------- | ------ | ------------------------- | | x-api-key\* | String | API key provided by Gsped | | Content-Type\* | String | `application/json` | #### **Example responses** {% tabs %} {% tab title="200: OK Shipment information" %} ```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 Input error" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="403: Forbidden Invalid API key" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Shipment not found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} *** ### Fastest - POST `POST` `https://api.gsped.it/[INSTANCE]/RateComparativa/fastest` This endpoint is used the same way as RateComparativa POST, but the response contains only the **fastest** courier for the selling/purchase price list respectively, according to the request made. **Headers** | Name | Type | Description | | -------------- | ------ | ------------------------- | | x-api-key\* | String | API key provided by Gsped | | Content-Type\* | String | `application/json` | #### **Example responses** {% tabs %} {% tab title="200: OK Shipment information" %} ```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 Input error" %} ```json { "status": 400, "errors": "client_id: dato obbligatorio" } ``` {% endtab %} {% tab title="403: Forbidden Invalid API key" %} ```javascript { // Response } ``` {% endtab %} {% tab title="404: Not Found Shipment not found" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %}