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

# Crea spedizione

> Crea un ordine di spedizione logistica con origine e destinazione specificate

Crea un ordine di spedizione dalla sede di origine specificata. Indichi il laboratorio di destinazione con `destination_lab`. La spedizione va all'indirizzo di spedizione registrato per quel laboratorio.

Richiede lo scope `shipments_manage`.

Invia un header opzionale `Idempotency-Key` per poter ripetere questa creazione in sicurezza — ripetere la stessa chiave restituisce la risposta originale invece di crearne una seconda. Vedi [Idempotenza](https://docs.anivahealth.com/it/concepts/idempotency.md).

## Richiesta

### Parametri del body

**location\_id** `string` *required*

UUID della sede del test di origine. La sede deve essere attiva e 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.

**destination\_lab** `string` *required*

Laboratorio di destinazione. Uno tra `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` o
`quade`. La spedizione va all'indirizzo di spedizione registrato per questo laboratorio. Un laboratorio
senza un indirizzo di spedizione registrato restituisce `400`.

**appointment\_id** `string`

UUID facoltativo dell'appuntamento a cui collegare questa spedizione al momento della creazione. L'appuntamento deve essere
nel contesto di accesso della tua chiave API. Il collegamento compare direttamente come voce nell'array `appointments`
della spedizione e, viceversa, come voce nell'array `shipments` dell'appuntamento. Per collegare
altri appuntamenti dopo la creazione, o rimuovere il collegamento iniziale, usa [Collega appuntamenti alla
spedizione](https://docs.anivahealth.com/it/api/shipments/attach-appointments-to-shipment.md) e [Scollega appuntamenti dalla
spedizione](https://docs.anivahealth.com/it/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Data di ritiro in formato `YYYY-MM-DD` (es. `2026-04-15`), interpretata nel fuso orario
della sede di origine. Deve essere un giorno feriale (lunedì–venerdì), oggi o in futuro. I ritiri in giornata non sono
disponibili dopo le 16:00 Europe/Berlin.

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

Orario minimo di ritiro in formato `HH:MM` (es. `09:00`), interpretato come ora locale nel
fuso orario della sede di origine. Deve essere compreso tra `09:00` e `19:00`.

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

Orario massimo di ritiro in formato `HH:MM` (es. `12:00`), interpretato come ora locale nel fuso orario
della sede di origine. Deve essere compreso tra `09:00` e `19:00`. La fascia (`pickup_time_till -
    pickup_time_from`) deve durare almeno 2 ore.

**package\_count** `integer` (default: 1)

Numero di colli. Il valore predefinito è `1`.

**weight** `number` (default: 0.5)

Peso in kg. Il valore predefinito è `0.5`.

**pickup\_remarks** `string`

Istruzioni per il corriere al ritiro (note del mittente). Se omesso, vengono usate le note salvate
dell'indirizzo di ritiro (o nessuna se l'indirizzo non ne ha). Massimo 128 caratteri.

**contents** `string`

Descrizione in testo libero del contenuto del pacco, mostrata al corriere e restituita come
`contents`. Massimo 40 caratteri (es. `Medizinisch freigestellte Probe`).

**notes** `string`

Note interne facoltative. Massimo 128 caratteri.

## Risposta

In caso di successo, l'API restituisce `201 Created` con la nuova spedizione.

**id** `string` *required*

Identificativo di riferimento della spedizione (es. `P2604151234`).

**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`. Una spedizione creata da te è `aniva`.

**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 subito dopo la creazione.
La sincronizzazione in background aggiunge gli eventi man mano che il fornitore li segnala.

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

Appuntamenti collegati a questa spedizione, dal collegamento più vecchio al più recente. Ogni voce è `{ id, added_at }`;
confronta ogni `id` con [Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md).
Contiene l'appuntamento passato tramite `appointment_id` (se presente) subito dopo la creazione.

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

Ordini di kit a domicilio collegati a questa spedizione, nello stesso formato `{ id, added_at }`. Array vuoto per una
spedizione creata da te.

**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 — es. formato data non valido, data nel fine settimana, fascia di ritiro troppo stretta, orario limite per il ritiro in giornata superato. Restituito anche quando `destination_lab` o la sede di origine non ha un indirizzo registrato. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione o la sede è fuori dal tuo contesto di accesso. |
| `404` | Sede non trovata o non attiva, oppure è stato fornito `appointment_id` ma l'appuntamento non esiste. |
| `409` | La `Idempotency-Key` è già stata usata con un corpo di richiesta diverso, oppure la sua richiesta originale non è ancora stata completata. |
| `500` | Errore interno del server. |
| `502` | Il fornitore logistico ha rifiutato la richiesta. Include il messaggio di errore del fornitore. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 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-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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