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

# Spedizioni

> Come funziona la logistica nell'API di Aniva: spedizioni dei campioni al laboratorio e pacchi dei kit domiciliari, con tracciamento e stato.

Una spedizione è un singolo pacco fisico: un ritiro tramite corriere che trasporta campioni di sangue da una sede di test a un laboratorio, il kit diretto a un paziente con kit domiciliare o il campione che quel paziente rispedisce indietro. L'API Shipments ti permette di creare, tracciare, modificare e annullare ordini di spedizione, ed elenca ogni pacco in un unico posto indipendentemente da chi lo ha prenotato.

## Un unico elenco, filtrato

`GET /api/v1/shipments` è l'unica raccolta. Una spedizione è autonoma — ha una relazione molti-a-molti con gli appuntamenti e può appartenere a un ordine di kit domiciliare — quindi non esiste un elenco annidato sotto una risorsa padre. Filtra lo stesso elenco con `?appointment_id=` o `?home_kit_order_id=`, paginalo con `limit` / `offset` e segui l'array inline `shipments` della risorsa padre (`{ id, added_at }` sia negli appuntamenti sia negli ordini di kit domiciliare) verso [Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) quando hai un id.

## Contenuto e chi l'ha prenotata

Ogni spedizione riporta due informazioni non visibili dai suoi indirizzi:

* `contents` — testo libero che descrive cosa contiene il pacco, impostato alla creazione (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) e mostrato al corriere. Solo informativo. La direzione non è un campo: se un pacco è diretto a un laboratorio si deduce da `destination`.
* `booked_by` — chi ha stampato l'etichetta: `aniva` o `external`. Solo le spedizioni `aniva` accettano [Aggiorna](https://docs.anivahealth.com/it/api/shipments/update-shipment.md) e [Annulla](https://docs.anivahealth.com/it/api/shipments/cancel-shipment.md); un pacco `external` è tracciato nello stesso elenco ma restituisce `501` per entrambe.

Un pacco che conteneva un'etichetta di reso e il pacco riportato indietro da quell'etichetta puntano l'uno all'altro tramite `paired_with`.

## Accesso

