> 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/pickup-richieste-di-ritiro.md).

# Pickup (pickup requests)

Pickup management

## Pickup - GET

Returns information about the status of a pickup request.

## Retrieve pickup information.

<mark style="color:blue;">`GET`</mark> `https://api.gsped.it/[INSTANCE]/pickup`

#### Query Parameters

| Name                                 | Type    | Description |
| ------------------------------------ | ------- | ----------- |
| id<mark style="color:red;">\*</mark> | Integer | Pickup ID   |

#### Headers

| Name                                        | Type   | Description               |
| ------------------------------------------- | ------ | ------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | String | Api Key provided by Gsped |

{% tabs %}
{% tab title="200: OK Operation completed successfully" %}

```javascript
{
    "status": 2,
    "num_spedizione": "",
    "error": "",
    "id": 70058437,
    "note": "",
    "note_orm": "",
    "num_orm": "CBJ180121002626"
}
```

{% endtab %}

{% tab title="400: Bad Request Malformed request" %}

```javascript
{
    "error": "ID richiesta di ritiro non indicato"
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid Api Key" %}

```javascript
{
    "status": false,
    "error": "Invalid API key "
}
```

{% endtab %}

{% tab title="404: Not Found Shipment not found" %}

```javascript
{
    "error": "Richiesta di ritiro non trovata"
}
```

{% endtab %}
{% endtabs %}

### **Example code snippets**

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.gsped.it/sandbox/pickup?id=12345',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'x-api-key: YOUR-API-KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}

{% tab title="Python" %}

```python
import http.client

conn = http.client.HTTPSConnection("api.gsped.it")
payload = ''
headers = {
  'x-api-key': 'YOUR-API-KEY'
}
conn.request("GET", "/sandbox/pickup?id=12345", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
```

{% endtab %}

{% tab title="GO" %}

```go
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.gsped.it/sandbox/pickup?id=12345"
  method := "GET"

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("x-api-key", "YOUR-API-KEY")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new RestClient("https://api.gsped.it/sandbox/pickup?id=12345");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "YOUR-API-KEY");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location --request GET 'https://api.gsped.it/sandbox/pickup?id=12345' \
--header 'x-api-key: YOUR-API-KEY'
```

{% endtab %}
{% endtabs %}

## Pickup - POST

Sends a pickup request to the courier.

{% hint style="info" %}
**Warning:**

Unless there are errors in the field names and/or wrong data, this endpoint always responds with status code **200,** even when the pickup request was not successful.

Always check the **status** field in the pickup response.

If the value of this field is **0.6** or **10**, the pickup was not booked (in most cases because of times and dates not accepted by the courier since they cannot be handled operationally).

Finally, bear in mind that not all couriers immediately provide the information on whether the requested pickup is feasible: check with the Gsped technicians for the couriers you want to use this endpoint with.
{% endhint %}

{% hint style="warning" %}
Some couriers (for example DHL) also require the recipient data (`rcpt_*` fields): if they are missing, the call responds **400** indicating the field required for that courier, for example `rcpt_name: valore obbligatorio per questo corriere`.
{% endhint %}

## Send a pickup request

<mark style="color:green;">`POST`</mark> `https://api.gsped.it/[INSTANCE]/pickup`

#### Headers

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

#### Request Body

