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

# Llista les comandes de kits de prova a casa

> Recupera els kits de prova a casa enviats per correu accessibles per a la teva clau d'API

Obtén una llista de comandes de kits de prova a casa. Una comanda de kit de prova a casa envia un kit de prova per fer a casa — Aniva envia el kit, el pacient recull la mostra a casa i l'envia de tornada per correu. Cada comanda de kit de prova a casa inclou el perfil del pacient integrat.

Quan es proporciona `profile_id`, retorna totes les comandes de kits de prova a casa d'aquest perfil. Quan s'omet, retorna totes les comandes de kits de prova a casa accessibles.

Requereix l'àmbit `home_kit_orders_view` o `home_kit_orders_manage`.

## Sol·licitud

### Paràmetres de consulta

**profile\_id** `string`

Filtra per UUID del perfil. Quan es proporciona, retorna totes les comandes de kits de prova a casa d'aquest perfil.

**lab\_code** `string`

Filtra per codi de laboratori (coincidència exacta) — associa un kit físic que tinguis a mà amb la seva comanda mitjançant el codi
que hi porta imprès, p. ex. abans de cridar [Activa](https://docs.anivahealth.com/ca/api/home-kit-orders/activate-home-kit.md).

## Resposta

En cas d'èxit, l'API retorna `200 OK` amb una matriu d'objectes de 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`.
El grau de compleció dels resultats de laboratori s'obté a [Obtén els resultats](https://docs.anivahealth.com/ca/api/home-kit-orders/get-results.md).

**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
kit físic), i es pot canviar amb [Actualitza](https://docs.anivahealth.com/ca/api/home-kit-orders/update-home-kit.md) mentre
és `pending`. 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 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.

## Crides repetides

Aniva desa la resposta d'aquest punt final durant 5 minuts per a cada clau d'API. Una crida repetida dins
d'aquest període rep la resposta desada. Les capçaleres `Cache-Status` i `Age` indiquen que la resposta està
desada i quina antiguitat té.

Per assabentar-te d'un canvi de seguida, subscriu-te als esdeveniments webhook `home_kit_order.created` i a l'esdeveniment de cada estat, per exemple `home_kit_order.activated`.
Consulta [Lectures repetides](https://docs.anivahealth.com/ca/concepts/webhooks.md#lectures-repetides).

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Error de validació — per exemple, `profile_id` no és un UUID vàlid o la consulta té un paràmetre desconegut. |
| `403` | Prohibit — la teva clau API no té accés a aquesta operació o el perfil sol·licitat queda fora del teu àmbit de permisos. |
| `500` | Error intern del servidor. |

```bash cURL (all home kit orders) theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (by profile) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/home-kit-orders?profile_id=a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "status": "dispatched",
    "delivery_address": {
      "name": "Maria Schmidt",
      "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": "2026-04-02T08:00: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": [
      {
        "biomarker_id": 42,
        "added_at": "2026-04-01T09:52:00Z"
      }
    ],
    "metadata": {},
    "replaces_home_kit_order_id": null,
    "replacement_reason": null,
    "results_ready_emails": [],
    "lab_code": "7642000123",
    "activated_at": null,
    "shipments": [
      { "id": "K2604021FQ7", "added_at": "2026-04-02T08:00:00Z" },
      { "id": "K260402P3XD", "added_at": "2026-04-02T08:00:00Z" }
    ]
  }
]
```

```json 403 theme={null}
{
  "error": "Access denied: profile is outside your permission scope"
}
```


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