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

# Criar encomenda de kit de teste em casa

> Pedir um kit de teste em casa enviado por correio para um perfil

Faz uma encomenda de kit de teste em casa para um perfil de paciente. Uma encomenda de kit de teste em casa envia um kit de teste para fazer em casa por correio — a Aniva envia o kit para a morada de entrega, o paciente recolhe a amostra em casa e envia-a de volta por correio. Isto é diferente de uma [marcação](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md), que é uma colheita de sangue venoso num local de análise.

**É obrigatório exatamente um painel.** Um kit de teste em casa corresponde 1:1 a um kit físico — o painel é o kit — e a encomenda entra na fila de embalamento assim que é criada, pelo que a composição tem de ser definitiva à partida. Ainda podes trocar o painel através de [Atualizar encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/update-home-kit.md) enquanto a encomenda estiver em `pending`.

## Kits de substituição

Quando um kit não consegue fornecer os resultados — o paciente não conseguiu encher o tubo, a amostra chegou com material insuficiente, o laboratório não a conseguiu analisar — encomenda uma **substituição** enviando `replaces_home_kit_order_id`.

Uma substituição é uma nova encomenda com um novo código de laboratório, mesmo quando o primeiro kit nunca foi ativado: o laboratório precisa de uma nova requisição e não é possível distinguir duas amostras com o mesmo código. A encomenda que substituis não é alterada — mantém o seu próprio estado, o seu próprio código de laboratório e quaisquer resultados já registados nela.

Daqui resultam duas coisas:

* **O painel é herdado.** Omite `panel_id` e a substituição leva o painel da encomenda que substitui, que é o que o paciente comprou e o que identifica a caixa.
* **Tu escolhes o que é repetido.** Envia `biomarker_ids` com os marcadores que falharam e o laboratório repete apenas esses, pelo que o kit segue apenas com os tubos necessários. Omite-o para repetir todo o painel.

Os marcadores são repetidos pelos grupos do painel, não um a um. Indicar um marcador de um grupo repete todo esse grupo, porque não é possível fazer um pedido ao laboratório que reporte mais do que foi solicitado. Uma substituição de um único marcador pode, portanto, chegar com mais de um resultado, e o número de tubos pode ser superior ao que a lista de marcadores sugere.

Só pode estar a caminho uma substituição por kit de cada vez.

> [!NOTE]
>
> Se fizeste a integração antes de estes campos existirem, a Aniva também lê `metadata.original_kit_id` e
> `metadata.replacement_reason` na criação e trata a encomenda como uma substituição. Este é o único
> local onde os metadados são interpretados, existe apenas para manter essa integração anterior e os campos
> acima prevalecem sempre. Envia os campos.

Um `201` significa que a encomenda está confirmada e será encaminhada para expedição — não precisas de fazer mais nada para o kit ser embalado e enviado.

Requer o âmbito `home_kit_orders_manage`.

