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

# Llista els enviaments

> Recupera enviaments, filtrats per cita, comanda de kit a domicili o estat

Recupera els enviaments accessibles per a la teva clau d'API, els més nous primer. Tots els paquets són en aquesta mateixa llista:
una recollida per missatger d'una consulta, el kit de camí cap a un pacient amb kit de prova a casa i la mostra
de tornada. Filtra per un únic element pare amb `appointment_id` o `home_kit_order_id`.

Requereix l'àmbit `shipments_view` o `shipments_manage`.

La resposta prové de la nostra base de dades i no crida mai el transportista. Una sincronització en segon pla actualitza cada
enviament (cada 10 minuts per a GO!, cada hora per a DHL) i `synced_at` a cada fila t'indica quan s'ha
consultat el transportista per última vegada.

## Sol·licitud

### Paràmetres de consulta

**appointment\_id** `string`

Només els enviaments vinculats a aquesta cita (UUID). `404` quan la cita no existeix, `403`
quan és fora del teu context d'accés.

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

Només els enviaments vinculats a aquesta comanda de kit de prova a casa (UUID). Normalment es retornen dues files — el kit de
camí cap al pacient i la mostra de tornada al laboratori (la seva `destination` és el laboratori). Mateixes
regles `404` / `403` que `appointment_id`.

**status** `string`

Només els enviaments en aquest estat. Un d'entre `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Nombre màxim d'enviaments a retornar. Per defecte 100, màxim 500.

**offset** `integer`

Nombre d'enviaments a ometre. Per defecte 0. L'ordenació és estable (`created_at` descendent, després
referència), així que les pàgines no se solapen.

## Resposta

Si té èxit, l'API retorna `200 OK` amb una matriu d'objectes d'enviament.

**id** `string` *required*

Identificador de referència de l'enviament.

**status** `string` *required*

Estat del cicle de vida de l'enviament. Un de `pending`, `in_transit`, `delivered`, `fault` o `cancelled`.

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

Proveïdor logístic. Pot ser `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` o `dhl_express`. Un paquet de kit a domicili és `dhl_parcel`, o `dhl_warenpost` quan s'envia a l'estranger
com a Warenpost International.

**tracking\_number** `string`

Número de seguiment extern del proveïdor logístic. Pot ser `null`.

**contents** `string`

Descripció en text lliure del contingut del paquet, tal com s'ha indicat en crear-lo (p. ex., `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Només informatiu — si un paquet va cap a un
laboratori es llegeix a `destination`, i la seva contrapart a `paired_with`. Pot ser `null`.

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

Qui ha imprès l'etiqueta: `aniva` o `external`. Només els enviaments `aniva` accepten
[Actualitza](https://docs.anivahealth.com/ca/api/shipments/update-shipment.md) i [Cancel·la](https://docs.anivahealth.com/ca/api/shipments/cancel-shipment.md); un
paquet `external` té seguiment, però retorna `501` en tots dos casos.

**paired\_with** `string`

Referència de l'altre paquet d'un enviament de dos paquets — el paquet que portava una etiqueta
de retorn i el paquet que torna amb aquesta etiqueta. Definit en tots dos. `null` per a un paquet d'un sol trajecte.

**origin** `object`

Adreça de recollida. Pot ser `null`.

**objecte d'adreça**

**name** `string` *required*

Nom del destinatari, empresa o ubicació.

**company\_name** `string`

Empresa / línia c/o. Pot ser `null`.

**street** `string` *required*

Nom del carrer, sense el número.

**house\_number** `string`

Número de portal. Pot ser `null`.

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

Edifici, entrada o pis. Pot ser `null`.

**city** `string` *required*

Ciutat.

**state** `string`

Estat o província. Pot ser `null`.

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

Codi postal/ZIP.

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

Codi de país ISO 3166-1 alfa-2.

**phone** `string`

Telèfon de contacte. Pot ser `null`.

**email** `string`

Correu electrònic de contacte. Pot ser `null`.

**destination** `object`

Adreça de lliurament. Mateixa estructura que `origin`. Pot ser `null`.

**pickup** `object`

Franja de recollida programada. Pot ser `null`.

**objecte pickup**

**from** `string` *required*

Inici de la franja de recollida com a instant UTC (ISO 8601 amb el sufix `Z`).

**till** `string` *required*

Final de la franja de recollida com a instant UTC (ISO 8601 amb el sufix `Z`).

**timezone** `string` *required*

Zona horària IANA de la ubicació de recollida (p. ex., `Europe/Berlin`). Fes-la servir per mostrar `from` / `till` en l'hora local de la ubicació de recollida.

**notes** `string`

Notes opcionals. Pot ser `null`.

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

Esdeveniments cronològics del cicle de vida del proveïdor logístic (el més antic primer). Matriu
buida si el proveïdor encara no ha comunicat cap esdeveniment. Fes-ho servir per a la interfície
per esdeveniment, l'auditoria i els senyals més precisos del transportista; basa't en `status` per a l'estat actual canònic.

**camps d'actualització d'estat**

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

L'esdeveniment en el vocabulari d'estats d'enviament — `pending`, `in_transit`, `delivered` o
`fault` — perquè puguis llegir una línia temporal sense conèixer els codis del transportista. `null` quan
l'esdeveniment no porta cap estat (creació de l'etiqueta, un escaneig «sense informació» del transportista, entrades registrades
abans que existís aquest camp). Mai `cancelled`.

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

