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

# Aggiorna ordine di kit domiciliare

> Modifica un kit per test domiciliare fai da te

Aggiorna l'indirizzo di consegna, il pannello, i metadati o le email di notifica dei risultati pronti di un ordine del kit domiciliare. Includi solo i campi che vuoi modificare.

L'indirizzo di consegna e il pannello possono essere modificati solo finché l'ordine è `pending`, perché il kit fisico viene spedito al momento dell'invio. `metadata` è per la tua gestione interna e rimane modificabile per tutta la durata dell'ordine.

Non esistono endpoint per aggiungere o rimuovere pannelli: un kit domiciliare include esattamente un pannello (corrisponde 1:1 a un prodotto kit fisico), quindi l'unica operazione sensata sul pannello è la sostituzione che fai qui.

Richiede lo scope `home_kit_orders_manage`.

## Richiesta

### Parametri di percorso

**id** `string` *required*

Identificativo univoco (UUID) dell'ordine del kit domiciliare da aggiornare.

### Parametri del body

Tutti i parametri del body sono facoltativi — includi solo i campi che vuoi modificare.

**delivery\_address** `object`

L'indirizzo a cui spedire il kit — in una delle due forme: `{ location_id }`, che fa riferimento a una sede di test nota, oppure i campi indirizzo inline (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` facoltativi — lo stesso schema dell'API delle sedi). Fornisci esattamente una delle due opzioni — un riferimento a una sede o un indirizzo inline, non entrambi.

**indirizzo di consegna**

> [tab] Riferimento a una sede
>
> **location\_id** `string` *required*
>
> UUID di una sede di test nota a cui spedire il kit. Correla con [Elenca
> sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md).

