> 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/spedizioni-e-dintorni/stocks/stocks-invio-disposizioni.md).

# Stocks - Invio disposizioni

Invio disposizioni di svincolo su una giacenza

### Stocks/{id}/instructions

Questo endpoint permette di inviare al corriere le disposizioni di svincolo per una giacenza (riconsegna, restituzione al mittente, ecc.), operazione precedentemente disponibile solo tramite interfaccia web.

<mark style="color:green;">`POST`</mark> `https://api.gsped.it/[ISTANZA]/Stocks/{id}/instructions`

Le disposizioni disponibili dipendono dal corriere della giacenza. Non tutti i corrieri supportano tutte le azioni, e alcuni (es. UPS) non prevedono affatto lo svincolo tramite questo canale. Vedi la tabella Azioni supportate per corriere.

**Path parameters**

| Name                                 | Type | Description                      |
| ------------------------------------ | ---- | -------------------------------- |
| id<mark style="color:red;">\*</mark> | int  | ID della giacenza su cui operare |

**Headers**

| Name                                           | Type   | Description              |
| ---------------------------------------------- | ------ | ------------------------ |
| x-api-key<mark style="color:red;">\*</mark>    | string | API key fornita da Gsped |
| Content-Type<mark style="color:red;">\*</mark> | string | `application/json`       |

**Request body**

| Name                                     | Type   | Description                                                                          |
| ---------------------------------------- | ------ | ------------------------------------------------------------------------------------ |
| action<mark style="color:red;">\*</mark> | string | Disposizione da applicare. Vedi Azioni disponibili.                                  |
| notes                                    | string | Note libere per il corriere (max 65 caratteri, troncate se più lunghe)               |
| scheduled\_date                          | string | Data di riconsegna richiesta, formato `YYYY-MM-DD` (dove supportata dal corriere)    |
| new\_address                             | object | Nuovo indirizzo di consegna. **Obbligatorio** quando `action` è `retry_new_address`. |
| options                                  | object | Opzioni aggiuntive (solo corrieri "detailed": BRT, GLS, FedEx, DHL). Vedi Opzioni.   |

**Oggetto `new_address`**

| Name         | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| name         | string | Nome destinatario (max 30)         |
| address      | string | Indirizzo (max 35)                 |
| city         | string | Città (max 40)                     |
| province     | string | Provincia, sigla (max 2)           |
| postal\_code | string | CAP (max 5)                        |
| phone        | string | Telefono (max 20, dove supportato) |

**Oggetto `options`**

Disponibili solo per i corrieri "detailed" (BRT, GLS, FedEx, DHL); ignorate dagli altri.

| Name                       | Type    | Description                               |
| -------------------------- | ------- | ----------------------------------------- |
| phone\_prenotification     | bool    | Riconsegna con preavviso telefonico       |
| cancel\_cash\_on\_delivery | bool    | Annulla il contrassegno                   |
| change\_cod\_amount        | decimal | Nuovo importo del contrassegno            |
| change\_shipping\_terms    | string  | Modalità di porto: `franco` o `assegnato` |
| charge\_to\_sender         | bool    | Spese a carico del mittente               |
| charge\_to\_recipient      | bool    | Spese a carico del destinatario           |

**Azioni disponibili**

| Azione                    | Descrizione                                              |
| ------------------------- | -------------------------------------------------------- |
| `retry_same_address`      | Riconsegnare allo stesso indirizzo                       |
| `retry_new_address`       | Consegnare a un nuovo indirizzo (richiede `new_address`) |
| `return_to_sender`        | Restituire al mittente                                   |
| `hold_at_depot`           | Trattenere in fermo deposito presso la filiale           |
| `destroy`                 | Distruggere la merce                                     |
| `deliver_with_reserve`    | Consegnare accettando riserva specifica                  |
| `deliver_without_reserve` | Consegnare senza apporre riserva                         |
| `recipient_pickup`        | Il destinatario ritira la merce in sede                  |

**Azioni supportate per corriere**

| Azione                    | TNT / SDA / CTCourier | BRT / GLS / FedEx / DHL | SGT |
| ------------------------- | :-------------------: | :---------------------: | :-: |
| `retry_same_address`      |           ✓           |            ✓            |  ✓  |
| `retry_new_address`       |           ✓           |            ✓            |  ✓  |
| `return_to_sender`        |           ✓           |            ✓            |  ✓  |
| `hold_at_depot`           |           ✓           |                         |     |
| `destroy`                 |                       |            ✓            |     |
| `deliver_with_reserve`    |                       |            ✓            |     |
| `deliver_without_reserve` |                       |            ✓            |     |
| `recipient_pickup`        |                       |            ✓            |     |

