> 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/labels.md).

# Labels

Endpoint to retrieve the label of a specific parcel

Returns the label of **a single parcel** of a shipment, without downloading the file with the labels of all the parcels.

## Retrieve the label of a parcel

<mark style="color:blue;">`GET`</mark> `https://api.gsped.it/[INSTANCE]/labels/[id_spedizione]`

The parcel is specified by number **or** by code: the two parameters are alternatives, and specifying both is an error.

#### Path Parameters

| Name                                             | Type   | Description              |
| ------------------------------------------------ | ------ | ------------------------ |
| id\_spedizione<mark style="color:red;">\*</mark> | String | Unique Gsped shipment ID |

#### Query Parameters

| Name          | Type   | Description                                                    |
| ------------- | ------ | -------------------------------------------------------------- |
| n\_collo      | String | Parcel number, from 1 to the number of parcels in the shipment |
| codice\_collo | String | Parcel code; must be unique within the shipment                |

#### Headers

| Name                                        | Type   | Description              |
| ------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark> | String | APIKEY provided by Gsped |

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

```javascript
{
  "status": 200,
  "response": {
    "id_sped": 1234,
    "id_collo": 2,
    "labels": {
      "zpl": "^XA...^XZ",
      "pdf": "JVBERi0xLjQK..."
    }
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Parcel not specified" %}

```javascript
{
  "status": 400,
  "errors": [
    "Collo non indicato: serve n_collo oppure codice_collo"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="400: Bad Request Conflicting parameters" %}

```javascript
{
  "status": 400,
  "errors": [
    "Indicare n_collo oppure codice_collo, non entrambi"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="400: Bad Request Parcel code not unique" %}

```javascript
{
  "status": 400,
  "errors": [
    "Codice collo non univoco per la spedizione"
  ],
  "response": []
}
```

{% endtab %}

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

```javascript
{
  "status": 404,
  "errors": [
    "Spedizione non trovata"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="404: Not Found Label not available" %}

```javascript
{
  "status": 404,
  "errors": [
    "Etichetta non disponibile per il collo indicato"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid apikey" %}

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

{% endtab %}
{% endtabs %}

The **PDF** is base64-encoded, the **ZPL** is returned as text. If only the ZPL is available for that parcel, the PDF is produced by converting it; if that is missing too, the field is left empty.

{% hint style="warning" %}
Some couriers do not store a label for each parcel, but a single file with the labels of the whole shipment. For those shipments the endpoint returns that file when you request the first parcel, and responds 404 for the following parcels.
{% endhint %}

#### Example code snippets

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/labels/1234?n_collo=2",
  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;
}
```

{% endtab %}

{% tab title="PYTHON" %}

```python
import http.client

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

payload = ""

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

conn.request("GET", "/sandbox/labels/1234?n_collo=2", payload, headers)

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

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

{% endtab %}

{% tab title="GO" %}

```go
package main

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

func main() {

	url := "https://api.gsped.it/sandbox/labels/1234?n_collo=2"

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

}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.gsped.it/sandbox/labels/1234?n_collo=2"),
    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);
}
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url 'https://api.gsped.it/sandbox/labels/1234?n_collo=2' \
  --header 'x-api-key: YOUR-API-KEY'
```

{% endtab %}
{% endtabs %}