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

# Listaa lähetykset

> Hae lähetykset ajanvarauksen, kotitestitilauksen tai tilan mukaan suodatettuna

Hae lähetykset, joihin API-avaimellasi on pääsy, uusin ensin. Kaikki paketit ovat tässä yhdessä listassa:
kuriirinouto vastaanotolta, potilaalle matkalla oleva kotitestipakkaus sekä takaisin matkalla oleva
näyte. Suodata yhteen yläkohteeseen parametrilla `appointment_id` tai `home_kit_order_id`.

Vaatii `shipments_view`- tai `shipments_manage`-käyttöoikeuden.

Vastaus tulee tietokannastamme eikä koskaan kutsu kuljetusyhtiötä. Taustasynkronointi päivittää jokaisen
lähetyksen (GO! 10 minuutin välein, DHL tunnin välein), ja kunkin rivin `synced_at` kertoo, milloin
kuljetusyhtiöltä viimeksi kysyttiin tietoja.

## Pyyntö

### Kyselyparametrit

**appointment\_id** `string`

Vain tähän ajanvaraukseen linkitetyt lähetykset (UUID). `404`, kun ajanvarausta ei ole olemassa, `403`,
kun se on pääsykontekstisi ulkopuolella.

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

Vain tähän kotitestipakkauksen tilaukseen linkitetyt lähetykset (UUID). Tavallisesti palautuu kaksi riviä —
potilaalle matkalla oleva kotitestipakkaus ja laboratorioon palaava näyte (sen `destination` on laboratorio). Samat
`404`- ja `403`-säännöt kuin parametrilla `appointment_id`.

**status** `string`

Vain tässä tilassa olevat lähetykset. Jokin arvoista `pending`, `in_transit`, `delivered`, `fault`, `cancelled`.

**limit** `integer`

Palautettavien lähetysten enimmäismäärä. Oletus 100, enintään 500.

**offset** `integer`

Ohitettavien lähetysten määrä. Oletus 0. Lajittelu on vakaa (`created_at` laskevassa järjestyksessä,
sitten viite), joten sivut eivät mene päällekkäin.

## Vastaus

Onnistuessaan API palauttaa tilakoodin `200 OK` ja taulukon lähetysobjekteja.

**id** `string` *required*

Lähetyksen viitetunniste.

**status** `string` *required*

Lähetyksen elinkaaritila. Yksi arvoista `pending`, `in_transit`, `delivered`, `fault` tai `cancelled`.

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

Logistiikkapalveluntarjoaja. Yksi arvoista `go`, `dhl_parcel`, `dhl_warenpost`, `rotrunner`, `rapido`,
`ups` tai `dhl_express`. Kotitestipaketin lähetys on `dhl_parcel`, tai `dhl_warenpost`, kun se lähetetään ulkomaille
Warenpost International -lähetyksenä.

**tracking\_number** `string`

Logistiikkapalveluntarjoajan ulkoinen seurantanumero. Voi olla `null`.

**contents** `string`

Vapaamuotoinen kuvaus paketin sisällöstä sellaisena kuin se annettiin luonnin yhteydessä (esim. `"Medizinisch
    freigestellte Probe"`, `"Home test kit"`). Vain tiedoksi – se, onko paketti menossa
laboratorioon, luetaan kentästä `destination`, ja sen vastinpari kentästä `paired_with`. Voi olla `null`.

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

