> ## 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 una comanda de kit de prova a casa

> Sol·licita un kit de prova a casa enviat per correu per a un perfil

Sol·licita una comanda de kit de prova a casa per a un perfil de pacient. Una comanda de kit de prova a casa envia un kit d'autoprova per correu — Aniva envia el kit a l'adreça de lliurament, el pacient recull una mostra ell mateix a casa i la retorna per correu. Això es diferencia d'una [cita](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md), que és una extracció de sang venosa en un centre de proves.

**Cal exactament un panell.** Un kit de prova a casa correspon 1:1 a un producte de kit físic — el panell és el kit — i la comanda entra a la cua d'embalatge tan bon punt es crea, de manera que la composició ha de ser definitiva des del principi. Tot i així, pots canviar el panell mitjançant [Actualitza la comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/update-home-kit.md) mentre la comanda estigui en estat `pending`.

## Kits de substitució

Quan un kit no pot donar els seus resultats — el pacient no ha pogut omplir el tub, la mostra ha arribat amb massa poc material, el laboratori no l'ha pogut analitzar — demana una **substitució** enviant `replaces_home_kit_order_id`.

Una substitució és una comanda nova amb un nou codi de laboratori, també quan el primer kit no s'ha activat mai: el laboratori necessita una petició nova i no es poden distingir dues mostres amb el mateix codi. La comanda que substitueixes no es modifica — conserva el seu propi estat, el seu propi codi de laboratori i qualsevol resultat que ja hi estigui registrat.

Això implica dues coses:

* **El panell s'hereta.** Omet `panel_id` i la substitució porta el panell de la comanda que substitueix, que és el que va comprar el pacient i la marca que porta la caixa.
* **Tu tries què es torna a analitzar.** Envia `biomarker_ids` amb els marcadors que han fallat i el laboratori només torna a analitzar aquests, així el kit s'envia només amb els tubs que calen. Omet-lo per tornar a analitzar tot el panell.

Els marcadors es tornen a analitzar per grups del panell, no un per un. Si indiques un marcador d'un grup, es torna a analitzar tot el grup, perquè no es pot fer una petició de laboratori que informi de més del que s'ha demanat. Per tant, una substitució d'un sol marcador pot arribar amb més d'un resultat, i el nombre de tubs pot ser superior al que suggereix la llista de marcadors.

Només pot haver-hi una substitució en camí per kit alhora.

> [!NOTE]
>
> Si vas fer la integració abans que existissin aquests camps, Aniva també llegeix
> `metadata.original_kit_id` i `metadata.replacement_reason` en crear una comanda i la tracta com a
> substitució. Aquest és l'únic lloc on s'interpreten les metadades, existeix només per mantenir
> aquella integració anterior i els camps de dalt sempre tenen prioritat. Envia els camps.

Un `201` vol dir que la comanda queda confirmada i passarà a preparació — no cal que facis res més perquè el kit s'embali i s'enviï.

Requereix l'àmbit `home_kit_orders_manage`.

