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

# Obter envio

> Obter um envio pelo seu ID de referência

Obtém um único envio pelo seu ID de referência. A resposta vem da nossa base de dados e nunca
contacta a transportadora. Uma sincronização em segundo plano atualiza cada envio (a cada 10 minutos para a GO!, de hora a hora para a
DHL) e `synced_at` indica-te quando a transportadora foi consultada pela última vez.

Requer o âmbito `shipments_view` ou `shipments_manage`.

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

**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 (por ex., `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Apenas informativo — se uma encomenda segue para um
laboratório verifica-se em `destination`, e a respetiva contraparte em `paired_with`. Pode ser `null`.

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

Quem imprimiu a etiqueta: `aniva` ou `external`. Só os envios `aniva` aceitam
[Atualizar](https://docs.anivahealth.com/pt/api/shipments/update-shipment.md) e [Cancelar](https://docs.anivahealth.com/pt/api/shipments/cancel-shipment.md); um
pacote `external` tem seguimento, mas devolve `501` em ambos os casos.

**paired\_with** `string`

Referência do outro pacote de uma remessa de dois pacotes — o pacote que levou uma etiqueta de
devolução e o pacote que essa etiqueta traz de volta. Definida em ambos. `null` para um pacote 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 enviados pelo fornecedor de logística (mais antigos
primeiro). Array vazio se o fornecedor ainda não comunicou eventos. Usa isto para UI por evento,
auditoria e sinais mais detalhados da transportadora; baseia-te em `status` para o estado atual
canónico.

**campos de atualização de estado**

**state** `string | null` *required*

O evento no vocabulário de estado do envio — `pending`, `in_transit`, `delivered` ou
`fault` — para poderes ler uma cronologia sem conhecer os códigos da transportadora. `null`
quando o evento não traz estado (criação da etiqueta, uma leitura sem informação da
transportadora, registos gravados antes de este campo existir). Nunca `cancelled`.

**code** `string | null` *required*

O código de estado próprio da transportadora: `GO10` / `GO90` / `GOY001` da GO!, `VA` / `ZF`
/ `LA` / `ZU` da DHL. `null` quando a transportadora não forneceu nenhum. Mantém-se estável
entre traduções de `status`.

**detail\_code** `string | null` *required*

O código mais detalhado da transportadora, quando existe — o `statusDetailed` da DHL, por
ex., `CNRFC_NRQRD_ZF` (reencaminhado para uma estação de correios), `HLDCC_SERPT_LA`
(disponível para levantamento lá), `DLVRD_SERPT_ZU` (levantado). `null` para transportadoras
sem este código.

**status** `string` *required*

Etiqueta de estado vinda do fornecedor (texto livre, por ex., `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

**description** `string | null` *required*

Uma explicação do código ou a frase mais longa da transportadora. `null` quando não existe
nenhuma.

**location** `string | null` *required*

Onde ocorreu a leitura, tal como a transportadora lhe chama — um depósito da GO!
(`"HUB Niederaula"`) ou uma cidade da DHL. Texto livre, não uma coordenada. `null` quando a
transportadora não comunicou nenhuma.

**time** `string` *required*

Hora em que o evento foi registado (ISO 8601, com o offset comunicado pela transportadora).

**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) para
obteres o payload completo da marcação. Array vazio quando não há marcações associadas.
Só são listadas as marcações no teu contexto de acesso.

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

Encomendas de kit de teste em casa associadas a este envio, pela ligação mais antiga primeiro, no
mesmo formato `{ id, added_at }`. Cruza cada `id` com
[Obter encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/get-home-kit.md). Array vazio para
pacotes de consultório. Só são listadas as encomendas no teu contexto de acesso. Consulta
[Acesso](https://docs.anivahealth.com/pt/concepts/shipments.md#acesso).

**synced\_at** `string`

Quando o envio foi conciliado pela última vez com a transportadora, como instante UTC. As
leituras nunca chamam a transportadora — uma sincronização em segundo plano mantém os envios
atualizados — por isso isto mostra quão antiga é a resposta. `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`.

## Chamadas repetidas

A Aniva guarda a resposta deste endpoint durante 60 minutos para cada chave de API. Uma chamada
repetida dentro deste período recebe a resposta guardada enquanto o envio não mudar. Depois de uma
alteração, recebes uma resposta atualizada. Os cabeçalhos `Cache-Status` e `Age` mostram que a
resposta está guardada e quão antiga é.

Numa resposta guardada, `synced_at` e `updated_at` podem ser mais antigos do que numa resposta atualizada.

Para saberes de uma alteração de imediato, subscreve os eventos de webhook `shipment.created` e `shipment.updated`.
Consulta [Leituras repetidas](https://docs.anivahealth.com/pt/concepts/webhooks.md#leituras-repetidas).

## 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 ou o envio está fora do teu contexto de acesso. Um pacote está no teu contexto de acesso quando pelo menos uma marcação ou encomenda de kit de teste em casa associada também está. |
| `404` | Envio não encontrado. |
| `500` | Erro interno do servidor. |

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

```json 200 theme={null}
{
  "id": "P2611194821",
  "status": "in_transit",
  "logistics_provider": "go",
  "tracking_number": "GO123456789",
  "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": [
    {
      "state": "in_transit",
      "code": "GO10",
      "detail_code": null,
      "status": "Shipment picked up",
      "description": "Picked up at the consignor",
      "location": "Berlin",
      "time": "2026-04-15T09:22:00+02:00"
    },
    {
      "state": "in_transit",
      "code": "GO50",
      "detail_code": null,
      "status": "Receiving station",
      "description": null,
      "location": "HUB Niederaula",
      "time": "2026-04-15T11:18:00+02:00"
    }
  ],
  "appointments": [
    {
      "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
      "added_at": "2026-04-15T08:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": "2026-04-15T11:20:00Z",
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": "2026-04-15T11:20:00Z"
}
```

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


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