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

> Criar um pedido de envio logístico com origem e destino especificados

Cria um pedido de envio a partir do local de origem especificado. Indicas o laboratório de destino com `destination_lab`. O envio segue para a morada de envio registada desse laboratório.

Requer o âmbito `shipments_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

**location\_id** `string` *required*

UUID do local de testes de origem. O local tem de estar ativo e dentro do contexto de acesso da tua chave de API.
Usa [Listar locais](https://docs.anivahealth.com/pt/api/locations/list-locations.md) para encontrar os IDs de locais disponíveis.

**destination\_lab** `string` *required*

Laboratório de destino. Um dos seguintes: `zotzklimas`, `labclinic`, `nordicgroup`, `biomes`, `imd` ou
`quade`. O envio segue para a morada de envio registada para este laboratório. Um laboratório
sem morada de envio registada devolve `400`.

**appointment\_id** `string`

UUID opcional da marcação à qual associar este envio no momento da criação. A marcação tem de estar
dentro do contexto de acesso da tua chave de API. A associação aparece diretamente como uma entrada no
array `appointments` do envio e, inversamente, como uma entrada no array `shipments` da marcação. Para associar
marcações adicionais após a criação, ou remover a associação inicial, usa [Associar marcações a
envio](https://docs.anivahealth.com/pt/api/shipments/attach-appointments-to-shipment.md) e [Desassociar marcações de
envio](https://docs.anivahealth.com/pt/api/shipments/detach-appointments-from-shipment.md).

**pickup\_date** `string` *required*

Data de recolha no formato `YYYY-MM-DD` (por ex., `2026-04-15`), interpretada no fuso horário do
local de origem. Tem de ser um dia útil (segunda a sexta-feira), hoje ou no futuro. Não existem
recolhas no próprio dia após as 16:00 Europe/Berlin.

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

Hora de recolha mais cedo no formato `HH:MM` (por ex., `09:00`), interpretada como hora local no
fuso horário do local de origem. Tem de estar entre `09:00` e `19:00`.

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

Hora de recolha mais tarde no formato `HH:MM` (por ex., `12:00`), interpretada como hora local no fuso
horário do local de origem. Tem de estar entre `09:00` e `19:00`. A janela (`pickup_time_till -
    pickup_time_from`) tem de ter pelo menos 2 horas.

**package\_count** `integer` (default: 1)

Número de volumes. O valor predefinido é `1`.

**weight** `number` (default: 0.5)

Peso em kg. O valor predefinido é `0.5`.

**pickup\_remarks** `string`

Instruções para o estafeta na recolha (observações do remetente). Quando omitido, são usadas as
observações guardadas na morada de recolha (ou nenhumas, se a morada não as tiver). Máximo de 128 caracteres.

**contents** `string`

Descrição em texto livre do conteúdo da encomenda, apresentada ao estafeta e devolvida como
`contents`. Máximo de 40 caracteres (por ex., `Medizinisch freigestellte Probe`).

**notes** `string`

Notas internas opcionais. Máximo de 128 caracteres.

## Resposta

Em caso de sucesso, a API devolve `201 Created` com o novo envio.

**id** `string` *required*

Identificador de referência do envio (por ex., `P2604151234`).

**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`. Um envio que crias é `aniva`.

**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 imediatamente após a criação.
A sincronização em segundo plano adiciona eventos à medida que o operador os comunica.

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

Marcações associadas a este envio, da associação mais antiga para a mais recente. 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).
Contém a marcação passada em `appointment_id` (se existir) imediatamente após a criação.

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

Pedidos de kits para casa associados a este envio, no mesmo formato `{ id, added_at }`. Array vazio para um
envio que crias.

**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 inválido, data de fim de semana, janela de recolha demasiado curta, hora limite para recolha no próprio dia ultrapassada. Também devolvido quando `destination_lab` ou o local de origem não têm morada registada. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação ou o local está fora do teu contexto de acesso. |
| `404` | Local não encontrado ou inativo, ou `appointment_id` foi indicado mas a marcação não existe. |
| `409` | A `Idempotency-Key` já foi usada com um corpo de pedido diferente, ou o pedido original ainda não terminou. |
| `500` | Erro interno do servidor. |
| `502` | O operador logístico rejeitou o pedido. Inclui a mensagem de erro do operador. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/shipments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "destination_lab": "labclinic",
    "appointment_id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "pickup_date": "2026-04-15",
    "pickup_time_from": "09:00",
    "pickup_time_till": "12:00",
    "notes": "Handle with care — temperature-sensitive samples"
  }'
```

```json 201 theme={null}
{
  "id": "P2611194821",
  "status": "pending",
  "logistics_provider": "go",
  "tracking_number": null,
  "contents": null,
  "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": "Handle with care — temperature-sensitive samples",
  "status_updates": [],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-15T07:00:00Z",
  "updated_at": null
}
```

```json 400 theme={null}
{
  "error": "pickup_date must be a weekday (Monday–Friday)"
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 502 theme={null}
{
  "error": "Logistics provider error: Pickup on weekend/holiday not possible",
  "logistics_error_code": 2001
}
```


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