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

# Elenca spedizioni

> Recupera le spedizioni, filtrate per appuntamento, ordine di kit a domicilio o stato

Recupera le spedizioni accessibili alla tua chiave API, dalla più recente. Ogni pacco è in questo unico elenco:
un ritiro tramite corriere da uno studio medico, il kit in viaggio verso un paziente con kit domiciliare e il campione in
ritorno. Filtra per un singolo elemento principale con `appointment_id` o `home_kit_order_id`.

Richiede lo scope `shipments_view` o `shipments_manage`.

La risposta proviene dal nostro database e non chiama mai il corriere. Una sincronizzazione in background aggiorna ogni
spedizione (ogni 10 minuti per GO!, ogni ora per DHL) e `synced_at` in ogni riga ti indica quando il
corriere è stato interrogato l'ultima volta.

## Richiesta

### Parametri di query

**appointment\_id** `string`

Solo spedizioni collegate a questo appuntamento (UUID). `404` quando l'appuntamento non esiste, `403`
quando è fuori dal tuo contesto di accesso.

**home\_kit\_order\_id** `string`

Solo spedizioni collegate a questo ordine di kit domiciliare (UUID). Di norma vengono restituite due righe: il kit in
viaggio verso il paziente e il campione di ritorno al laboratorio (il suo `destination` è il laboratorio). Stesse
regole `404` / `403` di `appointment_id`.

**status** `string`

Solo spedizioni in questo stato. Uno tra `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Numero massimo di spedizioni da restituire. Valore predefinito 100, massimo 500.

**offset** `integer`

Numero di spedizioni da saltare. Valore predefinito 0. L'ordinamento è stabile (`created_at` decrescente, poi
riferimento), quindi le pagine non si sovrappongono.

## Risposta

In caso di successo, l'API restituisce `200 OK` con un array di oggetti spedizione.

**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 indicata alla creazione (es. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Solo a scopo informativo — per sapere se un pacco è diretto a un
laboratorio si legge `destination`, e il pacco corrispondente da `paired_with`. Può essere `null`.

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

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` viene tracciato, ma restituisce `501` per entrambe le operazioni.

**paired\_with** `string`

Riferimento dell'altro pacco di una spedizione di due pacchi: il pacco che conteneva un'etichetta di
reso e il pacco che quell'etichetta riporta indietro. Impostato su entrambi. `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). Array vuoto se il
fornitore non ha ancora segnalato eventi. Usalo per la UI per evento, l'audit e i segnali più dettagliati del corriere;
affidati a `status` per lo stato attuale canonico.

**campi di aggiornamento dello stato**

**state** `string | null` *required*

L'evento nel vocabolario degli stati di spedizione — `pending`, `in_transit`, `delivered` o
`fault` — così puoi leggere una cronologia senza conoscere i codici del corriere. `null` quando
l'evento non ha stato (creazione dell'etichetta, scansione senza informazioni del corriere, voci
registrate prima dell'esistenza di questo campo). Mai `cancelled`.

**code** `string | null` *required*

Il token di stato del corriere: `GO10` / `GO90` / `GOY001` di GO!, `VA` / `ZF` / `LA`
/ `ZU` di DHL. `null` quando il corriere non ne ha fornito alcuno. Stabile tra le traduzioni di
`status`.

**detail\_code** `string | null` *required*

Il token più dettagliato del corriere, se disponibile — `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` per i corrieri che non ne dispongono.

**status** `string` *required*

Etichetta di stato fornita dal corriere (testo libero, ad es. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Una spiegazione del codice o la frase più estesa del corriere. `null` quando non esiste né l'una né l'altra.

**location** `string | null` *required*

Dove è avvenuta la scansione, secondo il nome del corriere — un deposito GO! (`"HUB Niederaula"`) o una
città DHL. Testo libero, non una coordinata. `null` quando il corriere non ha indicato nulla.

**time** `string` *required*

Ora in cui l'evento è stato rilevato (ISO 8601, con l'offset segnalato dal corriere).

**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) per il
payload completo dell'appuntamento. Array vuoto se non ci sono appuntamenti collegati.
Vengono elencati solo gli appuntamenti nel tuo contesto di accesso.

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

Ordini di kit domiciliari collegati a questa spedizione, dal collegamento più vecchio, nella stessa struttura `{ id, added_at }`.
Confronta ogni `id` con [Ottieni ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/get-home-kit.md). Array
vuoto per i pacchi degli studi medici. Vengono elencati solo gli ordini nel tuo contesto di accesso. Vedi
[Accesso](https://docs.anivahealth.com/it/concepts/shipments.md#accesso).

**synced\_at** `string`

Quando la spedizione è stata sincronizzata l'ultima volta con il corriere, come istante UTC. Le letture non chiamano mai il
corriere — una sincronizzazione in background mantiene aggiornate le spedizioni — quindi questo indica quanto è vecchia la risposta. `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`.

## Chiamate ripetute

Aniva salva la risposta di questo endpoint per 5 minuti per ogni chiave API. Una chiamata ripetuta
in questo intervallo riceve la risposta salvata. Gli header `Cache-Status` e `Age` indicano che la risposta è
salvata e da quanto tempo.

Per sapere subito di una modifica, iscriviti agli eventi webhook `shipment.created` e `shipment.updated`.
Vedi [Letture ripetute](https://docs.anivahealth.com/it/concepts/webhooks.md#letture-ripetute).

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Parametro query non valido. |
| `403` | Accesso negato — scope mancante, oppure l'appuntamento o l'ordine di kit domiciliare filtrato è fuori dal tuo ambito di accesso. |
| `404` | L'appuntamento o l'ordine di kit domiciliare filtrato non è stato trovato. |
| `500` | Errore interno del server. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "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": [
      {
        "state": "in_transit",
        "code": "GO10",
        "detail_code": null,
        "status": "Shipment picked up",
        "description": "Picked up at the consignor",
        "location": "Berlin",
        "time": "2026-04-15T09:22:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "GO50",
        "detail_code": null,
        "status": "Receiving station",
        "description": null,
        "location": "HUB Niederaula",
        "time": "2026-04-15T11:18:00+02:00"
      }
    ],
    "appointments": [
      {
        "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
        "added_at": "2026-04-15T08:30:00Z"
      }
    ],
    "home_kit_orders": [],
    "synced_at": "2026-04-15T11:20:00Z",
    "created_at": "2026-04-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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