> ## 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.

# Annulla spedizione

> Annulla un ordine di spedizione

Annulla un ordine di spedizione. Chiama l'API del fornitore logistico per annullare l'ordine e aggiorna lo stato della spedizione a `cancelled`.

Annullare una spedizione già in stato `cancelled` restituisce `200` con quella spedizione e il fornitore viene chiamato una sola volta. La risposta include `Idempotent-Replayed: true` così puoi distinguere una ripetizione dalla chiamata che ha eseguito l'operazione. Vedi [Idempotenza](https://docs.anivahealth.com/it/concepts/idempotency.md).

> [!WARNING]
>
> Le spedizioni non possono essere annullate dopo il ritiro — in quel caso viene restituito `409 Conflict`.

Un'etichetta di reso DHL non può essere annullata da sola; anche in questo caso viene restituito `409 Conflict`. Annulla invece
il pacco di andata. Annullare un pacco DHL di andata annulla anche le relative righe di ritorno
`pending`. Ciascuna diventa `cancelled` con una voce `RETURN_LEG_CANCELLED` in `status_updates`. Vedi
[Etichette di reso](https://docs.anivahealth.com/it/concepts/shipments.md#etichette-di-reso).

In una scatola con più kit, ogni kit ha la propria riga di andata e la propria etichetta di reso, anche
quando la scatola viaggia con l'etichetta di un solo kit. Annullare la riga di andata di un kit annulla anche l'etichetta
di reso di quel kit.

Per annullare un pacco con kit a domicilio, ogni ordine di kit a domicilio 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`).

## Risposta

In caso di successo, l'API restituisce `200 OK` con l'oggetto della spedizione annullata.

**id** `string` *required*

Identificativo di riferimento della spedizione.

**status** `string` *required*

Stato del ciclo di vita della spedizione. Sarà `cancelled` dopo un annullamento riuscito.

**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`).

**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 prima dell'annullamento. Ogni voce è
`{ id, added_at }`; confronta ogni `id` con
[Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md).
Sono 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` | Formato ID non valido. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione, la spedizione è fuori dal tuo contesto di accesso o un ordine di kit a domicilio collegato è fuori dal tuo contesto di accesso. |
| `404` | Spedizione non trovata. |
| `409` | Impossibile annullare la spedizione — è già stata ritirata o consegnata, oppure è un'etichetta di reso DHL (annulla invece il pacco di andata). |
| `501` | La spedizione è `external` — non è stata prenotata tramite Aniva e non può essere annullata qui. |
| `500` | Errore interno del server. |
| `502` | Il fornitore logistico ha rifiutato la richiesta (es. termine per l'annullamento superato). Include il messaggio di errore del fornitore. |

```bash cURL theme={null}
curl --request DELETE \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "cancelled",
  "logistics_provider": "go",
  "tracking_number": "GO1234567890",
  "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-15T07:00:00Z",
    "till": "2026-04-15T10: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-03T16:45:00Z"
}
```

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

```json 409 (return label) theme={null}
{
  "error": "Shipment K260904P3XD is the return label of K2609041FQ7. DHL cannot cancel a return label on its own. Cancel the outbound parcel while it is pending. After the outbound parcel ships, the label stays valid and Aniva closes this shipment manually."
}
```

```json 403 (Aniva-managed parcel) theme={null}
{
  "error": "Access denied: only Aniva can change this parcel."
}
```

```json 404 theme={null}
{
  "error": "Shipment not found"
}
```

```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.