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

# Shipment References

This endpoint lets you manage multiple references for a shipment.

## ShipmentReferences - GET

<mark style="color:green;">`GET`</mark> <https://api.gsped.it/\\[INSTANCE]/ShipmentReferences/\\[ID\\_SPEDIZIONE>]

Retrieves the references associated with the requested shipment

### URL Parameters

| Name           | Type    | Description                     |
| -------------- | ------- | ------------------------------- |
| ISTANZA        | String  | Name of the instance            |
| ID\_SPEDIZIONE | Integer | Unique Gsped ID of the shipment |

### **Headers**

| Name      | Type   |                          |
| --------- | ------ | ------------------------ |
| x-api-key | String | Apikey provided by Gsped |

**Response**

{% tabs %}
{% tab title="200" %}
References retrieved successfully

```json
{
    "primaryReference": "382993",
    "secondaryReference": [
        "ref1",
        "ref2",
        "ref3"
    ]
}
```

{% endtab %}

{% tab title="400" %}
Malformed request

```json
{
    "error": "Dati in ingresso non validi : Il campo 'id spedizione' è obbligatorio."
}
```

{% endtab %}

{% tab title="403" %}
You do not have the permissions required to manage the requested shipment

```json
{
    "error": "Non si hanno i permessi necessari per gestire la spedizione con ID XYZ"
}
```

{% endtab %}

{% tab title="404" %}
There are no references associated with the requested shipment. This code is also returned if the requested shipment does not exist

```json
{
    "error": "Non sono ancora presenti riferimenti per la spedizione con ID XYZ"
}
```

{% endtab %}
{% endtabs %}

## ShipmentReferences - POST

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

This endpoint lets you associate one or more references with the shipment.

**IMPORTANT:**

This endpoint can be called several times on the same shipment to add references as and when needed.

{% hint style="danger" %}
**Currently the maximum number of references that can be associated with a shipment is 20.**
{% endhint %}

### **Headers**

| Name      | Value    |                          |
| --------- | -------- | ------------------------ |
| x-api-key | `String` | Apikey provided by Gsped |

### **Body**

| Name         | Type    | Description                                                                                                  |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| idSpedizione | Integer | Unique Gsped ID of the shipment                                                                              |
| references   | array   | <p>Array containing the references to associate with the shipment.<br><strong>Maximum 20 items!</strong></p> |

### Example

```json
{
    "idSpedizione": 70266806,
    "references": [
        "altroRif",
        "nuovoRif"
    ]
}
```

**Response**

{% tabs %}
{% tab title="200" %}
Reference(s) added successfully

```json
{
    "status": "Riferimento associato con successo"
}
```

{% endtab %}

{% tab title="400" %}
Malformed request, or the request exceeds the number of references allowed for the shipment.

```json
{
    "error": "Dati in ingresso non validi : Il campo 'id spedizione' è obbligatorio."
}
```

{% endtab %}

{% tab title="403" %}
You do not have the permissions required to manage the requested shipment

```json
{
    "error": "Non si hanno i permessi necessari per gestire la spedizione con ID XYZ"
}
```

{% endtab %}

{% tab title="404" %}
The shipment to which the references should be associated does not exist

```json
{
    "error": "La spedizione con ID XYZ non esiste"
}
```

{% endtab %}
{% endtabs %}

## ShipmentReferences - DELETE

<mark style="color:red;">`DELETE`</mark> <https://api.gsped.it/\\[INSTANCE]/ShipmentReferences/\\[ID\\_SPEDIZIONE]/\\[REFERENCE>]

This endpoint lets you dissociate all the references of a shipment or remove a single reference

### URL Parameters

| Name           | Type    | Description                                                                                                                                                                                                                                                                                                        |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ISTANZA        | String  | Name of the instance                                                                                                                                                                                                                                                                                               |
| ID\_SPEDIZIONE | integer | Unique Gsped ID of the shipment                                                                                                                                                                                                                                                                                    |
| REFERENCE      | string  | <p><strong>Optional parameter.</strong><br><br>If set, it specifies the reference to dissociate from the shipment.<br><br><strong>NB:</strong> If it is not specified, <strong>all references</strong> are dissociated<br><br><strong>NB2:</strong> Any special characters must be <strong>urlencoded</strong></p> |

### Headers

| Name      | Type   | Description              |
| --------- | ------ | ------------------------ |
| x-api-key | string | Apikey provided by Gsped |

**Response**

{% tabs %}
{% tab title="200" %}
Reference dissociated successfully

```json
{
    "status": "Riferimento cancellato"
}
```

{% endtab %}

{% tab title="400" %}
Malformed request

```json
{
    "error": "Dati in ingresso non validi : Il campo 'id spedizione' è obbligatorio."
}
```

{% endtab %}

{% tab title="403" %}
You do not have the permissions required to manage the requested shipment

```json
{
    "error": "Non si hanno i permessi necessari per gestire la spedizione con ID XYZ"
}
```

{% endtab %}

{% tab title="404" %}
There are no associated references to delete for the requested shipment. This code is also returned if the requested shipment does not exist

```json
{
    "error": "Non sono presenti riferimenti associati alla spedizione"
}
```

{% endtab %}
{% endtabs %}