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

# Actualitza una comanda de kit de prova a casa

> Modifica un kit de prova a casa enviat per correu

Actualitza l'adreça de lliurament, el panell, les metadades o els correus de resultats disponibles d'una comanda de kit de prova a casa. Inclou només els camps que vulguis canviar.

L'adreça de lliurament i el panell només es poden canviar mentre la comanda té l'estat `pending`, perquè el kit físic s'envia en el moment de l'expedició. `metadata` serveix per al teu propi registre i es pot modificar durant tota la vida de la comanda.

No hi ha punts finals per afegir o eliminar panells: un kit de prova a casa porta exactament un panell (correspon 1:1 a un producte de kit físic), així que l'única operació de panell amb sentit és el canvi que fas aquí.

Requereix l'àmbit `home_kit_orders_manage`.

## Sol·licitud

### Paràmetres de ruta

**id** `string` *required*

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

### Paràmetres del cos

Tots els paràmetres del cos són opcionals — inclou només els camps que vulguis canviar.

**delivery\_address** `object`

L'adreça on s'ha d'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 integrats (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` són opcionals — el mateix vocabulari que l'API d'ubicacions). Proporciona'n exactament una — una referència d'ubicació o una adreça integrada, 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.

**panel\_id** `string`

UUID del panell que s'ha d'associar en lloc de l'actual — com que cada kit té exactament un
panell, un canvi és l'única operació amb sentit. Només mentre la comanda té l'estat `pending` i
només per un panell que Aniva hagi configurat amb un producte de kit d'expedició (`422` en cas
contrari); canviar pel panell que ja està associat no té cap efecte.

**metadata** `object`

Els teus propis parells clau/valor. **Es fusionen** amb les metadades existents en lloc de
substituir-les: les claus que ometis es conserven, una clau enviada amb valor `null` s'elimina i
un objecte buit `{}` ho esborra tot. Els límits coincideixen amb [Crea una comanda de kit de prova
a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/create-home-kit.md), i la validació és de tot o res — si es rebutja
qualsevol clau, no s'escriu res. No posis mai dades personals ni clíniques a `metadata` — no es
tracten com a dades de pacient.

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

Substitueix la llista de fins a 5 adreces que reben cadascuna un correu quan tots els resultats
del laboratori són definitius. Envia `[]` per desactivar els correus. Es pot editar en tots els
estats excepte `cancelled`. La teva clau necessita accés `results_view` al pacient; si no,
retorna `403`. Consulta [Correus de resultats disponibles](https://docs.anivahealth.com/ca/concepts/results.md#correus-d-avis-de-resultats-a-punt).

## Resposta

En cas d'èxit, l'API retorna `200 OK` amb la comanda de kit de prova a casa actualitzada i el seu perfil incrustat.

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

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

**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 informada mitjançant [Activa](https://docs.anivahealth.com/ca/api/home-kit-orders/activate-home-kit.md) — quan el
pacient va recollir la mostra. `null` fins que el kit estigui activat.

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

La comanda de kit de prova a casa que aquesta substitueix, quan és un kit de substitució. `null` en una comanda normal. Consulta
[Crea una comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/create-home-kit.md).

**replacement\_reason** `string`

Motiu pel qual s'ha enviat la substitució. `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).

**metadata** `object` *required*

Parells clau/valor definits pel col·laborador, retornats literalment. Sempre present — `{}` quan no s'ha definit.

**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 — sempre n'hi ha exactament un (un kit
de prova a casa correspon 1:1 a un producte de kit físic) i se substitueix directament quan passes
`panel_id`. Consulta els detalls del panell (nom, biomarcadors) mitjançant [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 a la carta associats a aquesta comanda de kit de prova a casa fora de qualsevol panell. Creua cada
`biomarker_id` amb [Llista els biomarcadors](https://docs.anivahealth.com/ca/api/biomarkers/list-biomarkers.md) amb `home_kit=true` per obtenir les dades de visualització.

**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, primer el més antic — normalment el kit cap al pacient
i la mostra de tornada al laboratori. Buit fins que logística imprimeixi una etiqueta. Consulta 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., format d'UUID no vàlid o falta un camp de `delivery_address`. |
| `403` | Prohibit — la teva clau d'API no té accés a aquesta operació, la comanda de kit de prova a casa é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 la comanda de kit de prova a casa, o el panell de `panel_id` no existeix. |
| `409` | Conflicte — la comanda ja no té l'estat `pending`; l'adreça i el panell només es poden canviar abans de l'expedició. |
| `409` | Conflicte — la comanda és un kit de substitució, que conserva el panell de la comanda que substitueix. |
| `409` | Conflicte — la comanda té l'estat `cancelled` i has enviat `results_ready_emails`. |
| `422` | El panell no es pot demanar com a kit de prova a casa — no hi ha cap producte de kit d'expedició configurat. |
| `500` | Error intern del servidor. |

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