Shipment

Gestione delle spedizioni

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
id*	String	ID univoco Gsped della spedizione

Headers

Name	Type	Description
x-api-key*	String	Apikey fornita da GSPED

200: OK Informazioni spedizione

{
    // Response
}

400: Bad Request Errore input

{
    // Response
}

403: Forbidden Apikey invalida

{
    // Response
}

404: Not Found Spedizione non trovata

{
    // Response
}

Snippets codice di esempio

PHP

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

PYTHON

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

GO

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

}

C#

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

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​ ​è​ ​la​ ​seguente:​ ​

sulla​ ​risposta​ ​delle API​ ​sulla​ ​POST​ ​di​ ​creazione​ ​spedizione​ ​va​ ​innanzitutto controllato​ ​il​ ​codice​ ​di​ ​risposta​ ​HTTP,​ ​se​ ​è​ ​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 ​è​ ​200​ ​i​ ​dati​ ​hanno​ ​passato​ ​il primo livello di validazione ​ed​ ​è​ ​stata​ ​avviata​ ​la generazione​ ​della​ ​lettera​ ​di​ ​vettura.​ ​Andrà quindi verificato il valore del campo​ ​status,​ ​se contiene​ ​0​ ​la​ ​lettera​ ​di​ ​vettura​ ​è​ ​stata​ ​generata​ ​correttamente​ ​e​ ​potrà​ ​essere​ ​recuperata​ ​dai campi​ ​preposti​ ​nella​ ​risposta.​ ​Se​ ​invece​ ​il campo status​ ​è​ ​uguale​ ​a​ ​0.6​ ​la​ ​generazione​ ​della​ ​lettera​ ​di vettura​ ​è​ ​fallita​ ​e​ ​il​ ​campo​ ​error​ ​conterrà​ ​la​ ​descrizione​ ​dell’errore.​ ​Questo​ ​tipo​ ​di​ ​errori​ ​si può​ ​verificare​ ​per​ ​situazioni​ ​tipo​ ​cap​ ​e​ ​località​ ​non​ ​coerenti,​ ​indirizzo​ ​non​ ​accettato​ ​dai sistemi​ ​del​ ​corriere,​ ​servizio​ ​richiesto​ ​non​ ​disponibile​ ​per​ ​la​ ​località​ ​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

Name	Type	Description
x-api-key*	String	Apikey rilasciata da Gsped

Request Body

Name	Type	Description
corriere*	Int	ID corriere Gsped ( Corrieri e servizi )
colli*	Int	Numero colli della spedizione
volume*	Float	Volume spedizione in Metri Cubi
peso*	Float	Peso spedizione espresso in KG
origine*	String	Nazione origine della merce sigla iso 2 char
merce*	String	Descrizione generica della merce spedita
ddt_num	String	Riferimento numerico della spedizione, se non definito Gsped ne crea uno automaticamente
ddt_alpha	String	Riferimento alfanumerico della spedizione, se non definito Gsped ne crea uno automaticamente
client_id*	Int	ID cliente fornito da Gsped
servizio*	Int	ID servizio Gsped ( Corrieri e servizi )
sender_cap	String	Zipcode del mittente
sender_city	String	Località mittente
sender_addr	String	Indirizzo mittente
sender_contact	String	Nome contatto mittente
sender_name	String	Nome mittente
rcpt_contact*	String	Nome contatto destinatario
rcpt_name*	String	Nome destinatario
sender_email	String	Email mittente
sender_phone	String	Telefono mittente
sender_country_code	String	Nazione mittente sigla iso 2 char
rcpt_prov*	String	Provincia/Stato desinatario sigla iso 2 char
rcpt_cap*	String	Zipcode destinatario
rcpt_city*	String	Località destinatario
rcpt_addr*	String	Indirizzo destinatario
sender_prov	String	Provincia/Stato mittente siga iso 2 char
rcpt_phone*	String	Telefono destinatario
rcpt_email*	String	Email destinatario
rcpt_country_code*	String	Nazione destinatario sigla iso 2 char
note_sender	String	Note del mittente
valuta		Sigla valuta iso 4217
valore	Float	Valore importo assicurazione
dropshipping	String	Flag 1 per inviare lettera di vettura alla mail del mittente
al_sabato	String	Flag S|N per attivare servizio al sabato (solo per corrieri abilitati)
al_piano	String	Flag S|N per attivare servizio al piano (solo per corrieri abilitati)
fermo_deposito	String	Flag S|N per identificare una spedizione in fermo deposito
reso_contestuale	String	Flag S|N per attivare servizio EXCHANGE (solo per corrieri abilitati)
documenti	String	Flag 0|1 per identificare una spedizione di documenti
addebito_dogana	Int	Assegnazione oneri doganali. Valori ammessi : - 0 : Oneri doganali al destinatario - 1 : Oneri doganali al mittente - 2 : Oneri doganalia terzo Nota : Nel caso questo campo non venga indicato, si assume che gli oneri doganali vanno assegnati al destinatario
chi_paga	Int	Assegnazione costi spedizione : - 0 : Paga il mittente - 1 : Paga il destinatario
valore_doganale	Float	Indicazione del valore doganale
id_order_gelproximity	String	ID ordine sui sistemi di Gel Proximity per invio tracking
invoice_date	String	Data formato YYYY-MM-GG della data della fattura
invoice_number	String	Numero della fattura
invoiced_client_id	Int	DA VALORIZZARE SOLO PER LE ISTANZE RESELLER Da utilizzare per indicare a quale cliente del reseller abbinare la spedizione.

200: OK Spedizione creata

{
  "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": "[e-mail]",
  "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": "[e-mail]",
  "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": ""
}

400: Bad Request Input errato

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

403: Forbidden Apikey invalida

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

Snippets codice di esempio

PHP

<?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\": \"[e-mail]\",\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;
}

PYTHON

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": "[e-mail]",
  "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"))

GO

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\": \"[e-mail]\",\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))

}

C#

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\": \"[e-mail]\",\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

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": "[e-mail]",
  "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": "[e-mail]",
    "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

Name	Type	Description
id*	String	ID univoco Gsped della spedizione

Headers

Name	Type	Description
x-api-key*	String	Apikey fornita da Gsped

200: OK Cancellazione avvenuta

{
  "error": ""
}

404: Not Found Spedizione non trovata

{
  "error": "Spedizione non trovata"
}

403: Forbidden Apikey invalida

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

400: Bad Request Errore input

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

Snippets codice di esempio

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://apistaging.aws.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;
}

PYTHON

import http.client

conn = http.client.HTTPConnection("apistaging.aws.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"))

GO

package main

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

func main() {

	url := "http://apistaging.aws.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))

}

C#

// Some codevar clientHandler = new HttpClientHandler
{
    UseCookies = false,
};
var client = new HttpClient(clientHandler);
var request = new HttpRequestMessage
{
    Method = HttpMethod.Delete,
    RequestUri = new Uri("http://apistaging.aws.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

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