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

> Cancelar um pedido de envio

Cancela um pedido de envio. Isto chama a API do operador logístico para cancelar o pedido e atualiza o estado do envio para `cancelled`.

Cancelar um envio que já está `cancelled` devolve `200` com esse envio, e o operador só é chamado uma vez. 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).

> [!WARNING]
>
> Não é possível cancelar envios após a recolha — isso devolve `409 Conflict`.

Não é possível cancelar uma etiqueta de devolução da DHL isoladamente; isso também devolve `409 Conflict`. Em vez disso, cancela
a encomenda de ida. Cancelar uma encomenda de ida da DHL também cancela os respetivos registos de devolução
`pending`. Cada um passa a `cancelled` com uma entrada `RETURN_LEG_CANCELLED` em `status_updates`. Consulta
[Etiquetas de devolução](https://docs.anivahealth.com/pt/concepts/shipments.md#etiquetas-de-devolucao).

Numa caixa com vários kits, cada kit tem o seu próprio registo de ida e a sua própria etiqueta de devolução, mesmo
quando a caixa viaja com a etiqueta de apenas um kit. Cancelar o registo de ida de um kit também cancela a etiqueta
de devolução desse kit.

Para cancelar uma encomenda de kit para casa, todos os pedidos de kit para casa associados têm de estar no teu contexto de acesso.
Caso contrário, a chamada devolve `403`. Consulta [Acesso](https://docs.anivahealth.com/pt/concepts/shipments.md#acesso).

## Pedido

### Parâmetros de caminho

**id** `string` *required*

ID de referência do envio (por ex., `P2611194821`).

## Resposta

Em caso de sucesso, a API devolve `200 OK` com o objeto do envio cancelado.

**id** `string` *required*

Identificador de referência do envio.

**status** `string` *required*

Estado do ciclo de vida do envio. Será `cancelled` após um cancelamento bem-sucedido.

**logistics\_provider** `string` *required*

Operador logístico. Um de `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` ou `dhl_express`. Uma encomenda de kit para casa é `dhl_parcel`, ou `dhl_warenpost` quando segue para o estrangeiro
como Warenpost International.

**tracking\_number** `string`

Número de seguimento externo do operador logístico. Pode ser `null`.

**contents** `string`

Descrição em texto livre do conteúdo da encomenda, conforme indicado na criação. Pode ser `null`.

**booked\_by** `string` *required*

Quem imprimiu a etiqueta: `aniva` ou `external`. Apenas os envios `aniva` aceitam esta chamada.

**paired\_with** `string`

Referência da outra encomenda de uma remessa com duas encomendas. `null` para uma encomenda só de ida.

**origin** `object`

Morada de recolha. Pode ser `null`.

**objeto de morada**

**name** `string` *required*

Nome do destinatário, empresa ou local.

**company\_name** `string`

Linha de empresa / a/c. Pode ser `null`.

**street** `string` *required*

Nome da rua, sem o número da porta.

**house\_number** `string`

Número da porta. Pode ser `null`.

**address\_line\_2** `string`

Edifício, entrada ou andar. Pode ser `null`.

**city** `string` *required*

Cidade.

**state** `string`

Estado ou província. Pode ser `null`.

**postal\_code** `string` *required*

Código postal.

**country\_code** `string` *required*

Código de país ISO 3166-1 alpha-2.

**phone** `string`

Número de telefone de contacto. Pode ser `null`.

**email** `string`

Email de contacto. Pode ser `null`.

**destination** `object`

Morada de entrega. Mesma estrutura que `origin`. Pode ser `null`.

**pickup** `object`

Janela de recolha agendada. Pode ser `null`.

**objeto pickup**

**from** `string` *required*

Início da janela de recolha como instante UTC (ISO 8601 com sufixo `Z`).

**till** `string` *required*

Fim da janela de recolha como instante UTC (ISO 8601 com sufixo `Z`).

**timezone** `string` *required*

Fuso horário IANA do local de recolha (por ex., `Europe/Berlin`).

**notes** `string`

Notas opcionais. Pode ser `null`.

**status\_updates** `object[]` *required*

Eventos cronológicos do ciclo de vida do operador logístico (mais antigos primeiro). Cada entrada tem
`state`, `code`, `detail_code`, `status`, `description`, `location` e `time`. Consulta [Obter
envio](https://docs.anivahealth.com/pt/api/shipments/get-shipment.md) para cada campo. Array vazio se ainda não houver eventos registados.

**appointments** `ShipmentAppointmentLink[]` *required*

Marcações que estavam associadas a este envio antes do cancelamento. Cada entrada tem o formato
`{ id, added_at }`; cruza cada `id` com
[Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md).
Apenas são listadas as marcações no teu contexto de acesso.

**home\_kit\_orders** `ShipmentHomeKitOrderLink[]` *required*

Pedidos de kits para casa associados a este envio, da associação mais antiga para a mais recente, no mesmo formato `{ id, added_at }`.
Apenas são listados os pedidos no teu contexto de acesso. Array vazio para encomendas de clínicas.

**synced\_at** `string`

Quando o envio foi reconciliado pela última vez com a transportadora, como instante UTC. `null` até à primeira
sincronização.

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

Data e hora de criação (ISO 8601).

**updated\_at** `string`

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

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Formato de ID inválido. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação, o envio está fora do teu contexto de acesso ou um pedido de kit para casa associado está fora do teu contexto de acesso. |
| `404` | Envio não encontrado. |
| `409` | O envio não pode ser cancelado — já foi recolhido ou entregue, ou trata-se de uma etiqueta de devolução DHL (cancela antes a encomenda de ida). |
| `501` | O envio é `external` — não foi reservado através da Aniva e não pode ser cancelado aqui. |
| `500` | Erro interno do servidor. |
| `502` | O operador logístico rejeitou o pedido (por ex., prazo de cancelamento ultrapassado). Inclui a mensagem de erro do operador. |

```bash cURL theme={null}
curl --request DELETE \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "cancelled",
  "logistics_provider": "go",
  "tracking_number": "GO1234567890",
  "contents": "Medizinisch freigestellte Probe",
  "booked_by": "aniva",
  "paired_with": null,
  "origin": {
    "name": "Aniva Berlin Mitte",
    "company_name": null,
    "street": "Unter den Linden",
    "house_number": "42",
    "address_line_2": null,
    "postal_code": "10117",
    "city": "Berlin",
    "state": null,
    "country_code": "DE",
    "phone": "+4930987654321",
    "email": "berlin-mitte@anivahealth.com"
  },
  "destination": {
    "name": "LabClinic GmbH",
    "company_name": null,
    "street": "Laborstraße",
    "house_number": "10",
    "address_line_2": null,
    "postal_code": "80331",
    "city": "München",
    "state": null,
    "country_code": "DE",
    "phone": null,
    "email": null
  },
  "pickup": {
    "from": "2026-04-15T07:00:00Z",
    "till": "2026-04-15T10:00:00Z",
    "timezone": "Europe/Berlin"
  },
  "notes": null,
  "status_updates": [],
  "appointments": [],
  "home_kit_orders": [],
  "synced_at": "2026-04-03T15:00:00Z",
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": "2026-04-03T16:45:00Z"
}
```

```json 409 theme={null}
{
  "error": "Shipment cannot be cancelled after pickup"
}
```

```json 409 (return label) theme={null}
{
  "error": "Shipment K260904P3XD is the return label of K2609041FQ7. DHL cannot cancel a return label on its own. Cancel the outbound parcel while it is pending. After the outbound parcel ships, the label stays valid and Aniva closes this shipment manually."
}
```

```json 403 (Aniva-managed parcel) theme={null}
{
  "error": "Access denied: only Aniva can change this parcel."
}
```

```json 404 theme={null}
{
  "error": "Shipment not found"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: The cancellation notice period has already been exceeded. Cancellation is no longer possible via the web service. Please contact the GO! station.",
  "logistics_error_code": 4006
}
```


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