| Name                                                | Type    | Description                                                                                                                                        |
| --------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| client\_id<mark style="color:red;">\*</mark>        | Integer | ID of the client account with which you want to generate the shipment (value provided)                                                             |
| invoiced\_client\_id                                | Integer | <p>TO BE SET ONLY FOR RESELLER INSTANCES (required)<br>Use it to specify which of the reseller's clients the pickup should be associated with.</p> |
| corriere<mark style="color:red;">\*</mark>          | Integer | Courier code                                                                                                                                       |
| servizio<mark style="color:red;">\*</mark>          | Integer | Service code                                                                                                                                       |
| colli<mark style="color:red;">\*</mark>             | Integer | Number of parcels the shipment will consist of                                                                                                     |
| peso<mark style="color:red;">\*</mark>              | Float   | Total weight in KG                                                                                                                                 |
| <p>volume<mark style="color:red;">\*</mark><br></p> | Float   | Shipment volume in cubic metres                                                                                                                    |
| date\_req\_ritiro<mark style="color:red;">\*</mark> | String  | Pickup date (YYYY-MM-DD)                                                                                                                           |
| opening\_time<mark style="color:red;">\*</mark>     | String  | Time the goods are ready (HH:MM:SS)                                                                                                                |
| closing\_time<mark style="color:red;">\*</mark>     | String  | Closing time (HH:MM:SS)                                                                                                                            |
| opening\_time2                                      | String  | Second time the goods are ready (HH:MM:SS) - *TNT courier only*                                                                                    |
| closing\_time2                                      | String  | Second closing time (HH:MM:SS) - *TNT courier only*                                                                                                |
| ddt\_alpha                                          | String  | Client alphanumeric reference                                                                                                                      |
| ddt\_num                                            | Integer | Client numeric reference                                                                                                                           |
| sender\_name                                        | String  | Sender name/company name                                                                                                                           |
| sender\_addr                                        | String  | Sender address (street + house number)                                                                                                             |
| sender\_cap                                         | String  | Sender postcode                                                                                                                                    |
| sender\_city                                        | String  | Sender town/city                                                                                                                                   |
| sender\_contact                                     | String  | Contact person at the sender                                                                                                                       |
| sender\_email                                       | String  | Sender email                                                                                                                                       |
| sender\_prov                                        | String  | Sender province (2-character code)                                                                                                                 |
| sender\_country\_code                               | String  | Sender country (ISO 3166-1 alpha-2 code)                                                                                                           |
| sender\_phone                                       | String  | Sender phone                                                                                                                                       |
| rcpt\_name                                          | String  | Recipient name/company name                                                                                                                        |
| note\_sender                                        | String  | Sender notes                                                                                                                                       |
| rcpt\_addr                                          | String  | Recipient address (street + house number)                                                                                                          |
| rcpt\_cap                                           | String  | Recipient postcode                                                                                                                                 |
| rcpt\_city                                          | String  | Recipient town/city                                                                                                                                |
| rcpt\_prov                                          | String  | Recipient province (2-character code)                                                                                                              |
| rcpt\_country\_code                                 | String  | Recipient country (ISO 3166-1 alpha- 2 code)                                                                                                       |
| rcpt\_contact                                       | String  | Contact person at the recipient                                                                                                                    |
| rcpt\_phone                                         | String  | Recipient phone                                                                                                                                    |
| rcpt\_email                                         | String  | Recipient email                                                                                                                                    |
| merce                                               | String  | Description of the goods                                                                                                                           |
| daticolli                                           | Array   | Parcel dimension details (if available):                                                                                                           |
| daticolli.n\_collo                                  | Integer | Sequential number                                                                                                                                  |
| daticolli.altezza                                   | Integer | Height in CM                                                                                                                                       |
| daticolli.larghezza                                 | Integer | Width in CM                                                                                                                                        |
| daticolli.lunghezza                                 | Integer | Length in CM                                                                                                                                       |
| daticolli.peso                                      | Float   | Weight in KG                                                                                                                                       |
| daticolli.volume                                    | Float   | Volume in cubic metres                                                                                                                             |

{% tabs %}
{% tab title="200: OK Request completed successfully" %}

```javascript
{
    "status": 2,
    "num_spedizione": "",
    "error": "",
    "id": 70061546,
    "note": "",
    "note_orm": "",
    "num_orm": "CBJ180121002626"
}
```

{% endtab %}

{% tab title="400: Bad Request Malformed data" %}

```javascript
{
    "error": "client_id: valore non valido"
}
```

{% endtab %}
{% endtabs %}