Envia um cabeçalho opcional `Idempotency-Key` para tornar esta criação segura para repetir — repetir a mesma chave devolve a resposta original em vez de criar outra. Vê [Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

## Pedido

### Parâmetros do corpo

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

UUID do perfil de paciente para o qual criar a encomenda de kit de teste em casa.

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

UUID do painel do catálogo a encomendar. Exatamente um — um kit de teste em casa corresponde 1:1 a um kit físico,
pelo que o painel é o kit. Os IDs de painel são fornecidos pela Aniva para a tua conta de parceiro; consulta [Listar
painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md). Opcional numa substituição, onde assume por predefinição o painel da
encomenda que substituis.

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

UUID da encomenda de kit de teste em casa que esta substitui. Ao enviá-lo, esta passa a ser um kit de substituição — consulta
[Kits de substituição](#kits-de-substituicao) acima. A encomenda tem de pertencer ao mesmo perfil e não pode
já ter uma substituição a caminho.

**replacement\_reason** `string`

O motivo pelo qual a substituição é necessária, numa frase (por exemplo, `Zu wenig Material, HbA1c nicht
    auswertbar`). Obrigatório quando envias `replaces_home_kit_order_id` e ignorado nos restantes casos. No máximo
500 caracteres.

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

Numa substituição, os marcadores que o laboratório repete — normalmente os que o primeiro kit não conseguiu
fornecer. Cada um tem de fazer parte do que a encomenda que substituis pediu; confirma com [Listar
biomarcadores](https://docs.anivahealth.com/pt/api/biomarkers/list-biomarkers.md) com `home_kit=true`. Omite-o para repetir todo o painel. Só é
aceite em conjunto com `replaces_home_kit_order_id` e não em conjunto com um `panel_id` diferente.
Isto não requer nenhum scope adicional: repetir marcadores que o paciente já pagou não é uma seleção
à la carte.

**metadata** `object`

Os teus próprios pares chave/valor, devolvidos exatamente como enviados em cada leitura e nunca interpretados pela Aniva. Usa
este campo para incluir a tua referência de encomenda e correlacionares sem guardares os nossos IDs. No máximo 20 chaves;
as chaves têm de corresponder a `[A-Za-z0-9_-]` e ter no máximo 40 caracteres; os valores são uma string, um número ou um booleano,
com strings de no máximo 500 caracteres; 16 384 bytes serializados no total. As chaves que começam por `aniva_` estão
reservadas. Nunca coloques dados pessoais ou clínicos em `metadata` — não é tratado como dados de paciente.

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

Até 5 endereços que recebem um e-mail cada assim que todos os resultados laboratoriais forem
finais. O e-mail inclui uma ligação para a página de resultados no painel de administração da
Aniva. A tua chave precisa de acesso `results_view` ao paciente, caso contrário devolve `403`.
Omite este campo para usar os endereços predefinidos para o grupo do paciente. Uma lista vazia
desativa os e-mails. Vê [E-mails de resultados prontos](https://docs.anivahealth.com/pt/concepts/results.md#e-mails-de-resultados-prontos).

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

A morada para a qual enviar o kit por correio — tem um de dois formatos: `{ location_id }`, que referencia um local de análise conhecido, ou os campos de morada diretamente (`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 locais). Indica exatamente um — uma referência de local ou uma morada direta, não ambos.

**morada de entrega**

> [tab] Referenciar um local
>
> **location\_id** `string` *required*
>
> UUID de um local de análise conhecido para onde enviar o kit. Correlaciona com [Listar
> locais](https://docs.anivahealth.com/pt/api/locations/list-locations.md).

> [tab] Morada direta
>
> **name** `string` *required*
>
> Nome do destinatário, da empresa ou do local.
>
> **company\_name** `string`
>
> Empresa que guarda a encomenda para o destinatário — um intermediário `c/o` ou um departamento.
>
> **street** `string` *required*
>
> Nome da rua, sem o número da porta (por exemplo, `Wilhelmstraße`).
>
> **house\_number** `string`
>
> Número da porta (por exemplo, `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*
>
> Código postal. Uma morada alemã (`country_code` `DE`) precisa de exatamente 5 dígitos, por exemplo, `10117`.
>
> **country\_code** `string` *required*
>
> Código ISO 3166-1 alpha-2 (duas letras, por exemplo, `DE`). Minúsculas são aceites e guardadas em
> maiúsculas.
>
> **phone** `string`
>
> Número de telefone do destinatário, com indicativo do país (por exemplo, `+4791234567`). A transportadora usa-o para
> avisar o destinatário sobre a encomenda, por exemplo, que está à espera num ponto de recolha. Omite-o
> e a transportadora não recebe nenhum número de telefone.
>
> **email** `string`
>
> E-mail do destinatário. A transportadora usa-o tal como `phone`. Omite-o e a transportadora não recebe nenhum
> e-mail.

> [!NOTE]
>
> **Packstation ou Postfiliale (apenas Alemanha):** define `street` como `Packstation` ou `Postfiliale`,
> `house_number` como o número de três dígitos da estação e `address_line_2` como o DHL
> Postnummer do destinatário (6–10 dígitos, espaços permitidos). Sem o Postnummer, não é possível registar o envio.
> Não é suportado Postfach.

## Resposta

Em caso de sucesso, a API devolve `201 Created` com a nova 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`. Uma
encomenda recém-criada começa em `pending`.

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

**metadata** `object` *required*

Os pares chave/valor que indicaste. Sempre presente — `{}` quando não defines nenhum.

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

A encomenda de kit de teste em casa que esta substitui. `null` numa encomenda normal.

**replacement\_reason** `string`

O motivo que indicaste. `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).

**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). `null` até
o kit ser ativado.

**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 — o que indicaste como `panel_id`, com o registo da
hora de criação da encomenda. Sempre exatamente um. 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 associados fora do painel. Vazio numa criação normal — as encomendas de kits de teste em casa são feitas por
painel e alterar esta lista depois requer o scope de capacidade
`home_kit_orders_individual_biomarker_selection`. Numa substituição contém os
`biomarker_ids` que enviaste, que são os que o laboratório repete.

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

Envios associados a esta encomenda de kit de teste em casa, por ordem da associação mais antiga primeiro. Sempre vazio na criação — consulta os
envios 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.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — por exemplo, falta um campo em `delivery_address` ou tem um código postal alemão que não tem 5 dígitos, `panel_id` não é um UUID válido ou falta `replacement_reason` numa substituição. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação, o perfil está fora do teu âmbito de permissões ou definiste `results_ready_emails` sem acesso `results_view` ao paciente. |
| `404` | Perfil, painel ou encomenda de kit de teste em casa a substituir não encontrados. |
| `409` | Conflito — a `Idempotency-Key` já foi utilizada com um corpo diferente, o pedido original ainda não terminou ou o kit que estás a substituir já tem uma substituição a caminho. |
| `422` | O painel não pode ser encomendado como kit de teste em casa — não existe nenhum produto de kit configurado para expedição. Numa substituição: a encomenda que substituis pertence a outro perfil, uma entrada em `biomarker_ids` não faz parte do que foi pedido ou enviaste marcadores em conjunto com um `panel_id` diferente. |
| `500` | Erro interno do 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.