# Shipment References

Questo endpoint permette di gestire riferimenti multipli per una spedizione.

## ShipmentReferences - GET

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

Recupera i riferimenti associati per la spedizione richiesta

### URL Parameters

| Name           | Type    | Description                       |
| -------------- | ------- | --------------------------------- |
| ISTANZA        | String  | Nome dell'istanza di riferimento  |
| ID\_SPEDIZIONE | Integer | ID univoco Gsped della spedizione |

### **Headers**

| Name      | Type   |                         |
| --------- | ------ | ----------------------- |
| x-api-key | String | Apikey fornita da Gsped |

**Response**

{% tabs %}
{% tab title="200" %}
Riferimenti recuperati con successo

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

{% endtab %}

{% tab title="400" %}
Richiesta mal formata

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

{% endtab %}

{% tab title="403" %}
Non si hanno i permessi necessari per gestire la spedizione richiesta

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

{% endtab %}

{% tab title="404" %}
Non ci sono riferimenti associati per la spedizione richiesta. Questo codice si ottine anche nel caso la spedizione richiesta non esiste

```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/\\[ISTANZA]/ShipmentReferences>

Questo endpoint permette di associare uno o più riferimenti alla spedizione.

**IMPORTANTE :**&#x20;

Questo endpoint può essere richiamato più volte sulla stessa spedizione per aggiungere i riferimenti man mano che vi è necessità di farlo.&#x20;

{% hint style="danger" %}
**Al momento il limite massimo di riferimenti che possono essere associati a una spedizione è 20.**
{% endhint %}

### **Headers**

| Name      | Value    |                         |
| --------- | -------- | ----------------------- |
| x-api-key | `String` | Apikey fornita da Gsped |

### **Body**

| Name         | Type    | Description                                                                                                  |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| idSpedizione | Integer | ID univoco Gsped della spedizione                                                                            |
| references   | array   | <p>Array contenente i riferimenti da associare alla spedizione.<br><strong>Massimo 20 elementi!</strong></p> |

### Esempio

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

**Response**

{% tabs %}
{% tab title="200" %}
Rifimento/i inseriti con successo

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

{% endtab %}

{% tab title="400" %}
Richiesta mal formata oppure nella richiesta si supera il numero di riferimenti ammessi associati alla spedizione.

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

{% endtab %}

{% tab title="403" %}
Non si hanno i permessi necessari per gestire la spedizione richiesta

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

{% endtab %}

{% tab title="404" %}
La spedizione a cui associare i riferimenti non esiste

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

{% endtab %}
{% endtabs %}

## ShipmentReferences - DELETE

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

Questo endpoint permette di disassociare tutti i riferimenti di una spedizione o togliere un singolo riferimento

### URL Parameters

| Name           | Type    | Description                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ISTANZA        | String  | INome dell'istanza di riferimento                                                                                                                                                                                                                                                                                                                          |
| ID\_SPEDIZIONE | integer | ID univoco Gsped della spedizione                                                                                                                                                                                                                                                                                                                          |
| REFERENCE      | string  | <p><strong>Parametro Opzionale.</strong><br><br>Se valorizzato, indica il riferimento da disassociare dalla spedizione.<br><br><strong>NB:</strong> Nel caso in cui non venga indicato, verranno disassociati <strong>tutti i riferimenti</strong><br><br><strong>NB2:</strong> Eventuali caratteri speciali devono essere <strong>urlencoded</strong></p> |

### Headers

| Name      | Type   | Description             |
| --------- | ------ | ----------------------- |
| x-api-key | string | Apikey fornita da Gsped |

**Response**

{% tabs %}
{% tab title="200" %}
Riferimento disassociato con successo

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

{% endtab %}

{% tab title="400" %}
Richiesta mal formata

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

{% endtab %}

{% tab title="403" %}
Non si hanno i permessi necessari per gestire la spedizione richiesta

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

{% endtab %}

{% tab title="404" %}
Non ci sono riferimenti associati da cancellare per la spedizione richiesta. Questo codice si ottine anche nel caso la spedizione richiesta non esiste

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.gsped.com/spedizioni-e-dintorni/shipment-references.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.