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

# Listar envios

> Obter envios, filtrados por marcação, encomenda de kit doméstico ou estado

Obtém os envios acessíveis à tua chave de API, mais recentes primeiro. Todos os pacotes estão nesta
única lista: uma recolha por estafeta num consultório, o kit a caminho de um paciente de kit de
teste em casa e a amostra no caminho de volta. Filtra por um registo principal com `appointment_id`
ou `home_kit_order_id`.

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

A resposta vem da nossa base de dados e nunca chama 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`
em cada linha indica-te quando a transportadora foi consultada pela última vez.

## Pedido

### Parâmetros de consulta

**appointment\_id** `string`

Apenas envios associados a esta marcação (UUID). `404` quando a marcação não existe, `403` quando
está fora do teu contexto de acesso.

**home\_kit\_order\_id** `string`

Apenas envios associados a esta encomenda de kit de teste em casa (UUID). Normalmente são
devolvidas duas linhas — o kit a caminho do paciente e a amostra de volta para o laboratório (o seu
`destination` é o laboratório). As mesmas regras de `404` / `403` que em `appointment_id`.

**status** `string`

Apenas envios neste estado. Um de `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Número máximo de envios a devolver. Predefinição: 100, máximo: 500.

**offset** `integer`

Número de envios a ignorar. Predefinição: 0. A ordenação é estável (`created_at` decrescente e
depois referência), pelo que as páginas não se sobrepõem.

## Resposta

Em caso de sucesso, a API devolve `200 OK` com um array de objetos de 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 5 minutos por cada chave API. Uma chamada repetida dentro
deste período recebe a resposta guardada. Os cabeçalhos `Cache-Status` e `Age` mostram que a resposta está
guardada e há quanto tempo.

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` | Parâmetro de consulta inválido. |
| `403` | Proibido — scope em falta, ou a marcação / encomenda de kit de teste em casa filtrada está fora do teu âmbito. |
| `404` | A marcação ou encomenda de kit de teste em casa filtrada não foi encontrada. |
| `500` | Erro interno do servidor. |

```bash cURL (all shipments, first page) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?limit=100&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one home-kit order) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?home_kit_order_id=d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one appointment, in transit) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/shipments?appointment_id=c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a&status=in_transit' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "P2611194821",
    "status": "in_transit",
    "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": [
      {
        "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-14T16:00:00Z",
    "updated_at": "2026-04-15T11:20:00Z"
  }
]
```


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