# 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 %}