> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggiorna spedizione

> Modifica i dettagli della spedizione prima del ritiro

Aggiorna i dettagli della spedizione come la pianificazione del ritiro, il numero di pacchi o le note. Se cambiano campi rilevanti per la logistica (data di ritiro, orario, numero di pacchi o peso), l'ordine logistico esistente viene annullato e ne viene creato automaticamente uno nuovo. I campi omessi vengono mantenuti dalla spedizione esistente. I campi di pianificazione aggiornati vengono convalidati in base alle [regole di pianificazione del ritiro](https://docs.anivahealth.com/it/concepts/shipments.md#regole-per-la-programmazione-del-ritiro).

> [!WARNING]
>
> Le spedizioni non possono essere modificate dopo il ritiro. Il tentativo di aggiornare una spedizione già
> ritirata restituisce `409 Conflict`.

Un pacco con kit domiciliare ha già l'etichetta stampata, quindi è possibile modificare solo `notes`. Una nuova fascia di ritiro
o un nuovo peso su un pacco con kit domiciliare restituisce `409 Conflict`; annullalo e crea invece una nuova spedizione.

Per aggiornare un pacco con kit domiciliare, ogni ordine di kit domiciliare collegato deve rientrare nel tuo contesto di accesso.
In caso contrario la chiamata restituisce `403`. Vedi [Accesso](https://docs.anivahealth.com/it/concepts/shipments.md#accesso).

## Richiesta

### Parametri di percorso

**id** `string` *required*

ID di riferimento della spedizione (ad es. `P2611194821`).

### Parametri del body

Tutti i parametri del body sono facoltativi — includi solo i campi che vuoi modificare.

**pickup\_date** `string`

Nuova data di ritiro in formato `YYYY-MM-DD`, interpretata nel fuso orario della località di origine.

**pickup\_time\_from** `string`

Nuovo orario minimo di ritiro in formato `HH:MM`, interpretato come ora locale nel fuso orario
della località di origine.

**pickup\_time\_till** `string`

Nuovo orario massimo di ritiro in formato `HH:MM`, interpretato come ora locale nel fuso orario
della località di origine.

**package\_count** `integer`

Nuovo numero di pacchi.

**weight** `number`

Nuovo peso in kg.

**notes** `string`

Nuove note o osservazioni. Massimo 128 caratteri.

## Risposta

In caso di successo, l'API restituisce `200 OK` con la spedizione aggiornata.

**id** `string` *required*

Identificativo di riferimento della spedizione.

**status** `string` *required*

Stato del ciclo di vita della spedizione. Uno tra `pending`, `in_transit`, `delivered`, `fault` o `cancelled`.

**logistics\_provider** `string` *required*

Fornitore logistico. Uno tra `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` o `dhl_express`. Un pacco con kit a domicilio è `dhl_parcel`, oppure `dhl_warenpost` quando viene spedito all'estero
come Warenpost International.

**tracking\_number** `string`

Numero di tracciamento esterno del fornitore logistico. Può essere `null`.

**contents** `string`

Descrizione in testo libero del contenuto del pacco, come fornita alla creazione. Può essere `null`.

**booked\_by** `string` *required*

Chi ha stampato l'etichetta: `aniva` o `external`. Solo le spedizioni `aniva` accettano questa chiamata.

**paired\_with** `string`

Riferimento dell'altro pacco in una spedizione a due pacchi. `null` per un pacco di sola andata.

**origin** `object`

Indirizzo di ritiro. Può essere `null`.

**oggetto indirizzo**

**name** `string` *required*

Nome del destinatario, dell'azienda o della sede.

**company\_name** `string`

Riga azienda / c/o. Può essere `null`.

**street** `string` *required*

Nome della via, senza il numero civico.

**house\_number** `string`

Numero civico. Può essere `null`.

**address\_line\_2** `string`

Edificio, ingresso o piano. Può essere `null`.

**city** `string` *required*

Città.

**state** `string`

Stato o provincia. Può essere `null`.

**postal\_code** `string` *required*

CAP / codice postale.

**country\_code** `string` *required*

Codice paese ISO 3166-1 alpha-2.

**phone** `string`

Numero di telefono di contatto. Può essere `null`.

**email** `string`

Email di contatto. Può essere `null`.

**destination** `object`

Indirizzo di consegna. Stessa struttura di `origin`. Può essere `null`.

**pickup** `object`

Fascia di ritiro programmata. Può essere `null`.

**oggetto pickup**

**from** `string` *required*

Inizio della fascia di ritiro come istante UTC (ISO 8601 con suffisso `Z`).

**till** `string` *required*

Fine della fascia di ritiro come istante UTC (ISO 8601 con suffisso `Z`).

**timezone** `string` *required*

Fuso orario IANA del luogo di ritiro (es. `Europe/Berlin`). Usalo per mostrare `from` / `till` nell'ora locale del luogo di ritiro.

**notes** `string`

Note facoltative. Può essere `null`.

**status\_updates** `object[]` *required*

Eventi cronologici del ciclo di vita dal fornitore logistico (dal più vecchio al più recente). Ogni voce contiene
`state`, `code`, `detail_code`, `status`, `description`, `location` e `time`. Consulta [Ottieni
spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) per ogni campo. Array vuoto se non sono ancora stati rilevati eventi.

**appointments** `ShipmentAppointmentLink[]` *required*

Appuntamenti collegati a questa spedizione, dal collegamento più vecchio. Ogni voce è `{ id, added_at }`;
confronta ogni `id` con [Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md).
Vengono elencati solo gli appuntamenti nel tuo contesto di accesso.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Ordini di kit a domicilio collegati a questa spedizione, dal collegamento più vecchio al più recente, nello stesso formato `{ id, added_at }`.
Sono elencati solo gli ordini nel tuo contesto di accesso. Array vuoto per i pacchi degli studi medici.

**synced\_at** `string`

Quando la spedizione è stata sincronizzata per l'ultima volta con il corriere, come istante UTC. `null` fino alla prima
sincronizzazione.

**created\_at** `string` *required*

Timestamp di creazione (ISO 8601).

**updated\_at** `string`

Timestamp dell'ultimo aggiornamento (ISO 8601). Può essere `null`.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — ad es., formato di data o ora non valido. |
| `403` | Vietato — la tua chiave API non ha accesso a questa operazione, la spedizione è fuori dal tuo contesto di accesso oppure un ordine home-kit collegato è fuori dal tuo contesto di accesso. |
| `404` | Spedizione non trovata. |
| `409` | La spedizione non può essere modificata dopo il ritiro, oppure è un pacco home-kit la cui etichetta è già stampata e la richiesta modifica più di `notes`. |
| `501` | La spedizione è `external` — non è stata prenotata tramite Aniva e non può essere modificata qui. |
| `500` | Errore interno del server. |
| `502` | Il fornitore logistico ha rifiutato la richiesta (ad es., annullamento o ricreazione non riusciti). Include il messaggio di errore del fornitore. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickup_date": "2026-04-16",
    "pickup_time_from": "10:00",
    "pickup_time_till": "13:00"
  }'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": "Medizinisch freigestellte Probe",
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-16T08:00:00Z",
    "till": "2026-04-16T11:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": null,
  "status_updates": [],
  "appointments": [],
  "home_kit_orders": [],
  "synced_at": "2026-04-03T15:00:00Z",
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": "2026-04-03T15:10:00Z"
}
```

```json 409 theme={null}
{
  "error": "Shipment cannot be modified after pickup"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: The cancellation notice period has already been exceeded. Cancellation is no longer possible via the web service. Please contact the GO! station.",
  "logistics_error_code": 4006
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.