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

# Listar encomendas de kit de teste em casa

> Obter os kits de teste em casa enviados por correio acessíveis à tua chave API

Obtém uma lista de encomendas de kit de teste em casa. Uma encomenda de kit de teste em casa envia pelo correio um kit de teste para fazer em casa — a Aniva envia o kit, o paciente colhe a amostra em casa e envia-a de volta pelo correio. Cada encomenda de kit de teste em casa inclui o perfil do paciente incorporado.

Quando `profile_id` é fornecido, devolve todas as encomendas de kit de teste em casa desse perfil. Quando omitido, devolve todas as encomendas de kit de teste em casa acessíveis.

Requer o scope `home_kit_orders_view` ou `home_kit_orders_manage`.

## Pedido

### Parâmetros de consulta

**profile\_id** `string`

Filtra por UUID do perfil. Quando fornecido, são devolvidas todas as encomendas de kit de teste em casa deste perfil.

**lab\_code** `string`

Filtra por código de laboratório (correspondência exata) — associa um kit físico em mão à respetiva encomenda através do código
impresso nele, por exemplo, antes de chamares [Ativar](https://docs.anivahealth.com/pt/api/home-kit-orders/activate-home-kit.md).

## Resposta

Em caso de sucesso, a API devolve `200 OK` com um array de objetos de encomenda de kit de teste em casa.

**id** `string` *required*

Identificador único da encomenda de kit de teste em casa (UUID).

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

UUID do perfil a que pertence esta encomenda de kit de teste em casa.

**status** `string` *required*

Estado atual da encomenda de kit de teste em casa. Um de `pending`, `dispatched`, `activated` ou `cancelled`.
O detalhe de conclusão dos resultados de laboratório é obtido a partir de [Obter resultados](https://docs.anivahealth.com/pt/api/home-kit-orders/get-results.md).

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

A morada para onde enviar o kit — um de dois formatos: `{ location_id }`, que referencia um local de teste conhecido, ou os campos de morada inline (`name`, `street`, `city`, `postal_code`, `country_code`; `company_name` / `house_number` / `address_line_2` / `state` / `phone` / `email` opcionais — o mesmo vocabulário da API de localizações). Indica exatamente um — uma referência de localização ou uma morada inline, não ambos.

**morada de entrega**

> [tab] Referência de localização
>
> **location\_id** `string` *required*
>
> UUID do local de teste para onde o kit é enviado.

> [tab] Morada inline
>
> **name** `string` *required*
>
> Nome do destinatário, da empresa ou do local.
>
> **company\_name** `string`
>
> Empresa que guarda o volume para o destinatário — uma entidade `c/o` ou um departamento.
>
> **street** `string` *required*
>
> Nome da rua, sem o número da porta (p. ex., `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número da porta (p. ex., `118` ou `12a`).
>
> **address\_line\_2** `string`
>
> Edifício, entrada ou andar.
>
> **city** `string` *required*
>
> **state** `string`
>
> Estado ou província. Opcional.
>
> **postal\_code** `string` *required*
>
> **country\_code** `string` *required*
>
> Código ISO 3166-1 alpha-2 (duas letras, p. ex., `DE`).
>
> **phone** `string`
>
> **email** `string`

**lab\_code** `string`

Código de amostra de laboratório sob o qual os resultados são comunicados — impresso no kit físico e o que o
paciente lê na caixa como código de ativação. `null` até o kit ser embalado.
Só de leitura.

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

Data e hora da colheita comunicadas através de [Ativar](https://docs.anivahealth.com/pt/api/home-kit-orders/activate-home-kit.md) — quando o
paciente recolheu a amostra. `null` até o kit ser ativado.

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

A encomenda de kit de teste em casa que esta substitui, quando se trata de um kit de substituição. `null` numa encomenda normal. Consulta
[Criar encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/create-home-kit.md).

**replacement\_reason** `string`

Motivo do envio da substituição. `null` numa encomenda normal.

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

Endereços que recebem um e-mail assim que todos os resultados laboratoriais forem definitivos, em minúsculas. Vazio quando desativado. Consulta
[E-mails de resultados prontos](https://docs.anivahealth.com/pt/concepts/results.md#e-mails-de-resultados-prontos).

**metadata** `object` *required*

Pares chave/valor definidos pelo parceiro, devolvidos sem alterações. Sempre presente — `{}` quando não definido.

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

Data e hora ISO 8601 de criação da encomenda de kit de teste em casa.

**updated\_at** `string`

Data e hora ISO 8601 da última atualização. Pode ser `null`.

**profile** `object` *required*

O perfil do paciente associado a esta encomenda de kit de teste em casa.

**perfil**

**id** `string`

Identificador único do perfil (UUID).

**handle** `string`

Handle ou nome de utilizador do perfil. Pode ser `null`.

**first\_name** `string`

Nome próprio. Pode ser `null`.

**last\_name** `string`

Apelido. Pode ser `null`.

**email** `string`

Endereço de e-mail. Pode ser `null`.

**phone** `string`

Número de telefone no formato E.164. Pode ser `null`.

**sex** `integer`

Sexo biológico segundo a norma ISO/IEC 5218. Pode ser `null`.

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

Data de nascimento no formato `YYYY-MM-DD`. Pode ser `null`.

**height** `number`

Altura em centímetros. Pode ser `null`.

**weight** `number`

Peso em quilogramas. Pode ser `null`.

**language** `string`

Idioma preferido: um dos 32 códigos em [Criar perfil](https://docs.anivahealth.com/pt/api/profiles/create-profile.md).

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

Se este perfil recebe e-mails transacionais (programáticos). Pode ser `null`.

**created\_at** `string`

Data e hora ISO 8601 da criação do perfil.

**updated\_at** `string`

Data e hora ISO 8601 da última atualização do perfil. Pode ser `null`.

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

O painel associado a esta encomenda de kit de teste em casa — sempre exatamente um (um kit de teste em casa corresponde 1:1 a um
produto de kit físico), substituível através de [Atualizar](https://docs.anivahealth.com/pt/api/home-kit-orders/update-home-kit.md) enquanto estiver
`pending`. Consulta os detalhes do painel (nome, biomarcadores) através de [Listar painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md).

**Campos de associação do painel**

**panel\_id** `string`

UUID do painel — cruza com [Listar painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md).

**added\_at** `string`

Data e hora ISO 8601 em que o painel foi associado pela primeira vez a esta encomenda de kit de teste em casa.

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

Biomarcadores avulsos associados a esta encomenda de kit de teste em casa fora de qualquer painel. Cruza cada
`biomarker_id` com [Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) com `home_kit=true` para obter os dados de apresentação.

**Campos de biomarcadores individuais**

**biomarker\_id** `integer`

Identificador do biomarcador — cruza com
[Listar biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) com `home_kit=true`.

**added\_at** `string`

Data e hora ISO 8601 em que o biomarcador foi associado pela primeira vez a esta encomenda de kit de teste em casa.

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

Pacotes associados a esta encomenda de kit de teste em casa, com a associação mais antiga primeiro — normalmente o kit para o paciente
e a amostra de volta para o laboratório. Vazio até a expedição imprimir uma etiqueta. Lê os
pacotes completos com [Listar envios](https://docs.anivahealth.com/pt/api/shipments/list-shipments.md) e `?home_kit_order_id=`.

**Campos de associação do envio**

**id** `string`

Referência do envio — cruza com [Obter envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md).

**added\_at** `string`

Data e hora ISO 8601 em que o envio foi associado a esta encomenda de kit de teste em casa.

## Chamadas repetidas

A Aniva guarda a resposta deste endpoint durante 5 minutos por cada chave API. Uma chamada repetida dentro
deste período recebe a resposta guardada. Os cabeçalhos `Cache-Status` e `Age` mostram que a resposta está
guardada e há quanto tempo.

Para saberes de uma alteração de imediato, subscreve os eventos de webhook `home_kit_order.created` e o evento de cada estado, por exemplo `home_kit_order.activated`.
Consulta [Leituras repetidas](https://docs.anivahealth.com/pt/concepts/webhooks.md#leituras-repetidas).

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — por exemplo, `profile_id` não é um UUID válido ou a query tem um parâmetro desconhecido. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação ou o perfil pedido está fora do teu âmbito de permissões. |
| `500` | Erro interno do 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.