Shipment

Gestione delle spedizioni

PreviousThrottling NextShipment objects

Last updated 1 month ago

Shipment - GET

Questo endpoint permette di gestire la creazione, recupero e la cancellazione delle spedizioni su Gsped.

Shipment -GET

GET https://api.gsped.it/[ISTANZA]/Shipment

Recupera tutte le informazioni di una spedizione compre le etichette

Query Parameters

Name

Type

Description

Headers

Name

Type

Description

{
    // Response
}

{
    // Response
}

{
    // Response
}

{
    // Response
}

Snippets codice di esempio

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/Shipment?id=70059765",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => [
    "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

conn = http.client.HTTPSConnection("api.gsped.it")

payload = ""

headers = { 'x-api-key': "YOUR-API-KEY" }

conn.request("GET", "/sandbox/Shipment?id=70059765", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://api.gsped.it/sandbox/Shipment?id=70059765"

	req, _ := http.NewRequest("GET", url, nil)

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

}

// Some codevar client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.gsped.it/sandbox/Shipment?id=70059765"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

curl --request GET \
  --url 'https://api.gsped.it/sandbox/Shipment?id=70059765' \
  --header 'x-api-key: YOUR-API-KEY'

Shipment - POST

La chiamata Shipment Post permette di creare la spedizione.

Se l’operazione ha esito positivo, restituisce i dati della spedizione insieme alle relative etichette nei formati disponibili.

La creazione di una spedizione non necessariamente va sempre a buon fine, sia Gsped che i sistemi del corriere eseguono una serie di controlli sulla correttezza dei dati ricevuti, bisogna assicurarsi di gestire correttamente i possibili errori!

La logica da implementare per controllare l'esito delle chiamate è la seguente:

sulla risposta delle API sulla POST di creazione spedizione va innanzitutto controllato il codice di risposta HTTP, se è 400 i dati passati non hanno passato la prima serie di controlli sui dati, in quel caso il campo error contiene indicazioni sul problema riscontrato (ad esempio campi obbligatori mancanti).

Se il codice di risposta è 200 i dati hanno passato il primo livello di validazione ed è stata avviata la generazione della lettera di vettura. Andrà quindi verificato il valore del campo status, se contiene 0 la lettera di vettura è stata generata correttamente e potrà essere recuperata dai campi preposti nella risposta. Se invece il campo status è uguale a 0.6 la generazione della lettera di vettura è fallita e il campo error conterrà la descrizione dell’errore. Questo tipo di errori si può verificare per situazioni tipo cap e località non coerenti, indirizzo non accettato dai sistemi del corriere, servizio richiesto non disponibile per la località di destinazione et cetera.

I seguenti campi proposti nell'esempio fanno parte di un set che si può considerare "base" e comune un po' a tutti i corrieri per creare spedizioni. In caso si vogliano espandere le funzionalità o si debbano richiedere funzionalità disponibili presso uno specifico corriere va consultata la sezione degli Shipment objects, dei casi d'uso o dei corrieri.

Shipment POST

POST https://api.gsped.it/[ISTANZA]/Shipment

Creazione di una spedizione

Headers

Request Body

