> 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/spedizioni-e-dintorni/add-parcel.md).

# Add Parcel

Dynamic parcel management

### Overview

Once the main shipment has been created, the **Add Parcel** feature lets you add or remove parcels independently and get the corresponding labels.

### Supported couriers

\* see [notes](#courier-notes)

|    COURIER (Gsped ID)   | ADD PARCELS | REMOVE PARCELS |
| :---------------------: | :---------: | :------------: |
|        BRT\* (1)        |     Yes     |       Yes      |
|        TNT\* (2)        |     Yes     |       Yes      |
|      DPDFrance (6)      |     Yes     |       Yes      |
|   PDB Inviosystem (19)  |     Yes     |       Yes      |
|        Fedex (20)       |     Yes     |       Yes      |
|         RKS (28)        |     Yes     |       Yes      |
|       Dummy1 (70)       |     Yes     |       Yes      |
|       Dummy2 (71)       |     Yes     |       Yes      |
|       Dummy3 (72)       |     Yes     |       Yes      |
|       Dummy4 (73)       |     Yes     |       Yes      |
|       Dummy5 (74)       |     Yes     |       Yes      |
|       Dummy6 (75)       |     Yes     |       Yes      |
|       Dummy7 (76)       |     Yes     |       Yes      |
|       Dummy8 (77)       |     Yes     |       Yes      |
|       Dummy9 (78)       |     Yes     |       Yes      |
|       Dummy10 (79)      |     Yes     |       Yes      |
|    Italsempione (90)    |     Yes     |       Yes      |
|    Logisticando (91)    |     Yes     |       Yes      |
|    CSI Logistica (92)   |     Yes     |       Yes      |
|      Ribosped (93)      |     Yes     |       Yes      |
|    Zust - Tiesse (94)   |     Yes     |       Yes      |
|        Lynx (95)        |     Yes     |       Yes      |
|     Speditalia (97)     |     Yes     |       Yes      |
|         SVL (98)        |     Yes     |       Yes      |
|        ARCO (100)       |     Yes     |       Yes      |
|        GLS (101)        |     Yes     |       No       |
|       Fercam (131)      |     Yes     |       Yes      |
|       CEVA\* (164)      |     Yes     |       Yes      |
|        ALT (178)        |     Yes     |       Yes      |
|      LICCARDI (179)     |     Yes     |       Yes      |
|      DHL WLA (182)      |     Yes     |       Yes      |
| Ferrari Trasporti (190) |     Yes     |       Yes      |
|      Bracchi (191)      |     Yes     |       Yes      |
|      Sending (192)      |     Yes     |       Yes      |
|  Rhenus Logistics (193) |     Yes     |       Yes      |
|     UPS Offline (31)    |     Yes     |       Yes      |
|    Pittagorando (37)    |     Yes     |       Yes      |
|   Reni Trasporti (38)   |     Yes     |       Yes      |
|   UPS Healthcare (39)   |     Yes     |       Yes      |
|       Gruber (41)       |     Yes     |       Yes      |
|       Grendi (42)       |     Yes     |       Yes      |

{% hint style="info" %}
The list of enabled couriers is subject to change; please check for updates regularly
{% endhint %}

<details>

<summary>Courier notes</summary>

* BRT -> B2 solution only
* TNT -> only on the same date the label was created and before the pickup date/time.
* ALT and Liccardi -> inform Gsped that you intend to make Add/Delete Parcels calls (requires a configuration change)

</details>

### How the Add Parcel process works

To use the **Add Parcel** feature correctly you need 3 endpoints:

1. **Shipment** POST - to create the shipment
2. **Parcels** POST or DELETE - to add or remove parcels
3. **ShipmentConfirm** POST - for the final confirmation of the shipment, which closes it to changes

{% hint style="danger" %}
WARNING: Removing the only parcel of a shipment is equivalent to deleting the shipment.
{% endhint %}

{% hint style="info" %}
WARNING: Confirming a shipment prevents adding or removing parcels from it
{% endhint %}

## Add a single parcel to a shipment

<mark style="color:green;">`POST`</mark> `https://api.gsped.it/[INSTANCE]/Parcels`

JSON body.\
Can be used in 2 ways:\
1 - Shipment ID only + parcel data\
2 - Recipient data + parcel data

#### Request Body

| Name                                                  | Type   | Description                            |
| ----------------------------------------------------- | ------ | -------------------------------------- |
| id\_sped<mark style="color:red;">\*</mark>            | String | Unique Gsped ID                        |
| ddt\_alpha<mark style="color:red;">\*</mark>          | String | Alphanumeric reference of the shipment |
| rcpt\_cap<mark style="color:red;">\*</mark>           | String | Recipient postcode                     |
| rcpt\_city<mark style="color:red;">\*</mark>          | String | Recipient city                         |
| rcpt\_addr<mark style="color:red;">\*</mark>          | String | Recipient address                      |
| rcpt\_name<mark style="color:red;">\*</mark>          | String | Recipient name                         |
| rcpt\_prov<mark style="color:red;">\*</mark>          | String | Recipient province/state               |
| rcpt\_country\_code<mark style="color:red;">\*</mark> | String | Recipient country, 2-char ISO code     |
| collo<mark style="color:red;">\*</mark>               | Object | [Parcel data](#parcel-object)          |

{% tabs %}
{% tab title="200: OK Parcel added successfully" %}

```javascript
{
    "id_collo": 2,
    "id_sped": "123456789",
    "labels": {
        "jpg": "Stringa base64",
        "pdf": "Stringa base64",
        "zpl": "Stringa ZPL"
    },
    "tracking_collo": "JJD01111111111"
}
```

{% endtab %}

{% tab title="400: Bad Request Wrong payload" %}

```javascript
{
  "error": "Dati spedizione non presenti o in formato sbagliato"
}
```

{% endtab %}

{% tab title="404: Not Found Shipment not found by ID" %}

```javascript
{
  "error": "Shipment '1234' doesn't exists!"
}
```

{% endtab %}

{% tab title="404: Not Found Shipment not found by recipient data" %}

```javascript
{
  "error": "Unable to find unique shipment by ddt and address"
}
```

{% endtab %}
{% endtabs %}

### Parcel object

| Attribute     | Type    | Required |
| ------------- | ------- | :------: |
| peso          | integer |     X    |
| volume        | float   |     X    |
| larghezza     | integer |     X    |
| altezza       | integer |     X    |
| lunghezza     | integer |     X    |
| codice\_collo | string  |          |

### Parcels POST payload example

{% tabs %}
{% tab title="Shipment ID" %}

```json
{
  "id_sped":"1234567",
  "collo": {
    "peso": "5",
    "volume": "0.01",
    "larghezza": "35",
    "altezza": "15",
    "lunghezza": "10",
    "codice_collo": "identificativo1234"
  }
}
```

{% endtab %}

{% tab title="Recipient data" %}

```json
{
  "ddt_alpha":"test_parcel_8",
  "rcpt_name":"Rossi Gino",
  "rcpt_addr":"Via Milano 8",
  "rcpt_cap":"20123",
  "rcpt_city":"Milano",
  "rcpt_prov":"MI",
  "rcpt_country_code" : "IT",
  "collo": {
    "peso": "5",
    "volume": "0.01",
    "larghezza": "35",
    "altezza": "15",
    "lunghezza": "20",
    "codice_collo": "identificativo1234"
  }
}
```

{% endtab %}
{% endtabs %}

### Parcel POST example code snippet

{% tabs %}
{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/Parcels",
  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  \"id_sped\":\"1\",\n  \"collo\": {\n    \"peso\": \"5\",\n    \"volume\": \"0.01\",\n    \"larghezza\": \"35\",\n    \"altezza\": \"15\",\n    \"lunghezza\": \"10\"\n  }\n}",
  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

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

payload = "{\n  \"id_sped\":\"1\",\n  \"collo\": {\n    \"peso\": \"5\",\n    \"volume\": \"0.01\",\n    \"larghezza\": \"35\",\n    \"altezza\": \"15\",\n    \"lunghezza\": \"10\"\n  }\n}"

headers = {
    'Content-Type': "application/json",
    'x-api-key': "YOUR-API-KEY"
    }

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

	payload := strings.NewReader("{\n  \"id_sped\":\"1\",\n  \"collo\": {\n    \"peso\": \"5\",\n    \"volume\": \"0.01\",\n    \"larghezza\": \"35\",\n    \"altezza\": \"15\",\n    \"lunghezza\": \"10\"\n  }\n}")

	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/Parcels"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent("{\n  \"id_sped\":\"1\",\n  \"collo\": {\n    \"peso\": \"5\",\n    \"volume\": \"0.01\",\n    \"larghezza\": \"35\",\n    \"altezza\": \"15\",\n    \"lunghezza\": \"10\"\n  }\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);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url https://api.gsped.it/sandbox/Parcels \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data '{
  "id_sped":"1",
  "collo": {
    "peso": "5",
    "volume": "0.01",
    "larghezza": "35",
    "altezza": "15",
    "lunghezza": "10"
  }
}'
```

{% endtab %}
{% endtabs %}

## Remove a parcel from a shipment

<mark style="color:red;">`DELETE`</mark> `https://api.gsped.it/[INSTANCE]/Parcels`

Form Url-Encoded Body\
Can be used in 2 ways:\
1 - Shipment ID only + parcel data\
2 - Recipient data + parcel data

**N.B: the call ALWAYS and ONLY deletes the last parcel of the shipment.**

**An intermediate parcel cannot be deleted.**

#### Request Body

| Name                | Type   | Description                            |
| ------------------- | ------ | -------------------------------------- |
| id\_sped            | String | Unique Gsped ID                        |
| ddt\_alpha          | String | Alphanumeric reference of the shipment |
| rcpt\_name          | String | Recipient name                         |
| rcpt\_addr          | String | Recipient address                      |
| rcpt\_city          | String | Recipient city                         |
| rcpt\_cap           | String | Recipient postcode                     |
| rcpt\_prov          | String | Recipient province/state               |
| rcpt\_country\_code | String | Recipient country, 2-char ISO code     |

{% tabs %}
{% tab title="200: OK Parcel removed" %}

```javascript
{
    "id": "50000723",
    "num_spedizione": "7004525883",
    "num_collo": 1
}
```

{% endtab %}

{% tab title="200: OK Last parcel removed and shipment deleted" %}

```javascript
{
    "result": "Shipment deleted"
}
```

{% endtab %}

{% tab title="403: Forbidden Deletion of a confirmed shipment" %}

```javascript
{
    "error" : "This shipment is already confirmed"
}
```

{% endtab %}

{% tab title="404 Shipment does not exist for ID" %}

```javascript
{
  "error": "Shipment '1' doesn't exists!"
}
```

{% endtab %}

{% tab title="404: Not Found Shipment does not exist for recipient data" %}

```javascript
{
  "error": "Unable to find unique shipment by ddt and address"
}
```

{% endtab %}
{% endtabs %}

### Parcels DELETE example code snippet

{% tabs %}
{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/Parcels",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => "id_sped=69562763",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/x-www-form-urlencoded",
    "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

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

payload = "id_sped=69562763"

headers = {
    'Content-Type': "application/x-www-form-urlencoded",
    'x-api-key': "YOUR-API-KEY"
    }

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

	payload := strings.NewReader("id_sped=69562763")

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

	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
	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.Delete,
    RequestUri = new Uri("https://api.gsped.it/sandbox/Parcels"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        { "id_sped", "69562763" },
    }),
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request DELETE \
  --url https://api.gsped.it/sandbox/Parcels \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-api-key: YOUR-API-KEY' \
  --data id_sped=69562763
```

{% endtab %}
{% endtabs %}