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.

POST 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*

int

ID of the held shipment to act on

Headers

Name

Type

Description

x-api-key*

string

API key provided by Gsped

Content-Type*

string

application/json

Request body

Name

Type

Description

action*

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.

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

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

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

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

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

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

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

Example code snippets

<?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;
}

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"))

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))
}

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);
}

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"
    }
  }'

PreviousStocks

NextCOD (cash on delivery)

Last updated 22 days ago