El codi d'estat propi del transportista: `GO10` / `GO90` / `GOY001` de GO!, `VA` / `ZF` / `LA`
/ `ZU` de DHL. `null` quan el transportista no n'ha proporcionat cap. Estable entre traduccions d'idioma de
`status`.

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

El codi més detallat del transportista quan en té — `statusDetailed` de DHL, p. ex. `CNRFC_NRQRD_ZF`
(redirigit a una oficina de correus), `HLDCC_SERPT_LA` (a punt per recollir allà), `DLVRD_SERPT_ZU`
(recollit). `null` per als transportistes que no en tenen.

**status** `string` *required*

Etiqueta d'estat del proveïdor (text lliure, p. ex. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

Una explicació del codi o la frase més llarga del transportista. `null` quan no n'existeix cap.

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

On s'ha fet l'escaneig, tal com ho anomena el transportista — un dipòsit de GO! (`"HUB Niederaula"`) o una
ciutat de DHL. Text lliure, no una coordenada. `null` quan el transportista no n'ha comunicat cap.

**time** `string` *required*

Hora en què s'ha observat l'esdeveniment (ISO 8601, amb el desplaçament horari comunicat pel transportista).

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

Cites vinculades a aquest enviament, el vincle més antic primer. Cada entrada és `{ id, added_at }`;
creua cada `id` amb [Obtén la cita](https://docs.anivahealth.com/ca/api/appointments/get-appointment.md) per obtenir totes les
dades de la cita. Matriu buida quan no hi ha cap cita vinculada.
Només es llisten les cites del teu context d'accés.

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

Comandes de kit de prova a casa vinculades a aquest enviament, el vincle més antic primer, amb el mateix format `{ id, added_at }`.
Creua cada `id` amb [Obtén la comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/get-home-kit.md). Matriu
buida per als paquets de consulta. Només es llisten les comandes del teu context d'accés. Consulta
[Accés](https://docs.anivahealth.com/ca/concepts/shipments.md#acces).

**synced\_at** `string`

Quan s'ha conciliat l'enviament per última vegada amb el seu transportista, com un instant UTC. Les lectures no criden mai el
transportista — una sincronització en segon pla manté els enviaments actualitzats —, així que això indica l'antiguitat de la resposta. `null` fins a
la primera sincronització.

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

Marca de temps de creació (ISO 8601).

**updated\_at** `string`

Marca de temps de l'última actualització (ISO 8601). Pot ser `null`.

## Crides repetides

Aniva desa la resposta d'aquest punt final durant 5 minuts per a cada clau d'API. Una crida repetida dins
d'aquest període rep la resposta desada. Les capçaleres `Cache-Status` i `Age` indiquen que la resposta està
desada i quina antiguitat té.

Per assabentar-te d'un canvi a l'instant, subscriu-te als esdeveniments de webhook `shipment.created` i `shipment.updated`.
Consulta [Lectures repetides](https://docs.anivahealth.com/ca/concepts/webhooks.md#lectures-repetides).

## Respostes d'error

| Estat | Descripció |
| - | - |
| `400` | Paràmetre de consulta no vàlid. |
| `403` | Prohibit — falta l'abast o la cita / comanda de kit de prova a casa filtrada és fora del teu abast. |
| `404` | No s'ha trobat la cita o la comanda de kit de prova a casa filtrada. |
| `500` | Error intern del 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.