* Puoi leggere un pacco quando almeno un appuntamento o ordine di kit domiciliare collegato rientra nel tuo contesto di accesso, oppure quando è partito da una sede nel tuo contesto di accesso.
* `appointments` e `home_kit_orders` elencano solo gli appuntamenti e gli ordini nel tuo contesto di accesso.
* [Aggiorna](https://docs.anivahealth.com/it/api/shipments/update-shipment.md), [Annulla](https://docs.anivahealth.com/it/api/shipments/cancel-shipment.md), [Associa appuntamenti](https://docs.anivahealth.com/it/api/shipments/attach-appointments-to-shipment.md) e [Dissocia appuntamenti](https://docs.anivahealth.com/it/api/shipments/detach-appointments-from-shipment.md) richiedono che ogni ordine di kit domiciliare collegato sia nel tuo contesto di accesso. Altrimenti la chiamata restituisce `403` e solo Aniva può modificare il pacco.

## Le letture non chiamano mai il corriere

Ogni lettura viene servita dal nostro database. Una sincronizzazione in background allinea ogni spedizione con il relativo corriere (ogni 10 minuti per GO!, ogni ora per DHL) e imposta `synced_at`, che indica l'età di ogni risposta. Non esiste un aggiornamento forzato — DHL consente una chiamata di tracciamento ogni cinque secondi, quindi non sarebbe possibile offrire una lettura che interpella direttamente il corriere.

## Creazione di una spedizione

Quando crei una spedizione, specifichi il `location_id` di origine — la sede di test in cui il corriere deve effettuare il ritiro. Indichi anche il laboratorio di destinazione con `destination_lab`. La spedizione viene inviata all'indirizzo di spedizione registrato di quel laboratorio.

La sede deve rientrare nel contesto di accesso della tua chiave API. Usa [Elenca sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md) per trovare gli ID delle sedi disponibili.

Puoi passare facoltativamente `appointment_id` per collegare la spedizione a un appuntamento specifico al
momento della creazione. Il collegamento appare inline su entrambi i lati:

* sulla spedizione, come array `appointments` di elementi `{ id, added_at }`;
* sull'appuntamento, come array `shipments` di elementi `{ id, added_at }`.

Entrambi gli array sono ordinati dal collegamento più vecchio al più recente. Ogni `id` rimanda all'endpoint di dettaglio canonico
([Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md) /
[Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md)) per il payload completo — i partner che vogliono
l'avanzamento del corriere per singolo appuntamento seguono ogni elemento nell'array `shipments` dell'appuntamento fino
all'endpoint di dettaglio della spedizione.

Una spedizione può essere collegata a più appuntamenti e un appuntamento può essere collegato a più
spedizioni. Dopo la creazione, gestisci il collegamento con [Associa appuntamenti alla
spedizione](https://docs.anivahealth.com/it/api/shipments/attach-appointments-to-shipment.md) /
[Dissocia appuntamenti dalla spedizione](https://docs.anivahealth.com/it/api/shipments/detach-appointments-from-shipment.md). Ogni
modifica restituisce l'elenco degli appuntamenti della spedizione dopo la modifica.

La regola per le modifiche è: i collegamenti possono essere creati o rimossi quando l'appuntamento ha già superato
il prelievo di sangue (`blood_drawn`) OPPURE la spedizione è stata creata meno di 24 ore fa. Fuori da quella
finestra il collegamento è bloccato affinché i record storici restino stabili.

## Ciclo di vita

Le spedizioni passano attraverso i seguenti stati:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Stato | Significato |
| - | - |
| `pending` | L'ordine al corriere è stato inviato ed è in attesa di ritiro. |
| `in_transit` | Il corriere ha ritirato il pacco ed è in transito. |
| `delivered` | Il pacco è stato consegnato. |
| `fault` | Si è verificato un problema durante il transito, oppure il corriere ha rispedito il pacco al mittente. |
| `cancelled` | La spedizione è stata annullata. |

Ogni cambio di stato invia un [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md) `shipment.*`, ad esempio
`shipment.delivered`. `shipment.updated` si attiva a ogni modifica che puoi leggere, come una nuova scansione.

## Regole per la programmazione del ritiro

Quando crei o aggiorni la programmazione del ritiro di una spedizione si applicano le seguenti regole. `pickup_date`
(`YYYY-MM-DD`) e `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24h) sono valori di ora locale
**interpretati nel fuso orario IANA del luogo di origine** — non devi inviare un fuso orario insieme a essi.

| Regola | Dettaglio |
| - | - |
| **Solo giorni feriali** | `pickup_date` deve essere tra lunedì e venerdì. |
| **Oggi o in futuro** | `pickup_date` non può essere nel passato. |
| **Orario limite in giornata** | I ritiri in giornata vengono rifiutati dopo le 16:00 Europe/Berlin. |
| **Fascia oraria** | `pickup_time_from` e `pickup_time_till` devono rientrare tra le 09:00 e le 19:00. |
| **Finestra minima di 2 ore** | La finestra di ritiro deve durare almeno 2 ore. |

## Modificare le spedizioni

Puoi aggiornare la programmazione del ritiro, il numero di colli, il peso e le note di una spedizione tramite `PATCH /api/v1/shipments/{id}`. Se cambia un campo rilevante per la logistica (data di ritiro, orario, numero di colli o peso), l'ordine logistico esistente viene annullato automaticamente e ne viene creato uno nuovo. I campi che ometti dal corpo dell'aggiornamento vengono mantenuti dalla spedizione esistente — ad esempio, aggiornando solo `weight`, l'ordine viene ricreato con la stessa programmazione del ritiro. I campi della programmazione aggiornati vengono validati in base alle stesse [regole per la programmazione del ritiro](#regole-per-la-programmazione-del-ritiro).

> [!WARNING]
>
> Le spedizioni non possono essere modificate dopo che il corriere ha ritirato il pacco. I tentativi di aggiornare una
> spedizione in stato `in_transit`, `delivered` o `fault` restituiscono `409 Conflict`.

Se il fornitore logistico rifiuta l'annullamento o la ricreazione durante un aggiornamento, l'API restituisce `502 Bad Gateway` con il messaggio di errore del fornitore.

## Annullare le spedizioni

Annulla una spedizione tramite `DELETE /api/v1/shipments/{id}`. Questa chiamata invoca l'API del fornitore logistico per annullare l'ordine e aggiorna lo stato a `cancelled`.

> [!WARNING]
>
> Le spedizioni non possono essere annullate dopo il ritiro. I tentativi di annullare una spedizione già in stato
> `in_transit`, `delivered` o `fault` restituiscono `409 Conflict`. Annullarne una già
> `cancelled` non ha effetti e restituisce `200` con la spedizione — vedi
> [Idempotenza](https://docs.anivahealth.com/it/concepts/idempotency.md).

Il fornitore logistico può anche rifiutare l'annullamento per motivi propri (ad es. se il termine per l'annullamento è scaduto). In tal caso, l'API restituisce `502 Bad Gateway` con il messaggio di errore e il codice di errore del fornitore.

### Etichette di reso

Un'etichetta di reso DHL fa parte del relativo ordine di andata. DHL non può annullare l'etichetta da sola, quindi annullare la riga che traccia un'etichetta di reso restituisce `409 Conflict`. Annulla invece il pacco di andata, finché è in stato `pending`. Così annulli anche l'etichetta: ogni riga di ritorno `pending` del pacco di andata passa a `cancelled` e riceve una voce `RETURN_LEG_CANCELLED` in `status_updates`. Un pacco di reso già spedito dal paziente continua il suo percorso. Dopo la spedizione del pacco di andata, l'etichetta resta valida e Aniva chiude manualmente la riga di ritorno.

## ID di riferimento delle spedizioni

Ogni spedizione ha un ID di riferimento di 11 caratteri: una lettera, la data e quattro caratteri, `{letter}YYMMDDXXXX` (ad esempio `P2611194821`). La lettera indica a cosa appartiene la spedizione, mai la sua direzione:

| Lettera | Spedizione |
| - | - |
| `P` | Una spedizione che crei tramite questa API. |
| `M` | Una spedizione creata dal team Aniva. |
| `C` | Una spedizione dell'invio giornaliero di Aniva. |
| `K` | Un pacco con kit a domicilio. |
| `F`, `S` | Pacchi delle scorte interne di Aniva. |

Una spedizione dal 20 al 22 novembre 2026 mantiene il proprio ID con una parola davanti: `API`, `MAN`, `AUTO` o `KIT` (ad esempio `AUTO261121UWKX`). Entrambi i formati restano validi. Non controllare la lunghezza o la prima lettera di un ID. Usa l'ID per recuperare, aggiornare o annullare la spedizione.

## Indirizzi delle spedizioni

I campi `origin` e `destination` nella risposta della spedizione contengono oggetti indirizzo risolti con la seguente struttura:

```json theme={null}
{
  "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"
}
```

Per un pacco di uno studio medico, l'indirizzo `origin` viene risolto dalla sede del test che hai indicato alla
creazione e `destination` è il laboratorio che hai indicato in `destination_lab`.
Per un pacco di kit domiciliare, l'indirizzo di consegna del paziente è la `destination` del kit e
l'`origin` del reso del campione; la sede che confeziona il kit è la sua `origin`. L'indirizzo
non contiene `location_id` — collega un pacco di uno studio medico tramite l'appuntamento a cui è
associato.

## Finestra di ritiro

Il campo `pickup` nella risposta della spedizione contiene la finestra di ritiro del corriere programmata.
Include i timestamp `from` e `till` come istanti UTC (ISO 8601 con suffisso `Z`, ad es.
`2026-04-15T07:00:00Z`) e una stringa `timezone` (fuso orario IANA del luogo di ritiro). I valori locali
`pickup_date` / `pickup_time_*` che hai inviato in fase di creazione o aggiornamento vengono convertiti in questi
istanti assoluti usando quel fuso orario — usa `timezone` per riportare `from` / `till` all'ora
locale del luogo di ritiro. Il campo è `null` quando non è stata programmata alcuna finestra di ritiro.

## Registro degli aggiornamenti di stato

Ogni spedizione include un array `status_updates` — ogni evento del ciclo di vita segnalato dal fornitore
logistico, dal più vecchio al più recente. Ogni voce contiene:

* `state` — l'evento nel vocabolario degli stati di spedizione (`pending`, `in_transit`, `delivered`,
  `fault`), così puoi leggere la cronologia senza conoscere i codici del corriere. `null` quando l'evento
  non ha uno stato (creazione dell'etichetta, scansione senza informazioni del corriere, voci registrate prima che
  il campo esistesse). Mai `cancelled` — un annullamento è nostro, non un evento del corriere.
* `code` — il token di stato proprio del corriere (`GO10`, `GO90`, `GOY001` di GO!; `VA`, `ZF`,
  `LA`, `ZU` di DHL). `null` quando il corriere non ne fornisce alcuno. Stabile tra le traduzioni linguistiche di
  `status`.
* `detail_code` — il token più dettagliato del corriere, se presente: `statusDetailed` di DHL, ad es.
  `CNRFC_NRQRD_ZF` (reindirizzato a un ufficio postale), `HLDCC_SERPT_LA` (pronto per il ritiro lì),
  `DLVRD_SERPT_ZU` (ritirato). `null` negli altri casi.
* `status` — l'etichetta leggibile del corriere (ad es. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — una spiegazione del codice oppure la descrizione più lunga del corriere. `null` quando
  non esiste né l'una né l'altra.
* `location` — dove è avvenuta la scansione, con il nome usato dal corriere: un deposito GO!, una città DHL. Testo
  libero, non una coordinata.
* `time` — timestamp ISO 8601 dell'evento, come segnalato dal corriere (con il relativo offset).

Quando il corriere rispedisce il pacco al mittente, la cronologia riceve una voce con `code`
`RETURNED_TO_SENDER`. Il campo `status` riporta il motivo del corriere. La spedizione resta poi `fault`, anche
dopo che il corriere ci riconsegna il pacco.

L'elenco può essere vuoto se il corriere non ha ancora segnalato alcun evento.

Usa il campo `status` di primo livello per conoscere lo stato attuale canonico. Avanza in una sola direzione — da `pending`
a `in_transit` fino a `delivered` — con `fault` sovrapposto finché l'evento più recente ne segnala uno;
i corrieri non ordinano gli eventi per rilevanza (DHL aggiunge un avviso di reindirizzamento con codice `pre-transit`
dopo la scansione di consegna), quindi la voce più recente da sola non indica a che punto è il pacco.

## Esempio di spedizione

```json theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "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": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Esempio di pacchi di kit domiciliare

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` restituisce in coppia il kit in viaggio verso il paziente e il campione di ritorno:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

La riga di ritorno esiste dal momento in cui viene stampata l'etichetta di reso e resta `pending` finché il paziente non spedisce il campione — è lo stato reale, non una lacuna.


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