{
  "client_id": 390,
  "cod_destinatario": "",
  "colli": 1,
  "contrassegno": 0,
  "corriere": 104,
  "date_req_cons": "0000-00-00 00:00:00",
  "ddt_alpha": "TEST_GSPED",
  "ddt_num": 12346,
  "merce": "",
  "note_sender": "",
  "origine": "IT",
  "peso": 1.8,
  "preavviso_telefonico": "",
  "rcpt_addr": "115 E Endfield Rd",
  "rcpt_cap": 19053,
  "rcpt_city": "Feasterville Trevose",
  "rcpt_contact": "Tester",
  "rcpt_country_code": "US",
  "rcpt_email": "test@test.edu",
  "rcpt_name": "TEST MITTENTE",
  "rcpt_phone": "123456789",
  "rcpt_prov": "PA",
  "servizio": 9,
  "tipo_incasso": 0,
  "valore": 0,
  "valore_doganale": 37.5,
  "volume": 0.029,
  "status": 0,
  "fid_partenza": "",
  "num_serie": 0,
  "num_spedizione": "1253863656",
  "date_upd": "0000-00-00 00:00:00",
  "error": "",
  "sender_name": "test mittente",
  "sender_addr": "p.za Ambrosoli 13",
  "sender_cap": 15121,
  "sender_city": "Alessandria",
  "sender_contact": "Rossi Pino",
  "sender_prov": "AL",
  "sender_country_code": "IT",
  "sender_email": "test@test.it",
  "label_jpg": [
    "base64 encoded label string"
  ],
  "label_pdf": [
    "base64 encoded label string"
  ],
  "label_zpl": [
    "ZPL label string"
  ],
  "id": 50003621,
  "tnt_options": [],
  "tracking_link": "",
  "valuta": "EUR",
  "dropshipping": 0,
  "sender_phone": 12345562,
  "al_piano": "",
  "al_sabato": "",
  "reso_contestuale": "",
  "fermo_deposito": 0,
  "note": "",
  "centro_costo": "",
  "sda_servizio": "",
  "user_id": 0,
  "opening_time": "00:00:00",
  "closing_time": "00:00:00",
  "date_req_ritiro": "0000-00-00 00:00:00",
  "ups_uap_id": "",
  "sda_id_fermoposta": "",
  "note_2": "",
  "confermato": 0,
  "ups_signature_required": 0,
  "id_pickup": null,
  "documenti": 0,
  "sda_accessori": 0,
  "packaging": "",
  "dropoff_type": "",
  "vat_seller": "",
  "vat_buyer": "",
  "generic_service_point": "",
  "tipo_transazione": "supSoglia",
  "rcpt_language": "",
  "sender_eori": "",
  "rcpt_eori": "",
  "link_pickup_booking": ""
}

{
  "error": "client_id: deve essere lungo al massimo 7 caratteri"
}

{
  "status": false,
  "error": "Invalid API key "
}

