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

# Cancelar encomenda de kit de teste em casa

> Cancelar um kit de teste em casa enviado por correio

Cancela uma encomenda de kit de teste em casa ao definir o seu estado como `cancelled`. A encomenda de kit de teste em casa cancelada é devolvida na resposta.

Só é possível cancelar uma encomenda `pending`. Assim que estiver `dispatched`, o kit já foi embalado e etiquetado pela logística e o cancelamento devolve `409` — tal como acontece com uma encomenda `activated`.

Se o kit já tiver sido encomendado à logística, cancelamo-lo lá antes de cancelar o teu, e a chamada falha quando não aceitam o cancelamento: `409` quando o kit já está embalado e etiquetado, `502` quando a logística recusou o cancelamento ou não foi possível contactá-la. Em qualquer caso de falha, **nada é alterado** — a encomenda mantém-se ativa e é seguro tentar novamente após um `502`.

Cancelar uma encomenda que já está `cancelled` devolve `200` com essa encomenda, independentemente do estado a partir do qual foi cancelada. A resposta inclui `Idempotent-Replayed: true` para poderes distinguir uma repetição da chamada que realizou a ação. Consulta [Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

Requer o âmbito `home_kit_orders_manage`.

## Pedido

### Parâmetros de caminho

**id** `string` *required*

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

## Resposta

Em caso de sucesso, a API devolve `200 OK` com a encomenda de kit de teste em casa cancelada e o perfil incorporado. Uma encomenda que já estava cancelada devolve o mesmo `200`.

**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 da encomenda de kit de teste em casa. Será `cancelled` após um cancelamento bem-sucedido.

**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 que estava associado a esta encomenda de kit de teste em casa antes do cancelamento — sempre exatamente um (um
kit de teste em casa corresponde 1:1 a um produto de kit físico). 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 avulso que estavam associados a esta encomenda de kit de teste em casa antes do cancelamento. 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*

Volumes que estavam associados a esta encomenda de kit de teste em casa antes do cancelamento, da associação mais antiga para a mais recente. Lê os
volumes 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` | Formato de ID inválido — o valor fornecido não é um UUID válido. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação ou a encomenda de kit de teste em casa está fora do teu âmbito de permissões. |
| `404` | Encomenda de kit de teste em casa não encontrada. |
| `409` | Conflito — a encomenda já não está `pending` (expedida ou ativada) ou o kit já foi embalado e etiquetado pela logística. |
| `500` | Erro interno do servidor. |
| `502` | A logística recusou o cancelamento (inclui o motivo) ou não foi possível contactá-la. Nada foi alterado; a encomenda continua ativa. |

```bash cURL theme={null}
curl --request DELETE \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a \
  --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": "cancelled",
  "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-03T10: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": [],
  "metadata": {},
  "replaces_home_kit_order_id": null,
  "replacement_reason": null,
  "results_ready_emails": [],
  "lab_code": null,
  "activated_at": null,
  "shipments": []
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```

```json 409 theme={null}
{
  "error": "A home kit order can only be cancelled while it is pending. Once it is dispatched or activated the physical kit has been packed and labelled and can no longer be called back."
}
```

```json 502 theme={null}
{
  "error": "Fulfilment refused the cancellation (Order is already in fulfillment). The home kit order was NOT cancelled."
}
```


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