Kuka tulosti osoitekortin: `aniva` tai `external`. Vain `aniva`-lähetykset tukevat toimintoja
[Päivitä](https://docs.anivahealth.com/fi/api/shipments/update-shipment.md) ja [Peruuta](https://docs.anivahealth.com/fi/api/shipments/cancel-shipment.md);
`external`-pakettia seurataan, mutta kumpikin palauttaa koodin `501`.

**paired\_with** `string`

Kaksipakettisen lähetyksen toisen paketin viite — paketti, jonka mukana palautusosoitekortti
lähti, ja paketti, jonka kyseinen osoitekortti tuo takaisin. Asetettu molemmille. `null`
yksisuuntaiselle paketille.

**origin** `object`

Nouto-osoite. Voi olla `null`.

**osoiteobjekti**

**name** `string` *required*

Vastaanottajan, yrityksen tai toimipisteen nimi.

**company\_name** `string`

Yritys / c/o-rivi. Voi olla `null`.

**street** `string` *required*

Kadunnimi ilman talon numeroa.

**house\_number** `string`

Talon numero. Voi olla `null`.

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

Rakennus, porras tai kerros. Voi olla `null`.

**city** `string` *required*

Kaupunki.

**state** `string`

Osavaltio tai maakunta. Voi olla `null`.

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

Postinumero.

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

ISO 3166-1 alpha-2 -maakoodi.

**phone** `string`

Yhteyspuhelinnumero. Voi olla `null`.

**email** `string`

Yhteyssähköposti. Voi olla `null`.

**destination** `object`

Toimitusosoite. Sama rakenne kuin kentässä `origin`. Voi olla `null`.

**pickup** `object`

Ajoitettu noutoaikaikkuna. Voi olla `null`.

**pickup-objekti**

**from** `string` *required*

Noutoaikaikkunan alku UTC-ajankohtana (ISO 8601 ja `Z`-pääte).

**till** `string` *required*

Noutoaikaikkunan loppu UTC-ajankohtana (ISO 8601 ja `Z`-pääte).

**timezone** `string` *required*

Noutopaikan IANA-aikavyöhyke (esim. `Europe/Berlin`). Käytä tätä kenttien `from` / `till` esittämiseen noutopaikan paikallisessa ajassa.

**notes** `string`

Valinnaiset muistiinpanot. Voi olla `null`.

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

Logistiikkakumppanin elinkaaritapahtumat aikajärjestyksessä (vanhin ensin). Tyhjä taulukko, jos
kumppani ei ole vielä ilmoittanut tapahtumia. Käytä tätä tapahtumakohtaiseen käyttöliittymään,
auditointiin ja kuljetusyhtiön tarkempiin signaaleihin; luota varsinaisen nykytilan osalta kenttään
`status`.

**tilapäivityksen kentät**

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

Tapahtuma lähetyksen tilasanastossa — `pending`, `in_transit`, `delivered` tai
`fault` — jotta voit lukea aikajanaa tuntematta kuljetusyhtiön koodeja. `null`, kun
tapahtumalla ei ole tilaa (osoitekortin luonti, kuljetusyhtiön ei tietoja -skannaus,
ennen tämän kentän käyttöönottoa tallennetut merkinnät). Ei koskaan `cancelled`.

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

Kuljetusyhtiön oma tilakoodi: GO!:n `GO10` / `GO90` / `GOY001`, DHL:n `VA` / `ZF` / `LA`
/ `ZU`. `null`, kun kuljetusyhtiö ei toimittanut koodia. Pysyy samana `status`-kentän
käännöksistä riippumatta.

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

Kuljetusyhtiön tarkempi koodi, jos sillä on sellainen — DHL:n `statusDetailed`, esim.
`CNRFC_NRQRD_ZF` (ohjattu postitoimipaikkaan), `HLDCC_SERPT_LA` (valmis noudettavaksi
sieltä), `DLVRD_SERPT_ZU` (noudettu). `null` kuljetusyhtiöille, joilla ei ole tätä.

**status** `string` *required*

Kumppanilta saatu tilateksti (vapaamuotoinen teksti, esim. `"Shipment picked up"`,
`"Die Sendung wurde abgeholt."`).

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

Koodin selitys tai kuljetusyhtiön pidempi kuvaus. `null`, kun kumpaakaan ei ole.

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

Skannauspaikka kuljetusyhtiön nimeämänä — GO!-terminaali (`"HUB Niederaula"`) tai
DHL:n kaupunki. Vapaamuotoista tekstiä, ei koordinaatti. `null`, kun kuljetusyhtiö ei
ilmoittanut sijaintia.

**time** `string` *required*

Aika, jolloin tapahtuma havaittiin (ISO 8601, kuljetusyhtiön ilmoittamalla aikavyöhyke-erolla).

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

Tähän lähetykseen linkitetyt ajanvaraukset, vanhin linkitys ensin. Jokainen merkintä on `{ id, added_at }`;
hae täydet ajanvaraustiedot kullekin `id`-arvolle kutsulla [Hae ajanvaraus](https://docs.anivahealth.com/fi/api/appointments/get-appointment.md).
Tyhjä taulukko, kun ajanvarauksia ei ole linkitetty.
Vain pääsykontekstiisi kuuluvat ajanvaraukset listataan.

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

Tähän lähetykseen linkitetyt kotitestipakkausten tilaukset, vanhin linkitys ensin, samassa `{ id, added_at }` -muodossa.
Hae tiedot kullekin `id`-arvolle kutsulla [Hae kotitestipakkauksen tilaus](https://docs.anivahealth.com/fi/api/home-kit-orders/get-home-kit.md).
Tyhjä taulukko vastaanottojen paketeille. Vain pääsykontekstiisi kuuluvat tilaukset listataan. Katso
[Pääsyoikeudet](https://docs.anivahealth.com/fi/concepts/shipments.md#kaeyttoeoikeudet).

**synced\_at** `string`

Ajankohta, jolloin lähetyksen tiedot viimeksi täsmäytettiin kuljetusyhtiön kanssa (UTC-aika). Lukukutsut eivät koskaan kutsu
kuljetusyhtiötä — taustasynkronointi pitää lähetykset ajan tasalla — joten tämä kertoo, kuinka vanha vastaus on. `null`
ensimmäiseen synkronointiin asti.

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

Luontiaikaleima (ISO 8601).

**updated\_at** `string`

Viimeisimmän päivityksen aikaleima (ISO 8601). Voi olla `null`.

## Toistuvat kutsut

Aniva tallentaa tämän päätepisteen vastauksen 5 minuutiksi kullekin API-avaimelle. Tämän ajan sisällä
tehty toistuva kutsu saa tallennetun vastauksen. Otsikot `Cache-Status` ja `Age` kertovat, että vastaus on
tallennettu ja kuinka vanha se on.

Jos haluat tiedon muutoksesta heti, tilaa webhook-tapahtumat `shipment.created` ja `shipment.updated`.
Katso [Toistuvat haut](https://docs.anivahealth.com/fi/concepts/webhooks.md#toistuvat-haut).

## Virhevastaukset

| Tila | Kuvaus |
| - | - |
| `400` | Virheellinen kyselyparametri. |
| `403` | Pääsy kielletty — käyttöoikeus puuttuu tai suodatettu ajanvaraus / kotitestipakkauksen tilaus on käyttöoikeusalueesi ulkopuolella. |
| `404` | Suodatettua ajanvarausta tai kotitestipakkauksen tilausta ei löytynyt. |
| `500` | Sisäinen palvelinvirhe. |

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