> ## 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 ordine di kit domiciliare

> Richiedi un kit per test domiciliare fai da te per un profilo

Richiedi un ordine di kit domiciliare per il profilo di un paziente. Un ordine di kit domiciliare invia un kit di test fai da te per posta — Aniva spedisce il kit all'indirizzo di consegna, il paziente raccoglie da solo un campione a casa e lo rispedisce per posta. Questo è diverso da un [appuntamento](https://docs.anivahealth.com/it/api/appointments/create-appointment.md), che è un prelievo venoso in una sede di test.

**È richiesto esattamente un pannello.** Un kit domiciliare corrisponde 1:1 a un prodotto kit fisico — il pannello è il kit — e l'ordine entra in coda di imballaggio non appena viene creato, quindi la composizione deve essere definitiva fin dall'inizio. Puoi comunque cambiare il pannello tramite [Aggiorna ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/update-home-kit.md) finché l'ordine è `pending`.

## Kit sostitutivi

Quando un kit non può fornire i risultati — il paziente non è riuscito a riempire la provetta, il campione è arrivato con troppo poco materiale, il laboratorio non è riuscito ad analizzarlo — ordina una **sostituzione** inviando `replaces_home_kit_order_id`.

Una sostituzione è un nuovo ordine con un nuovo codice di laboratorio, anche quando il primo kit non è mai stato attivato: il laboratorio ha bisogno di una nuova richiesta e due campioni con lo stesso codice non possono essere distinti. L'ordine che sostituisci non viene modificato — mantiene il proprio stato, il proprio codice di laboratorio ed eventuali risultati già registrati per quell'ordine.

Ne conseguono due cose:

* **Il pannello viene ereditato.** Ometti `panel_id` e la sostituzione riprende il pannello dell'ordine che sostituisce, cioè ciò che il paziente ha acquistato e il marchio riportato sulla scatola.
* **Scegli tu cosa ripetere.** Invia `biomarker_ids` con i marcatori non riusciti e il laboratorio ripete solo quelli, così il kit viene spedito solo con le provette necessarie. Omettilo per ripetere l'intero pannello.

I marcatori vengono ripetuti per gruppi del pannello, non uno per uno. Indicare un marcatore di un gruppo fa ripetere l'intero gruppo, perché non è possibile inviare un ordine di laboratorio che riporti più di quanto richiesto. Una sostituzione per un singolo marcatore può quindi arrivare con più di un risultato e il numero di provette può essere maggiore di quanto suggerisca l'elenco dei marcatori.

Può essere in viaggio una sola sostituzione per kit alla volta.

> [!NOTE]
>
> Se hai effettuato l'integrazione prima che questi campi esistessero, Aniva legge anche `metadata.original_kit_id` e
> `metadata.replacement_reason` in fase di creazione e tratta l'ordine come una sostituzione. Questo è l'unico
> punto in cui i metadati vengono interpretati, esiste solo per supportare quella precedente integrazione e i campi
> sopra hanno sempre la precedenza. Invia i campi.

Un `201` significa che l'ordine è confermato e verrà passato alla logistica — non devi fare altro perché il kit venga imballato e spedito.

Richiede lo scope `home_kit_orders_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

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

UUID del profilo paziente per cui creare l'ordine di kit domiciliare.

**panel\_id** `string` *required*

UUID del pannello a catalogo da ordinare. Esattamente uno — un kit domiciliare corrisponde 1:1 a un prodotto kit fisico,
quindi il pannello è il kit. Gli ID dei pannelli sono forniti da Aniva per il tuo account partner; vedi [Elenca
pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md). Facoltativo per una sostituzione, dove per impostazione predefinita viene usato il pannello
dell'ordine che sostituisci.

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

UUID dell'ordine di kit domiciliare che questo sostituisce. Inviarlo rende questo ordine un kit sostitutivo — vedi
[Kit sostitutivi](#kit-sostitutivi) sopra. L'ordine deve appartenere allo stesso profilo e non deve
avere già una sostituzione in viaggio.

**replacement\_reason** `string`

Il motivo per cui è necessaria la sostituzione, in una frase (ad esempio `Zu wenig Material, HbA1c nicht
    auswertbar`). Obbligatorio quando invii `replaces_home_kit_order_id`, altrimenti ignorato. Al massimo
500 caratteri.

**biomarker\_ids** `integer[]`

In una sostituzione, i marcatori che il laboratorio ripete — di solito quelli che il primo kit non ha potuto
fornire. Ognuno deve far parte di ciò che richiedeva l'ordine che sostituisci; verifica con [Elenca
biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) con `home_kit=true`. Omettilo per ripetere l'intero pannello. Accettato
solo insieme a `replaces_home_kit_order_id` e non insieme a un `panel_id` diverso.
Non richiede alcuno scope aggiuntivo: ripetere marcatori che il paziente ha già pagato non è una selezione
à la carte.

**metadata** `object`

Le tue coppie chiave/valore, restituite invariate a ogni lettura e mai interpretate da Aniva. Usalo
per inserire il tuo riferimento d'ordine così da poterlo correlare senza salvare i nostri ID. Al massimo 20 chiavi;
le chiavi rispettano `[A-Za-z0-9_-]` e hanno al massimo 40 caratteri; i valori sono stringhe, numeri o booleani,
con stringhe di al massimo 500 caratteri; 16.384 byte serializzati in totale. Le chiavi che iniziano con `aniva_` sono
riservate. Non inserire mai dati personali o clinici in `metadata` — non viene trattato come dato del paziente.

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

Fino a 5 indirizzi che ricevono ciascuno un'email quando tutti i risultati di laboratorio sono definitivi. L'email rimanda alla
pagina dei risultati nel pannello di amministrazione Aniva. La tua chiave richiede l'accesso `results_view` per il paziente, altrimenti
`403`. Omettilo per usare gli indirizzi predefiniti impostati per il gruppo del paziente. Una lista vuota disattiva le
email. Vedi [Email di risultati pronti](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

**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` facoltativi — 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 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.