Snippets codice di esempio

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/shipment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"client_id\": 390,\n  \"colli\": 2,\n  \"corriere\": 104,\n  \"ddt_alpha\": \"TEST_GSPED\",\n  \"ddt_num\": 12346,\n  \"origine\": \"IT\",\n\t\"dropshipping\" : 0,\n  \"peso\": 2.4,\n  \"rcpt_addr\": \"115 E Endfield Rd\",\n  \"rcpt_cap\": \"19053\",\n  \"rcpt_city\": \"Feasterville Trevose\",\n  \"rcpt_contact\": \"Tester\",\n  \"rcpt_country_code\": \"US\",\n  \"rcpt_email\": \"test@test.it\",\n  \"rcpt_name\": \"TEST DESTINATARIO\",\n  \"rcpt_phone\": \"2159005458\",\n  \"rcpt_prov\": \"PA\",\n  \"servizio\": 9,\n  \"valore\": 0,\n  \"valore_doganale\": 37.50,\n  \"valuta\": \"EUR\",\n  \"volume\": 0.0972}",
  CURLOPT_HTTPHEADER => [
    "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

conn = http.client.HTTPSConnection("api.gsped.it")

payload = json.dumps({
  "client_id": 390,
  "colli": 2,
  "corriere": 104,
  "ddt_alpha": "TEST_GSPED",
  "ddt_num": 12346,
  "origine": "IT",
  "dropshipping": 0,
  "peso": 2.4,
  "rcpt_addr": "115 E Endfield Rd",
  "rcpt_cap": "19053",
  "rcpt_city": "Feasterville Trevose",
  "rcpt_contact": "Tester",
  "rcpt_country_code": "US",
  "rcpt_email": "test@test.it",
  "rcpt_name": "TEST DESTINATARIO",
  "rcpt_phone": "2159005458",
  "rcpt_prov": "PA",
  "servizio": 9,
  "valore": 0,
  "valore_doganale": 37.50,
  "valuta": "EUR",
  "volume": 0.0972
})

headers = { 'x-api-key': "YOUR-API-KEY" }

conn.request("POST", "/sandbox/shipment", 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/shipment"

	payload := strings.NewReader("{\n  \"client_id\": 390,\n  \"colli\": 2,\n  \"corriere\": 104,\n  \"ddt_alpha\": \"TEST_GSPED\",\n  \"ddt_num\": 12346,\n  \"origine\": \"IT\",\n\t\"dropshipping\" : 0,\n  \"peso\": 2.4,\n  \"rcpt_addr\": \"115 E Endfield Rd\",\n  \"rcpt_cap\": \"19053\",\n  \"rcpt_city\": \"Feasterville Trevose\",\n  \"rcpt_contact\": \"Tester\",\n  \"rcpt_country_code\": \"US\",\n  \"rcpt_email\": \"test@test.it\",\n  \"rcpt_name\": \"TEST DESTINATARIO\",\n  \"rcpt_phone\": \"2159005458\",\n  \"rcpt_prov\": \"PA\",\n  \"servizio\": 9,\n  \"valore\": 0,\n  \"valore_doganale\": 37.50,\n  \"valuta\": \"EUR\",\n  \"volume\": 0.0972\n }")

	req, _ := http.NewRequest("POST", url, payload)

	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/shipment"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{\n  \"client_id\": 390,\n  \"colli\": 2,\n  \"corriere\": 104,\n  \"ddt_alpha\": \"TEST_GSPED\",\n  \"ddt_num\": 12346,\n  \"origine\": \"IT\",\n\t\"dropshipping\" : 0,\n  \"peso\": 2.4,\n  \"rcpt_addr\": \"115 E Endfield Rd\",\n  \"rcpt_cap\": \"19053\",\n  \"rcpt_city\": \"Feasterville Trevose\",\n  \"rcpt_contact\": \"Tester\",\n  \"rcpt_country_code\": \"US\",\n  \"rcpt_email\": \"test@test.it\",\n  \"rcpt_name\": \"TEST DESTINATARIO\",\n  \"rcpt_phone\": \"2159005458\",\n  \"rcpt_prov\": \"PA\",\n  \"servizio\": 9,\n  \"valore\": 0,\n  \"valore_doganale\": 37.50,\n  \"valuta\": \"EUR\",\n  \"volume\": 0.0972 \n}")
    {
        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/shipment \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
  "client_id": 390,
  "colli": 2,
  "corriere": 104,
  "ddt_alpha": "TEST_GSPED",
  "ddt_num": 12346,
  "origine": "IT",
  "dropshipping" : 0,
  "peso": 2.4,
  "rcpt_addr": "115 E Endfield Rd",
  "rcpt_cap": "19053",
  "rcpt_city": "Feasterville Trevose",
  "rcpt_contact": "Tester",
  "rcpt_country_code": "US",
  "rcpt_email": "test@test.it",
  "rcpt_name": "TEST DESTINATARIO",
  "rcpt_phone": "2159005458",
  "rcpt_prov": "PA",
  "servizio": 9,
  "valore": 0,
  "valore_doganale": 37.50,
  "valuta": "EUR",
  "volume": 0.0972
}'

Scelta del corriere più economico

Nel caso si desideri che Gsped esegua la scelta del corriere più economico in base ai propri listini (configurati su Gsped) bisogna impostare nella chiamata corriere = 0 e servizio = 0

Esempio payload :

{
    "client_id": 391,
    "corriere": 0,
    "servizio": 0,
    "ddt_num": 123,
    "ddt_alpha": "Test123",
    "colli": 1,
    "rcpt_name": "Test destinatario",
    "rcpt_addr": "INDUSTRIESTRASSE 7",
    "rcpt_cap": "4313",
    "rcpt_city": "MOEHLIN",
    "rcpt_country_code": "CH",
    "rcpt_email": "test@gsped.com",
    "sender_name": "Test mittente",
    "sender_addr": "Via Marzorati 14",
    "sender_cap": "20014",
    "sender_city": "Nerviano",
    "sender_country_code": "IT",
    "peso": 1,
    "volume": 0
}

Shipment - DELETE

Questo endpoint consente di cancellare spedizioni create in precedenza solo se non sono ancora state confermate.

Quando si cancella una spedizione le etichette restituite dalla POST NON sono più valide e devono essere eliminate!

Shipment DELETE

DELETE https://api.gsped.it/[ISTANZA]/Shipment

Cancellazione di una spedizione sui sistemi Gsped e del corriere

Query Parameters

Headers

{
  "error": ""
}

{
  "error": "Spedizione non trovata"
}

{
  "status": false,
  "error": "Invalid API key "
}

{
  "error": "ID spedizione non indicata"
}

Snippets codice di esempio

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gsped.it/sandbox/Shipment?id=53",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => [
    "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

conn = http.client.HTTPConnection("api.gsped.it")

payload = ""

headers = {
    'x-api-key': "YOUR-API-KEY"
    }

conn.request("DELETE", "/sandbox/Shipment?id=53", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "http://api.gsped.it/sandbox/Shipment?id=53"

	req, _ := http.NewRequest("DELETE", url, nil)
	
	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))

}

