# 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

<mark style="color:$warning;">`POST`</mark> `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
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "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

<mark style="color:$warning;">`POST`</mark> `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

<mark style="color:$warning;">`POST`</mark> `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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.gsped.com/gsped-api-english-version/rating/comparative-rate-post.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.