## Risposta

In caso di successo, l'API restituisce `201 Created` con il nuovo ordine di kit domiciliare.

**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 di kit domiciliare. Uno tra `pending`, `dispatched`, `activated` o `cancelled`. Un
ordine appena creato inizia in `pending`.

**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`

**metadata** `object` *required*

Le coppie chiave/valore che hai fornito. Sempre presente — `{}` se non ne hai impostata nessuna.

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

L'ordine di kit domiciliare che questo sostituisce. `null` per un ordine normale.

**replacement\_reason** `string`

Il motivo che hai fornito. `null` per 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).

**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 della raccolta comunicato tramite [Attiva](https://docs.anivahealth.com/it/api/home-kit-orders/activate-home-kit.md). `null` finché
il kit non viene attivato.

**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 di kit domiciliare — quello fornito come `panel_id`, registrato con l'ora
di creazione dell'ordine. Sempre esattamente uno. 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 aggiunti al di fuori del pannello. Vuoto in una creazione normale — gli ordini di kit domiciliare vengono ordinati per
pannello e modificare questo elenco in seguito richiede lo scope di funzionalità
`home_kit_orders_individual_biomarker_selection`. In una sostituzione contiene i
`biomarker_ids` che hai inviato, ovvero quelli che il laboratorio ripete.

**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, a partire dal collegamento più vecchio. Sempre vuoto alla creazione — 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 — ad es. manca un campo in `delivery_address` o contiene un codice postale tedesco che non ha 5 cifre, `panel_id` non è un UUID valido oppure manca `replacement_reason` in una sostituzione. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione, il profilo è fuori dal tuo ambito di permessi oppure hai impostato `results_ready_emails` senza accesso `results_view` per il paziente. |
| `404` | Profilo, pannello o ordine di kit domiciliare da sostituire non trovato. |
| `409` | Conflitto — la `Idempotency-Key` è già stata usata con un body diverso, la richiesta originale non è ancora terminata oppure il kit che stai sostituendo ha già una sostituzione in viaggio. |
| `422` | Il pannello non è ordinabile come kit domiciliare — non è configurato alcun prodotto kit per la logistica. In una sostituzione: l'ordine che sostituisci appartiene a un altro profilo, una voce di `biomarker_ids` non fa parte di ciò che richiedeva oppure hai inviato marcatori insieme a un `panel_id` diverso. |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
    "metadata": { "your_order_ref": "ORD-10482", "priority": true },
    "delivery_address": {
      "name": "Maria Schmidt",
      "company_name": "c/o Weber",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE",
      "phone": "+4930123456789",
      "email": "maria.schmidt@example.com"
    }
  }'
```

```bash Replacement kit theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "replaces_home_kit_order_id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "replacement_reason": "Too little material, HbA1c could not be analysed",
    "biomarker_ids": [103],
    "metadata": { "your_order_ref": "ORD-10482-R1" },
    "delivery_address": {
      "name": "Maria Schmidt",
      "street": "Friedrichstraße",
      "house_number": "123",
      "postal_code": "10117",
      "city": "Berlin",
      "country_code": "DE"
    }
  }'
```

```json 201 theme={null}
{
  "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "status": "pending",
  "delivery_address": {
    "name": "Maria Schmidt",
    "company_name": "c/o Weber",
    "address_line_2": null,
    "street": "Friedrichstraße",
    "house_number": "123",
    "postal_code": "10117",
    "city": "Berlin",
    "country_code": "DE",
    "phone": "+4930123456789",
    "email": "maria.schmidt@example.com"
  },
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "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:45:00Z"
    }
  ],
  "individual_biomarkers": [],
  "metadata": { "your_order_ref": "ORD-10482", "priority": true },
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 400 theme={null}
{
  "error": "panel_id: panel_id must be a valid UUID"
}
```

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

```json 409 theme={null}
{
  "error": "Idempotency-Key \"ORD-10482\" was already used with a different request body. Use a new key for a different request, or resend the original body to read back its result."
}
```


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