// Some codevar clientHandler = new HttpClientHandler
{
    UseCookies = false,
};
var client = new HttpClient(clientHandler);
var request = new HttpRequestMessage
{
    Method = HttpMethod.Delete,
    RequestUri = new Uri("http://api.gsped.it/sandbox/Shipment?id=53"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

curl --request DELETE \
  --url 'http://api.gsped.it/sandbox/Shipment?id=53' \
  --header 'x-api-key: YOUR-API-KEY'

Shipment - PATCH

Questo endpoint permette di modificare una spedizione senza bisogno di ricreare l'etichetta SOLO se la spedizione non è ancora stata confermata.

N.B. Questo endpoint è valido SOLO per alcuni campi e SOLO per alcuni corrieri. Fare riferimento alla pagina del corriere specifico per vedere i campi modificabili.

PATCH https://api.gsped.it/[ISTANZA]/Shipment/[idSpedizione]

Recupera tutte le informazioni di una spedizione compre le etichette

Headers

{
    "result": "Spedizione aggiornata con successo",
    "status": 200
}

{
    "result": <messaggioDiErrore>,
    "status": 500
}

{
    "result": <messaggioDiErrore>,
    "status": 400
}

{
    "status": false,
    "error": "Invalid API key "
}

{
    "result": "Spedizione non trovata",
    "status": 500
}

Request Body

Dipende dal corriere: VEDI QUI

Snippets codice di esempio

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/Shipment/70059765",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => "{\"campo\": \"nuovo valore\"}",
  CURLOPT_HTTPHEADER => [
    "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

conn = http.client.HTTPSConnection("api.gsped.it")

payload = json.dumps({
  "campo" => "nuovo valore"
})

headers = { 'x-api-key': "YOUR-API-KEY" }

conn.request("PATCH", "/sandbox/shipment/70059765", 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/shipment/70059765"

	payload := strings.NewReader("{ \"campo\": \"nuovo valore\" }")

	req, _ := http.NewRequest("PATCH", url, payload)

	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.Patch,
    RequestUri = new Uri("https://api.gsped.it/sandbox/shipment/70059765"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{ \"campo\": \"nuovo valore\" }")
    {
        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 PATCH \
  --url https://api.gsped.it/sandbox/shipment/70059765 \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{"campo": "nuovo valore"}'