Comparative Rate POST

Preventive analysis of shipment costs

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

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

Code snippets

<?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;
}

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"))

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))
}

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);
}

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
}'

{
  "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
}

Response examples

{
  "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
          }
        }
      }
    }
  }
}

Lowest - POST

POST https://api.gsped.it/[INSTANCE]/RateComparativa/lowest

This endpoint works exactly like 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

{
  "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
          }
        }
      }
    }
  }
}

Fastest - POST

POST https://api.gsped.it/[INSTANCE]/RateComparativa/fastest

This endpoint works exactly like 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

{
  "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
          }
        }
      }
    }
  }
}

PreviousComparative Rate

hashtagRateComparativa - POST

hashtagFilter parameter rules

hashtagCode snippets

hashtagResponse examples

hashtagLowest - POST

hashtagHeaders

hashtagResponse examples

hashtagFastest - POST

hashtagResponse examples

RateComparativa - POST

Filter parameter rules

Code snippets

Response examples

Lowest - POST

Headers

Response examples

Fastest - POST

Response examples