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

# Atualizar envio

> Alterar detalhes do envio antes da recolha

Atualiza os detalhes do envio, como o horário de recolha, o número de pacotes ou as notas. Se algum campo relevante para a logística mudar (data de recolha, hora, número de pacotes ou peso), o pedido logístico existente é cancelado e é criado um novo automaticamente. Os campos que omitires mantêm-se a partir do envio existente. Os campos de horário atualizados são validados segundo as [regras de agendamento de recolha](https://docs.anivahealth.com/pt/concepts/shipments.md#regras-de-agendamento-de-recolha).

> [!WARNING]
>
> Os envios não podem ser alterados após a recolha. Tentar atualizar um envio que já foi recolhido
> devolve `409 Conflict`.

Um pacote de kit de teste em casa já tem a etiqueta impressa, por isso só `notes` pode mudar. Uma
nova janela de recolha ou peso num pacote de kit de teste em casa devolve `409 Conflict`; cancela-o
e cria um novo envio em vez disso.

Para atualizar um pacote de kit de teste em casa, todas as encomendas de kit de teste em casa associadas 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`).

### Parâmetros do corpo

Todos os parâmetros do corpo são opcionais — inclui apenas os campos que queres alterar.

**pickup\_date** `string`

Nova data de recolha no formato `YYYY-MM-DD`, interpretada no fuso horário do local de origem.

**pickup\_time\_from** `string`

Nova hora mais cedo para a recolha no formato `HH:MM`, interpretada como hora local no fuso
horário do local de origem.

**pickup\_time\_till** `string`

Nova hora mais tarde para a recolha no formato `HH:MM`, interpretada como hora local no fuso
horário do local de origem.

**package\_count** `integer`

Novo número de pacotes.

**weight** `number`

Novo peso em kg.

**notes** `string`

Novas notas ou observações. Máximo de 128 caracteres.

## Resposta

Em caso de sucesso, a API devolve `200 OK` com o envio atualizado.

**id** `string` *required*

Identificador de referência do envio.

**status** `string` *required*

Estado do ciclo de vida do envio. Um dos seguintes: `pending`, `in_transit`, `delivered`, `fault` ou `cancelled`.

**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`). Usa-o para apresentar `from` / `till` na hora local de recolha.

**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 associadas a este envio, pela ligação mais antiga primeiro. Cada entrada é
`{ id, added_at }`; cruza cada `id` com [Obter marcação](https://docs.anivahealth.com/pt/api/appointments/get-appointment.md).
Só 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` | Erro de validação — por ex., formato de data ou hora 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 domiciliário associado está fora do teu contexto de acesso. |
| `404` | Envio não encontrado. |
| `409` | O envio não pode ser modificado após a recolha, ou trata-se de uma encomenda de kit domiciliário cuja etiqueta já foi impressa e o pedido altera mais do que `notes`. |
| `501` | O envio é `external` — não foi agendado através da Aniva e não pode ser alterado aqui. |
| `500` | Erro interno do servidor. |
| `502` | O operador logístico rejeitou o pedido (por ex., o cancelamento ou a recriação falhou). Inclui a mensagem de erro do operador. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/shipments/P2611194821 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "pickup_date": "2026-04-16",
    "pickup_time_from": "10:00",
    "pickup_time_till": "13:00"
  }'
```

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "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-16T08:00:00Z",
    "till": "2026-04-16T11: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-03T15:10:00Z"
}
```

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

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