> [tab] Indirizzo inline
>
> **name** `string` *required*
>
> Nome del destinatario, dell'azienda o della sede.
>
> **company\_name** `string`
>
> Azienda che riceve il pacco per il destinatario — un destinatario `c/o` o un reparto.
>
> **street** `string` *required*
>
> Nome della via, senza il numero civico (ad es. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numero civico (ad es. `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edificio, ingresso o piano.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stato o provincia. Facoltativo.
>
> **postal\_code** `string` *required*
>
> Codice postale. Un indirizzo tedesco (`country_code` `DE`) richiede esattamente 5 cifre, ad es. `10117`.
>
> **country\_code** `string` *required*
>
> Codice ISO 3166-1 alpha-2 (due lettere, ad es. `DE`). Le minuscole sono accettate e salvate in
> maiuscolo.
>
> **phone** `string`
>
> Numero di telefono del destinatario, con prefisso internazionale (ad es. `+4791234567`). Il corriere lo usa per
> avvisare il destinatario sul pacco, ad esempio che è in attesa presso un punto di ritiro. Se lo
> ometti, il corriere non riceve alcun numero di telefono.
>
> **email** `string`
>
> Email del destinatario. Il corriere la usa come `phone`. Se la ometti, il corriere non riceve alcuna
> email.

> [!NOTE]
>
> **Packstation o Postfiliale (solo Germania):** imposta `street` su `Packstation` o `Postfiliale`,
> `house_number` sul numero a tre cifre della stazione e `address_line_2` sul DHL
> Postnummer del destinatario (6–10 cifre, spazi consentiti). Senza il Postnummer, il pacco non può essere prenotato.
> Una Postfach non è supportata.

**panel\_id** `string`

UUID del pannello da associare al posto di quello attuale — con esattamente un pannello per kit, la sostituzione
è l'unica operazione sensata. È consentita solo finché l'ordine è `pending` e solo con un pannello che Aniva ha
configurato con un prodotto kit di evasione (altrimenti `422`); la sostituzione con il pannello già associato
non ha effetto.

**metadata** `object`

Le tue coppie chiave/valore. Vengono **unite** ai metadati esistenti invece di sostituirli: le chiavi
omesse vengono mantenute, una chiave inviata con valore `null` viene eliminata e un oggetto vuoto `{}` cancella
tutto. I limiti corrispondono a quelli di [Crea ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/create-home-kit.md) e
la validazione è tutto o niente — se una chiave viene rifiutata, non viene salvato nulla. Non inserire mai dati personali o
clinici in `metadata` — non vengono trattati come dati del paziente.

**results\_ready\_emails** `string[]`

Sostituisce l'elenco di massimo 5 indirizzi che ricevono ciascuno un'email quando tutti i risultati di laboratorio sono definitivi.
Invia `[]` per disattivare le email. Modificabile in qualsiasi stato tranne `cancelled`. La tua chiave deve avere
accesso `results_view` al paziente, altrimenti `403`. Vedi
[Email di risultati pronti](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

## Risposta

In caso di successo, l'API restituisce `200 OK` con l'ordine del kit domiciliare aggiornato e il relativo profilo incorporato.

**id** `string` *required*

Identificatore univoco dell'ordine di kit domiciliare (UUID).

**profile\_id** `string` *required*

UUID del profilo a cui appartiene questo ordine di kit domiciliare.

**status** `string` *required*

Stato attuale dell'ordine del kit domiciliare. Uno tra `pending`, `dispatched`, `activated` o `cancelled`.

**delivery\_address** `object` *required*

L'indirizzo a cui spedire il kit — in uno di due formati: `{ location_id }` che fa riferimento a una sede di test nota, oppure i campi dell'indirizzo inline (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opzionali — lo stesso vocabolario dell'API delle sedi). Fornisci esattamente uno dei due — un riferimento a una sede o un indirizzo inline, non entrambi.

**indirizzo di consegna**

> [tab] Riferimento sede
>
> **location\_id** `string` *required*
>
> UUID della sede di test a cui viene spedito il kit.

> [tab] Indirizzo inline
>
> **name** `string` *required*
>
> Nome del destinatario, dell'azienda o della sede.
>
> **company\_name** `string`
>
> Azienda che riceve il pacco per conto del destinatario — un destinatario `c/o` o un reparto.
>
> **street** `string` *required*
>
> Nome della via, senza il numero civico (ad es. `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Numero civico (ad es. `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edificio, ingresso o piano.
>
> **city** `string` *required*
>
> **state** `string`
>
> Stato o provincia. Opzionale.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Codice ISO 3166-1 alpha-2 (due lettere, ad es. `DE`).
>
> **phone** `string`
>
> **email** `string`

**lab\_code** `string`

Codice campione di laboratorio con cui vengono refertati i risultati — stampato sul kit fisico e
letto dal paziente sulla scatola come codice di attivazione. `null` finché il kit non viene imballato.
Di sola lettura.

**activated\_at** `string` *required*

Timestamp di raccolta segnalato tramite [Attiva](https://docs.anivahealth.com/it/api/home-kit-orders/activate-home-kit.md) — quando il
paziente ha raccolto il campione. `null` finché il kit non viene attivato.

**replaces\_home\_kit\_order\_id** `string`

L'ordine di kit domiciliare sostituito da questo, quando si tratta di un kit sostitutivo. `null` su un ordine normale. Consulta
[Crea ordine di kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/create-home-kit.md).

**replacement\_reason** `string`

Motivo per cui è stata inviata la sostituzione. `null` su un ordine normale.

**results\_ready\_emails** `string[]` *required*

Indirizzi che ricevono ciascuno un'email quando tutti i risultati di laboratorio sono definitivi, in minuscolo. Vuoto se disattivato. Vedi
[Email di risultati pronti](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

**metadata** `object` *required*

Coppie chiave/valore definite dal partner, restituite esattamente come inviate. Sempre presente — `{}` se non impostato.

**created\_at** `string` *required*

Timestamp ISO 8601 della creazione dell'ordine di kit domiciliare.

**updated\_at** `string`

Timestamp ISO 8601 dell'ultimo aggiornamento. Può essere `null`.

**profile** `object` *required*

Il profilo del paziente associato a questo ordine di kit domiciliare.

**profilo**

**id** `string`

Identificatore univoco del profilo (UUID).

**handle** `string`

Handle o nome utente del profilo. Può essere `null`.

**first\_name** `string`

Nome. Può essere `null`.

**last\_name** `string`

Cognome. Può essere `null`.

**email** `string`

Indirizzo email. Può essere `null`.

**phone** `string`

Numero di telefono in formato E.164. Può essere `null`.

**sex** `integer`

Sesso biologico secondo ISO/IEC 5218. Può essere `null`.

**date\_of\_birth** `string`

Data di nascita in formato `YYYY-MM-DD`. Può essere `null`.

**height** `number`

Altezza in centimetri. Può essere `null`.

**weight** `number`

Peso in chilogrammi. Può essere `null`.

**language** `string`

Lingua preferita: uno dei 32 codici in [Crea profilo](https://docs.anivahealth.com/it/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indica se questo profilo riceve email transazionali (programmatiche). Può essere `null`.

**created\_at** `string`

Timestamp ISO 8601 della creazione del profilo.

**updated\_at** `string`

Timestamp ISO 8601 dell'ultimo aggiornamento del profilo. Può essere `null`.

**panels** `HomeKitOrderPanel[]` *required*

Il pannello associato a questo ordine del kit domiciliare — sempre esattamente uno (un kit domiciliare corrisponde 1:1 a un
prodotto kit fisico), sostituito sul posto quando passi `panel_id`. Consulta i dettagli del pannello (nome,
biomarcatori) tramite [Elenca pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md).

**Campi del pannello associato**

**panel\_id** `string`

UUID del pannello — confrontalo con [Elenca pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md).

**added\_at** `string`

Timestamp ISO 8601 in cui il pannello è stato associato per la prima volta a questo ordine di kit domiciliare.

**individual\_biomarkers** `HomeKitOrderIndividualBiomarker[]` *required*

Biomarcatori singoli associati a questo ordine di kit domiciliare al di fuori di qualsiasi pannello. Confronta ogni
`biomarker_id` con [Elenca biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) con `home_kit=true` per i dati di visualizzazione.

**Campi del biomarcatore singolo**

**biomarker\_id** `integer`

Identificatore del biomarcatore — confrontalo con
[Elenca biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) con `home_kit=true`.

**added\_at** `string`

Timestamp ISO 8601 in cui il biomarcatore è stato associato per la prima volta a questo ordine di kit domiciliare.

**shipments** `HomeKitOrderShipmentLink[]` *required*

Pacchi collegati a questo ordine di kit domiciliare, dal collegamento più vecchio in poi — di solito il kit verso il paziente
e il campione di ritorno al laboratorio. Vuoto finché la logistica non stampa un'etichetta. Leggi i
pacchi completi con [Elenca spedizioni](https://docs.anivahealth.com/it/api/shipments/list-shipments.md) e `?home_kit_order_id=`.

**Campi del collegamento alla spedizione**

**id** `string`

Riferimento della spedizione — confrontalo con [Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md).

**added\_at** `string`

Timestamp ISO 8601 in cui la spedizione è stata collegata a questo ordine di kit domiciliare.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — es. formato UUID non valido o campo `delivery_address` mancante. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione, l'ordine del kit domiciliare è fuori dal tuo ambito di autorizzazione oppure hai impostato `results_ready_emails` senza accesso `results_view` al paziente. |
| `404` | Ordine del kit domiciliare non trovato, oppure il pannello `panel_id` non esiste. |
| `409` | Conflitto — l'ordine non è più `pending`; indirizzo e pannello possono cambiare solo prima della spedizione. |
| `409` | Conflitto — l'ordine è un kit sostitutivo, che mantiene il pannello dell'ordine che sostituisce. |
| `409` | Conflitto — l'ordine è `cancelled` e hai inviato `results_ready_emails`. |
| `422` | Il pannello non è ordinabile come kit domiciliare — non è configurato alcun prodotto kit di evasione. |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Unter den Linden",
      "house_number": "77",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```json 200 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "street": "Unter den Linden",
    "house_number": "77",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-01T13:10:00Z",
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482" },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "delivery_address: Invalid input"
}
```

```json 409 theme={null}
{
  "error": "Panels and biomarkers can only be changed while the home kit order is pending. Once it is dispatched, activated, or cancelled its composition is locked."
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```


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