Envia una capçalera opcional `Idempotency-Key` perquè aquesta creació es pugui reintentar amb seguretat — repetir la mateixa clau retorna la resposta original en lloc de crear-ne una segona. Consulta [Idempotència](https://docs.anivahealth.com/ca/concepts/idempotency.md).

## Sol·licitud

### Paràmetres del cos

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

UUID del perfil de pacient per al qual es crea la comanda de kit de prova a casa.

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

UUID del panell del catàleg que vols demanar. Exactament un — un kit de prova a casa correspon
1:1 a un producte de kit físic, de manera que el panell és el kit. Aniva proporciona els ID de
panell per al teu compte de col·laborador; consulta [Llista els
panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md). Opcional en una substitució, on pren per defecte el panell de
la comanda que substitueixes.

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

UUID de la comanda de kit de prova a casa que aquesta substitueix. Si l'envies, la comanda passa
a ser un kit de substitució — consulta [Kits de substitució](#kits-de-substitucio) més amunt. La
comanda ha de pertànyer al mateix perfil i no pot tenir ja una substitució en camí.

**replacement\_reason** `string`

Per què cal la substitució, en una frase (per exemple, `Zu wenig Material, HbA1c nicht
    auswertbar`). Obligatori quan envies `replaces_home_kit_order_id` i ignorat en cas contrari.
Com a màxim 500 caràcters.

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

En una substitució, els marcadors que el laboratori torna a analitzar — normalment els que el
primer kit no ha pogut obtenir. Cada marcador ha de formar part del que demanava la comanda que
substitueixes; comprova'ls a [Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) amb
`home_kit=true`. Omet-lo per tornar a analitzar tot el panell. Només s'accepta juntament amb
`replaces_home_kit_order_id` i no juntament amb un `panel_id` diferent. No requereix cap scope
addicional: tornar a analitzar marcadors que el pacient ja ha pagat no és una selecció a la
carta.

**metadata** `object`

Els teus propis parells clau/valor, retornats literalment en cada lectura i mai interpretats per
Aniva. Fes-lo servir per incloure la teva referència de comanda i poder-la correlacionar sense
desar els nostres ID. Com a màxim 20 claus; les claus han de coincidir amb `[A-Za-z0-9_-]` i
tenir com a màxim 40 caràcters; els valors són cadenes, nombres o booleans, amb cadenes de com a
màxim 500 caràcters; 16.384 bytes serialitzats en total. Les claus que comencen per `aniva_`
estan reservades. No posis mai dades personals ni clíniques a `metadata` — no es tracten com a
dades de pacient.

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

Fins a 5 adreces que reben cadascuna un correu un cop tots els resultats del laboratori són
definitius. El correu enllaça a la pàgina de resultats del panell d'administració d'Aniva. La teva
clau necessita accés `results_view` per al pacient; si no, retorna `403`. Omet-lo per fer servir les
adreces per defecte configurades per al grup del pacient. Una llista buida desactiva els correus.
Consulta [Correus de resultats disponibles](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

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

L'adreça on s'ha d'enviar el kit per correu — una de dues formes: o bé `{ location_id }` fent referència a un centre de proves conegut, o bé els camps d'adreça directa (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opcionals — el mateix vocabulari que l'API d'ubicacions). Proporciona'n exactament una — una referència d'ubicació o una adreça directa, no totes dues.

**adreça de lliurament**

> [tab] Referencia una ubicació
>
> **location\_id** `string` *required*
>
> UUID d'un centre de proves conegut on enviar el kit. Correlaciona'l amb [Llista les
> ubicacions](https://docs.anivahealth.com/ca/api/locations/list-locations.md).

> [tab] Adreça directa
>
> **name** `string` *required*
>
> Nom del destinatari, de l'empresa o de la ubicació.
>
> **company\_name** `string`
>
> Empresa que recull el paquet per al destinatari — una entitat `c/o` o un departament.
>
> **street** `string` *required*
>
> Nom del carrer, sense el número (p. ex., `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número de portal (p. ex., `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edifici, entrada o pis.
>
> **city** `string` *required*
>
> **state** `string`
>
> Estat o província. Opcional.
>
> **postal\_code** `string` *required*
>
> Codi postal. Una adreça alemanya (`country_code` `DE`) necessita exactament 5 dígits, p. ex. `10117`.
>
> **country\_code** `string` *required*
>
> Codi ISO 3166-1 alfa-2 (dues lletres, p. ex. `DE`). S'accepten minúscules i es desen en
> majúscules.
>
> **phone** `string`
>
> Número de telèfon del destinatari, amb prefix de país (p. ex., `+4791234567`). El transportista
> el fa servir per avisar el destinatari sobre el paquet, per exemple que l'espera en un punt
> de recollida. Si l'omets, el transportista no rep cap número de telèfon.
>
> **email** `string`
>
> Correu electrònic del destinatari. El transportista el fa servir igual que `phone`. Si l'omets,
> el transportista no rep cap correu electrònic.

> [!NOTE]
>
> **Packstation o Postfiliale (només a Alemanya):** posa `Packstation` o `Postfiliale` a `street`,
> el número d'estació de tres dígits a `house_number` i el DHL Postnummer del destinatari (6–10
> dígits, s'admeten espais) a `address_line_2`. Sense el Postnummer, no es pot tramitar l'enviament
> del paquet. No s'admet un Postfach.

## Resposta

En cas d'èxit, l'API retorna `201 Created` amb la nova comanda de kit de prova a casa.

**id** `string` *required*

Identificador únic de la comanda de kit de prova a casa (UUID).

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

UUID del perfil al qual pertany aquesta comanda de kit de prova a casa.

**status** `string` *required*

Estat actual de la comanda de kit de prova a casa. Pot ser `pending`, `dispatched`, `activated`
o `cancelled`. Una comanda acabada de crear comença en `pending`.

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

L'adreça on enviar el kit per correu — pot tenir dues formes: o bé `{ location_id }`, que fa referència a una ubicació de prova coneguda, o bé els camps d'adreça directes (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opcionals — el mateix vocabulari que l'API d'ubicacions). Proporciona'n exactament una — una referència d'ubicació o una adreça directa, no pas totes dues.

**adreça de lliurament**

> [tab] Referència d'ubicació
>
> **location\_id** `string` *required*
>
> UUID de la ubicació de prova on s'envia el kit.

> [tab] Adreça directa
>
> **name** `string` *required*
>
> Nom del destinatari, de l'empresa o de la ubicació.
>
> **company\_name** `string`
>
> Empresa que rep el paquet per al destinatari — una entitat `c/o` o un departament.
>
> **street** `string` *required*
>
> Nom del carrer, sense el número (p. ex., `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número del carrer (p. ex., `118` o `12a`).
>
> **address\_line\_2** `string`
>
> Edifici, entrada o pis.
>
> **city** `string` *required*
>
> **state** `string`
>
> Estat o província. Opcional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Codi ISO 3166-1 alfa-2 (dues lletres, p. ex., `DE`).
>
> **phone** `string`
>
> **email** `string`

**metadata** `object` *required*

Els parells clau/valor que has proporcionat. Sempre present — `{}` quan no n'has definit cap.

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

La comanda de kit de prova a casa que aquesta substitueix. `null` en una comanda normal.

**replacement\_reason** `string`

El motiu que has proporcionat. `null` en una comanda normal.

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

Adreces que reben un correu electrònic cadascuna quan tots els resultats del laboratori són definitius, en minúscules. Buit quan està desactivat. Consulta
[Correus electrònics de resultats a punt](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

**lab\_code** `string`

Codi de mostra del laboratori amb què s'informen els resultats — imprès al kit físic, i el que el
pacient llegeix de la caixa com a codi d'activació. `null` fins que el kit estigui empaquetat.
Només de lectura.

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

Marca de temps de la recollida notificada mitjançant
[Activa](https://docs.anivahealth.com/ca/api/home-kit-orders/activate-home-kit.md). `null` fins que s'activi el kit.

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

Marca de temps ISO 8601 de quan es va crear la comanda de kit de prova a casa.

**updated\_at** `string`

Marca de temps ISO 8601 de l'última actualització. Pot ser `null`.

**profile** `object` *required*

El perfil del pacient associat a aquesta comanda de kit de prova a casa.

**perfil**

**id** `string`

Identificador únic del perfil (UUID).

**handle** `string`

Àlies o nom d'usuari del perfil. Pot ser `null`.

**first\_name** `string`

Nom. Pot ser `null`.

**last\_name** `string`

Cognom. Pot ser `null`.

**email** `string`

Adreça electrònica. Pot ser `null`.

**phone** `string`

Número de telèfon en format E.164. Pot ser `null`.

**sex** `integer`

Sexe biològic segons ISO/IEC 5218. Pot ser `null`.

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

Data de naixement en format `YYYY-MM-DD`. Pot ser `null`.

**height** `number`

Alçada en centímetres. Pot ser `null`.

**weight** `number`

Pes en quilograms. Pot ser `null`.

**language** `string`

Idioma preferit: un dels 32 codis a [Crea un perfil](https://docs.anivahealth.com/ca/api/profiles/create-profile.md).

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

Indica si aquest perfil rep correus electrònics transaccionals (programàtics). Pot ser `null`.

**created\_at** `string`

Marca de temps ISO 8601 de quan es va crear el perfil.

**updated\_at** `string`

Marca de temps ISO 8601 de l'última actualització del perfil. Pot ser `null`.

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

El panell associat a aquesta comanda de kit de prova a casa — el que has proporcionat com a
`panel_id`, registrat amb l'hora de creació de la comanda. Sempre exactament un. Consulta els
detalls del panell (nom, biomarcadors) a [Llista els panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md).

**Camps d'associació del panell**

**panel\_id** `string`

UUID del panell — consulta'l a [Llista panells](https://docs.anivahealth.com/ca/api/panels/list-panels.md).

**added\_at** `string`

Marca de temps ISO 8601 de quan es va associar el panell per primera vegada a aquesta comanda de kit de prova a casa.

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

Biomarcadors associats fora del panell. Buit en una creació normal — les comandes de kit de prova
a casa es demanen per panell, i modificar aquesta llista després requereix el scope de capacitat
`home_kit_orders_individual_biomarker_selection`. En una substitució conté els `biomarker_ids`
que has enviat, que són els que el laboratori torna a analitzar.

**Camps de biomarcador individual**

**biomarker\_id** `integer`

Identificador del biomarcador — consulta'l a
[Llista biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) amb `home_kit=true`.

**added\_at** `string`

Marca de temps ISO 8601 de quan es va associar el biomarcador per primera vegada a aquesta comanda de kit de prova a casa.

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

Paquets vinculats a aquesta comanda de kit de prova a casa, començant pel vincle més antic.
Sempre buit en crear-la — llegeix els paquets complets amb [Llista els
enviaments](https://docs.anivahealth.com/ca/api/shipments/list-shipments.md) i `?home_kit_order_id=`.

**Camps de vincle d'enviament**

**id** `string`

Referència de l'enviament — consulta-la a [Obtén un enviament](https://docs.anivahealth.com/ca/api/shipments/get-shipment.md).

**added\_at** `string`

Marca de temps ISO 8601 de quan es va vincular l'enviament a aquesta comanda de kit de prova a casa.

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Error de validació — p. ex., falta un camp a `delivery_address` o té un codi postal alemany que no és de 5 dígits, `panel_id` no és un UUID vàlid o falta `replacement_reason` en una substitució. |
| `403` | Prohibit — la teva clau d'API no té accés a aquesta operació, el perfil és fora del teu àmbit de permisos o has definit `results_ready_emails` sense accés `results_view` al pacient. |
| `404` | No s'ha trobat el perfil, el panell o la comanda de kit de prova a casa que cal substituir. |
| `409` | Conflicte — la clau `Idempotency-Key` ja s'ha fet servir amb un cos diferent, la seva sol·licitud original encara no ha finalitzat o el kit que substitueixes ja té una substitució en camí. |
| `422` | El panell no es pot demanar com a kit de prova a casa — no hi ha cap producte de kit configurat per a la seva preparació. En una substitució: la comanda que substitueixes pertany a un altre perfil, una entrada de `biomarker_ids` no forma part del que demanava o has enviat marcadors juntament amb un `panel_id` diferent. |
| `500` | Error intern del servidor. |

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