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

# Stocks - Send instructions

Send release instructions for a held shipment

### Stocks/{id}/instructions

This endpoint lets you send the courier the release instructions for a held shipment (redelivery, return to sender, etc.), an operation previously available only through the web interface.

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

The available instructions depend on the courier of the held shipment. Not all couriers support all actions, and some (e.g. UPS) do not allow release through this channel at all. See the Actions supported by courier table.

**Path parameters**

| Name                                 | Type | Description                       |
| ------------------------------------ | ---- | --------------------------------- |
| id<mark style="color:red;">\*</mark> | int  | ID of the held shipment to act on |

**Headers**

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

**Request body**

| Name                                     | Type   | Description                                                                       |
| ---------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| action<mark style="color:red;">\*</mark> | string | Instruction to apply. See Available actions.                                      |
| notes                                    | string | Free-text notes for the courier (max 65 characters, truncated if longer)          |
| scheduled\_date                          | string | Requested redelivery date, format `YYYY-MM-DD` (where supported by the courier)   |
| new\_address                             | object | New delivery address. **Required** when `action` is `retry_new_address`.          |
| options                                  | object | Additional options ("detailed" couriers only: BRT, GLS, FedEx, DHL). See Options. |

**`new_address` object**

| Name         | Type   | Description                     |
| ------------ | ------ | ------------------------------- |
| name         | string | Recipient name (max 30)         |
| address      | string | Address (max 35)                |
| city         | string | City (max 40)                   |
| province     | string | Province, abbreviation (max 2)  |
| postal\_code | string | Postcode (max 5)                |
| phone        | string | Phone (max 20, where supported) |

**`options` object**

Available only for "detailed" couriers (BRT, GLS, FedEx, DHL); ignored by the others.

| Name                       | Type    | Description                             |
| -------------------------- | ------- | --------------------------------------- |
| phone\_prenotification     | bool    | Redelivery with phone notice            |
| cancel\_cash\_on\_delivery | bool    | Cancel the cash on delivery (COD)       |
| change\_cod\_amount        | decimal | New cash on delivery (COD) amount       |
| change\_shipping\_terms    | string  | Shipping terms: `franco` or `assegnato` |
| charge\_to\_sender         | bool    | Costs charged to the sender             |
| charge\_to\_recipient      | bool    | Costs charged to the recipient          |

**Available actions**

| Action                    | Description                                       |
| ------------------------- | ------------------------------------------------- |
| `retry_same_address`      | Redeliver to the same address                     |
| `retry_new_address`       | Deliver to a new address (requires `new_address`) |
| `return_to_sender`        | Return to sender                                  |
| `hold_at_depot`           | Keep on hold at depot at the branch               |
| `destroy`                 | Destroy the goods                                 |
| `deliver_with_reserve`    | Deliver accepting a specific reservation          |
| `deliver_without_reserve` | Deliver without adding a reservation              |
| `recipient_pickup`        | The recipient collects the goods at the branch    |

**Actions supported by courier**

| Action                    | 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`        |                       |            ✓            |     |

The `options` are available only for the BRT / GLS / FedEx / DHL column. UPS is not supported.

{% tabs %}
{% tab title="200: OK Instructions sent" %}

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

{% endtab %}

{% tab title="400: Bad Request Input error" %}

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

{% endtab %}

{% tab title="403: Forbidden Access denied" %}

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

{% endtab %}

{% tab title="404: Not Found Held shipment does not exist" %}

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

{% endtab %}

{% tab title="422: Unprocessable Invalid action" %}

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

{% endtab %}

{% tab title="501: Not Implemented Courier not supported" %}

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

{% endtab %}

{% tab title="502: Bad Gateway Rejected by the courier" %}

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

{% endtab %}
{% endtabs %}

#### Example code snippets

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