### **Example code snippets**

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

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.gsped.it/sandbox/pickup',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "client_id": 390,
  "corriere": 1,
  "servizio": 0,
  "colli": 1,
  "peso": 5,
  "date_req_ritiro": "2022-01-14",
  "opening_time": "09:00",
  "closing_time": "17:30",
  "ddt_alpha": "2001504697",
  "ddt_num": 2001504697,
  "sender_name": "Test mittente",
  "sender_addr": "VIA PRINCIPESSA CLOTILDE, 70",
  "sender_cap": "10134",
  "sender_city": "Torino",
  "sender_contact": "contatto mittente",
  "sender_prov": "TO",
  "sender_country_code": "IT",
  "sender_email": "test@gsped.com",
  "sender_phone": "3208281234",
  "note_sender": "",
  "rcpt_addr": "Via Pier Santi Mattarella, 1",
  "rcpt_cap": "92100",
  "rcpt_city": "AGRIGENTO",
  "rcpt_contact": "contatto destinatario",
  "rcpt_country_code": "IT",
  "rcpt_email": "test@gsped.com",
  "rcpt_name": "test destinatario",
  "rcpt_phone": "0922601234",
  "rcpt_prov": "AG",
  "merce": "Articoli arredamento",
  "daticolli": [
    {
      "n_collo": 1,
      "altezza": 50,
      "larghezza": 35,
      "lunghezza": 25,
      "peso": 10,
      "volume": 0.014
    }
  ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'x-api-key: YOUR-API-KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="PYTHON" %}

```python
import http.client
import json

conn = http.client.HTTPSConnection("api.gsped.it")
payload = json.dumps({
  "client_id": 390,
  "corriere": 1,
  "servizio": 0,
  "colli": 1,
  "peso": 5,
  "date_req_ritiro": "2022-01-14",
  "opening_time": "09:00",
  "closing_time": "17:30",
  "ddt_alpha": "2001504697",
  "ddt_num": 2001504697,
  "sender_name": "Test mittente",
  "sender_addr": "VIA PRINCIPESSA CLOTILDE, 70",
  "sender_cap": "10134",
  "sender_city": "Torino",
  "sender_contact": "contatto mittente",
  "sender_prov": "TO",
  "sender_country_code": "IT",
  "sender_email": "test@gsped.com",
  "sender_phone": "3208281234",
  "note_sender": "",
  "rcpt_addr": "Via Pier Santi Mattarella, 1",
  "rcpt_cap": "92100",
  "rcpt_city": "AGRIGENTO",
  "rcpt_contact": "contatto destinatario",
  "rcpt_country_code": "IT",
  "rcpt_email": "test@gsped.com",
  "rcpt_name": "test destinatario",
  "rcpt_phone": "0922601234",
  "rcpt_prov": "AG",
  "merce": "Articoli arredamento",
  "daticolli": [
    {
      "n_collo": 1,
      "altezza": 50,
      "larghezza": 35,
      "lunghezza": 25,
      "peso": 10,
      "volume": 0.014
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR-API-KEY'
}
conn.request("POST", "/sandbox/pickup", 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/pickup"
  method := "POST"

  payload := strings.NewReader(`{`+"
"+`
  "client_id": 390,`+"
"+`
  "corriere": 1,`+"
"+`
  "servizio": 0,`+"
"+`
  "colli": 1,`+"
"+`
  "peso": 5,`+"
"+`
  "date_req_ritiro": "2022-01-14",`+"
"+`
  "opening_time": "09:00",`+"
"+`
  "closing_time": "17:30",`+"
"+`
  "ddt_alpha": "2001504697",`+"
"+`
  "ddt_num": 2001504697,`+"
"+`
  "sender_name": "Test mittente",`+"
"+`
  "sender_addr": "VIA PRINCIPESSA CLOTILDE, 70",`+"
"+`
  "sender_cap": "10134",`+"
"+`
  "sender_city": "Torino",`+"
"+`
  "sender_contact": "contatto mittente",`+"
"+`
  "sender_prov": "TO",`+"
"+`
  "sender_country_code": "IT",`+"
"+`
  "sender_email": "test@gsped.com",`+"
"+`
  "sender_phone": "3208281234",`+"
"+`
  "note_sender": "",`+"
"+`
  "rcpt_addr": "Via Pier Santi Mattarella, 1",`+"
"+`
  "rcpt_cap": "92100",`+"
"+`
  "rcpt_city": "AGRIGENTO",`+"
"+`
  "rcpt_contact": "contatto destinatario",`+"
"+`
  "rcpt_country_code": "IT",`+"
"+`
  "rcpt_email": "test@gsped.com",`+"
"+`
  "rcpt_name": "test destinatario",`+"
"+`
  "rcpt_phone": "0922601234",`+"
"+`
  "rcpt_prov": "AG",`+"
"+`
  "merce": "Articoli arredamento",`+"
"+`
  "daticolli": [`+"
"+`
    {`+"
"+`
      "n_collo": 1,`+"
"+`
      "altezza": 50,`+"
"+`
      "larghezza": 35,`+"
"+`
      "lunghezza": 25,`+"
"+`
      "peso": 10,`+"
"+`
      "volume": 0.014`+"
"+`
    }`+"
"+`
  ]`+"
"+`
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("x-api-key", "YOUR-API-KEY")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
var client = new RestClient("https://api.gsped.it/sandbox/pickup");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("x-api-key", "YOUR-API-KEY");
var body = @"{
" + "\n" +
@"  ""client_id"": 390,
" + "\n" +
@"  ""corriere"": 1,
" + "\n" +
@"  ""servizio"": 0,
" + "\n" +
@"  ""colli"": 1,
" + "\n" +
@"  ""peso"": 5,
" + "\n" +
@"  ""date_req_ritiro"": ""2022-01-14"",
" + "\n" +
@"  ""opening_time"": ""09:00"",
" + "\n" +
@"  ""closing_time"": ""17:30"",
" + "\n" +
@"  ""ddt_alpha"": ""2001504697"",
" + "\n" +
@"  ""ddt_num"": 2001504697,
" + "\n" +
@"  ""sender_name"": ""Test mittente"",
" + "\n" +
@"  ""sender_addr"": ""VIA PRINCIPESSA CLOTILDE, 70"",
" + "\n" +
@"  ""sender_cap"": ""10134"",
" + "\n" +
@"  ""sender_city"": ""Torino"",
" + "\n" +
@"  ""sender_contact"": ""contatto mittente"",
" + "\n" +
@"  ""sender_prov"": ""TO"",
" + "\n" +
@"  ""sender_country_code"": ""IT"",
" + "\n" +
@"  ""sender_email"": ""test@gsped.com"",
" + "\n" +
@"  ""sender_phone"": ""3208281234"",
" + "\n" +
@"  ""note_sender"": """",
" + "\n" +
@"  ""rcpt_addr"": ""Via Pier Santi Mattarella, 1"",
" + "\n" +
@"  ""rcpt_cap"": ""92100"",
" + "\n" +
@"  ""rcpt_city"": ""AGRIGENTO"",
" + "\n" +
@"  ""rcpt_contact"": ""contatto destinatario"",
" + "\n" +
@"  ""rcpt_country_code"": ""IT"",
" + "\n" +
@"  ""rcpt_email"": ""test@gsped.com"",
" + "\n" +
@"  ""rcpt_name"": ""test destinatario"",
" + "\n" +
@"  ""rcpt_phone"": ""0922601234"",
" + "\n" +
@"  ""rcpt_prov"": ""AG"",
" + "\n" +
@"  ""merce"": ""Articoli arredamento"",
" + "\n" +
@"  ""daticolli"": [
" + "\n" +
@"    {
" + "\n" +
@"      ""n_collo"": 1,
" + "\n" +
@"      ""altezza"": 50,
" + "\n" +
@"      ""larghezza"": 35,
" + "\n" +
@"      ""lunghezza"": 25,
" + "\n" +
@"      ""peso"": 10,
" + "\n" +
@"      ""volume"": 0.014
" + "\n" +
@"    }
" + "\n" +
@"  ]
" + "\n" +
@"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location --request POST 'https://api.gsped.it/sandbox/pickup' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR-API-KEY' \
--data-raw '{
  "client_id": 390,
  "corriere": 1,
  "servizio": 0,
  "colli": 1,
  "peso": 5,
  "date_req_ritiro": "2022-01-14",
  "opening_time": "09:00",
  "closing_time": "17:30",
  "ddt_alpha": "2001504697",
  "ddt_num": 2001504697,
  "sender_name": "Test mittente",
  "sender_addr": "VIA PRINCIPESSA CLOTILDE, 70",
  "sender_cap": "10134",
  "sender_city": "Torino",
  "sender_contact": "contatto mittente",
  "sender_prov": "TO",
  "sender_country_code": "IT",
  "sender_email": "test@gsped.com",
  "sender_phone": "3208281234",
  "note_sender": "",
  "rcpt_addr": "Via Pier Santi Mattarella, 1",
  "rcpt_cap": "92100",
  "rcpt_city": "AGRIGENTO",
  "rcpt_contact": "contatto destinatario",
  "rcpt_country_code": "IT",
  "rcpt_email": "test@gsped.com",
  "rcpt_name": "test destinatario",
  "rcpt_phone": "0922601234",
  "rcpt_prov": "AG",
  "merce": "Articoli arredamento",
  "daticolli": [
    {
      "n_collo": 1,
      "altezza": 50,
      "larghezza": 35,
      "lunghezza": 25,
      "peso": 10,
      "volume": 0.014
    }
  ]
}'
```

{% endtab %}
{% endtabs %}