Le `options` sono disponibili solo per la colonna BRT / GLS / FedEx / DHL. UPS non è supportato.

{% tabs %}
{% tab title="200: OK Disposizioni inviate" %}

```javascript
{
    "status": 200,
    "response": {
        "id_giacenza": 2,
        "action": "retry_same_address",
        "status": "sent"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Errore input" %}

```javascript
{
  "status": 400,
  "errors": [
    "id_giacenza obbligatorio"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="403: Forbidden Accesso negato" %}

```javascript
{
  "status": 403,
  "errors": [
    "Accesso negato"
  ],
  "response": []
}
```

{% endtab %}

{% tab title="404: Not Found Giacenza inesistente" %}

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

{% endtab %}

{% tab title="422: Unprocessable Azione non valida" %}

```javascript
{
  "status": 422,
  "errors": [
    "Azione 'destroy' non supportata per il corriere 132."
  ],
  "response": []
}
```

{% endtab %}

{% tab title="501: Not Implemented Corriere non supportato" %}

```javascript
{
  "status": 501,
  "errors": [
    "Il corriere UPS non prevede lo svincolo delle giacenze."
  ],
  "response": []
}
```

{% endtab %}

{% tab title="502: Bad Gateway Rifiuto corriere" %}

```javascript
{
  "status": 502,
  "errors": [
    "Invio disposizioni non riuscito."
  ],
  "response": []
}
```

{% endtab %}
{% endtabs %}

#### Snippets codice di esempio

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

```php
<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gsped.it/sandbox/Stocks/2/instructions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "action" => "retry_new_address",
    "notes"  => "Citofono Rossi",
    "new_address" => [
      "name"        => "Mario Rossi",
      "address"     => "Via Roma 1",
      "city"        => "Milano",
      "province"    => "MI",
      "postal_code" => "20100",
      "phone"       => "021234567",
    ],
  ]),
  CURLOPT_HTTPHEADER => [
    "x-api-key: YOUR-API-KEY",
    "Content-Type: application/json",
  ],
]);
$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
import json

conn = http.client.HTTPSConnection("api.gsped.it")
payload = json.dumps({
    "action": "retry_new_address",
    "notes": "Citofono Rossi",
    "new_address": {
        "name": "Mario Rossi",
        "address": "Via Roma 1",
        "city": "Milano",
        "province": "MI",
        "postal_code": "20100",
        "phone": "021234567",
    },
})
headers = {
    'x-api-key': "YOUR-API-KEY",
    'Content-Type': "application/json",
}
conn.request("POST", "/sandbox/Stocks/2/instructions", 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/Stocks/2/instructions"
  payload := strings.NewReader(`{
    "action": "retry_new_address",
    "notes": "Citofono Rossi",
    "new_address": {
      "name": "Mario Rossi",
      "address": "Via Roma 1",
      "city": "Milano",
      "province": "MI",
      "postal_code": "20100",
      "phone": "021234567"
    }
  }`)
  req, _ := http.NewRequest("POST", url, payload)
  req.Header.Add("x-api-key", "YOUR-API-KEY")
  req.Header.Add("Content-Type", "application/json")
  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/Stocks/2/instructions"),
    Headers =
    {
        { "x-api-key", "YOUR-API-KEY" },
    },
    Content = new StringContent(
        "{\"action\":\"retry_new_address\",\"notes\":\"Citofono Rossi\",\"new_address\":{\"name\":\"Mario Rossi\",\"address\":\"Via Roma 1\",\"city\":\"Milano\",\"province\":\"MI\",\"postal_code\":\"20100\",\"phone\":\"021234567\"}}",
        System.Text.Encoding.UTF8,
        "application/json"
    ),
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --request POST \
  --url 'https://api.gsped.it/sandbox/Stocks/2/instructions' \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "retry_new_address",
    "notes": "Citofono Rossi",
    "new_address": {
      "name": "Mario Rossi",
      "address": "Via Roma 1",
      "city": "Milano",
      "province": "MI",
      "postal_code": "20100",
      "phone": "021234567"
    }
  }'
```

{% endtab %}
{% endtabs %}