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

# Ottieni spedizione

> Recupera una spedizione tramite il suo ID di riferimento

Recupera una singola spedizione tramite il suo ID di riferimento. 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` ti indica quando è stato interrogato il corriere l'ultima volta.

Richiede lo scope `shipments_view` o `shipments_manage`.

## 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 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 memorizza la risposta di questo endpoint per 60 minuti per ogni chiave API. Una chiamata ripetuta entro
questo intervallo riceve la risposta memorizzata finché la spedizione non cambia. Dopo una modifica, ottieni una risposta
aggiornata. Gli header `Cache-Status` e `Age` indicano che la risposta è
memorizzata e quanto è vecchia.

In una risposta memorizzata, `synced_at` e `updated_at` possono essere più vecchi rispetto a una risposta aggiornata.

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` | Formato ID non valido. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione oppure la spedizione è fuori dal tuo contesto di accesso. Un pacco rientra nel tuo contesto di accesso quando vi rientra almeno un appuntamento o un ordine di kit domiciliare collegato. |
| `404` | Spedizione non trovata. |
| `500` | Errore interno del server. |

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

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}
```

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


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