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

# Lähetykset

> Näin logistiikka toimii Aniva API:ssa: näytelähetykset laboratorioon ja kotitestipakkausten paketit seurannan ja tilatietojen kanssa.

Lähetys on yksi fyysinen paketti: kuriirinouto, joka kuljettaa verinäytteet testipaikasta laboratorioon, kotitestipakkaus matkalla potilaalle tai näyte, jonka potilas postittaa takaisin. Shipments API antaa sinun luoda, seurata, muokata ja peruuttaa lähetystilauksia sekä listaa kaikki paketit samassa paikassa riippumatta siitä, kuka ne varasi.

## Yksi lista, suodatettuna

`GET /api/v1/shipments` on ainoa kokoelma. Lähetys on itsenäinen — sillä on monesta moneen -suhde ajanvarauksiin, ja se voi kuulua kotitestipakkaustilaukseen — joten ylätason alle sisällytettyä listaa ei ole. Rajaa samaa listaa parametrilla `?appointment_id=` tai `?home_kit_order_id=`, sivuta se parametreilla `limit` / `offset` ja seuraa ylätason upotettua `shipments`-taulukkoa (`{ id, added_at }` sekä ajanvarauksissa että kotitestipakkaustilauksissa) kutsuun [Hae lähetys](https://docs.anivahealth.com/fi/api/shipments/get-shipment.md), kun sinulla on yksi tunniste.

## Sisältö ja varaaja

Jokaisessa lähetyksessä on kaksi tietoa, jotka eivät näy sen osoitteista:

* `contents` — vapaamuotoinen teksti paketin sisällöstä, joka asetetaan luonnin yhteydessä (`"Medizinisch freigestellte Probe"`, `"Home test kit"`) ja näytetään kuriirille. Vain tiedoksi. Suunta ei ole oma kenttänsä: se, onko paketti menossa laboratorioon, luetaan `destination`-kentästä.
* `booked_by` — kuka tulosti osoitekortin: `aniva` tai `external`. Vain `aniva`-lähetykset hyväksyvät kutsut [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 samalla listalla, mutta molemmat kutsut palauttavat koodin `501`.

Paketti, jonka mukana lähetettiin palautusosoitekortti, ja paketti, jonka kyseinen osoitekortti tuo takaisin, viittaavat toisiinsa `paired_with`-kentän kautta.

## Käyttöoikeudet

* Voit lukea paketin tiedot, kun vähintään yksi siihen yhdistetty ajanvaraus tai kotitestipakkaustilaus kuuluu käyttöoikeusalueeseesi tai kun paketti lähti käyttöoikeusalueeseesi kuuluvasta toimipaikasta.
* `appointments` ja `home_kit_orders` listaavat vain käyttöoikeusalueeseesi kuuluvat ajanvaraukset ja tilaukset.
* Kutsut [Päivitä](https://docs.anivahealth.com/fi/api/shipments/update-shipment.md), [Peruuta](https://docs.anivahealth.com/fi/api/shipments/cancel-shipment.md), [Liitä ajanvarauksia](https://docs.anivahealth.com/fi/api/shipments/attach-appointments-to-shipment.md) ja [Irrota ajanvarauksia](https://docs.anivahealth.com/fi/api/shipments/detach-appointments-from-shipment.md) edellyttävät, että jokainen yhdistetty kotitestipakkaustilaus kuuluu käyttöoikeusalueeseesi. Muutoin kutsu palauttaa koodin `403`, ja vain Aniva voi muokata pakettia.

## Lukupyynnöt eivät koskaan kutsu kuljetusyhtiötä

Jokainen lukupyyntö palvellaan tietokannastamme. Taustasynkronointi täsmäyttää jokaisen lähetyksen sen kuljetusyhtiön kanssa (GO! 10 minuutin välein, DHL tunnin välein) ja kirjaa `synced_at`-aikaleiman, joka kertoo vastauksen iän. Pakotettua päivitystä ei ole — DHL sallii yhden seurantakutsun viiden sekunnin välein, joten kuljetusyhtiölle asti menevää lukupyyntöä ei voida tarjota.

## Lähetyksen luominen

Lähetystä luodessasi määrität lähtöpaikan `location_id` — testipaikan, josta kuriiri noutaa lähetyksen. Nimeät myös kohdelaboratorion kentällä `destination_lab`. Lähetys kuljetetaan kyseisen laboratorion rekisteröityyn toimitusosoitteeseen.

Toimipaikan on kuuluttava API-avaimesi käyttöoikeusalueeseen. Löydät käytettävissä olevat toimipaikkatunnisteet kutsulla [Listaa toimipaikat](https://docs.anivahealth.com/fi/api/locations/list-locations.md).

Voit halutessasi välittää parametrin `appointment_id` yhdistääksesi lähetyksen tiettyyn ajanvaraukseen
luonnin yhteydessä. Yhteys näkyy upotettuna molemmilla puolilla:

* lähetyksessä `appointments`-taulukkona, jossa on `{ id, added_at }`-merkintöjä;
* ajanvarauksessa `shipments`-taulukkona, jossa on `{ id, added_at }`-merkintöjä.

Molemmissa taulukoissa vanhin yhteys on ensin. Jokainen `id` viittaa varsinaiseen tietopäätepisteeseen
([Hae ajanvaraus](https://docs.anivahealth.com/fi/api/appointments/get-appointment.md) /
[Hae lähetys](https://docs.anivahealth.com/fi/api/shipments/get-shipment.md)), josta saa täydet tiedot — kumppanit, jotka haluavat
seurata kuriirin etenemistä ajanvarauskohtaisesti, seuraavat kutakin ajanvarauksen `shipments`-taulukon merkintää
lähetyksen tietopäätepisteeseen.

Lähetys voidaan yhdistää useaan ajanvaraukseen, ja ajanvaraus voidaan yhdistää useaan
lähetykseen. Hallitse yhteyksiä luonnin jälkeen kutsuilla [Liitä ajanvarauksia
lähetykseen](https://docs.anivahealth.com/fi/api/shipments/attach-appointments-to-shipment.md) /
[Irrota ajanvarauksia lähetyksestä](https://docs.anivahealth.com/fi/api/shipments/detach-appointments-from-shipment.md). Jokainen
muutos palauttaa lähetyksen päivitetyn ajanvarauslistan.

Muutossääntö on seuraava: yhteyksiä voi luoda tai poistaa, kun JOKO ajanvarauksen
verinäytteenotto on jo tehty (`blood_drawn`) tai lähetys on luotu alle 24 tuntia sitten. Tämän
aikaikkunan ulkopuolella yhteys on lukittu, jotta historiatiedot pysyvät muuttumattomina.

## Elinkaari

Lähetykset etenevät seuraavien tilojen läpi:

```text theme={null}
pending → in_transit → delivered
              ↓
            fault
    ↓
 cancelled
```

| Tila | Merkitys |
| - | - |
| `pending` | Kuriiritilaus on tehty ja odottaa noutoa. |
| `in_transit` | Kuriiri on noutanut paketin ja se on matkalla. |
| `delivered` | Paketti on toimitettu perille. |
| `fault` | Kuljetuksen aikana tapahtui ongelma, tai kuljetusyhtiö lähetti paketin takaisin lähettäjälle. |
| `cancelled` | Lähetys on peruttu. |

Jokainen tilamuutos lähettää `shipment.*`-[webhookin](https://docs.anivahealth.com/fi/concepts/webhooks.md), esimerkiksi
`shipment.delivered`. `shipment.updated` laukeaa jokaisesta luettavissa olevasta muutoksesta, kuten uudesta skannauksesta.

## Noutoaikataulun säännöt

Seuraavat säännöt pätevät lähetyksen noutoaikataulua luotaessa tai päivitettäessä. `pickup_date`
(`YYYY-MM-DD`) ja `pickup_time_from` / `pickup_time_till` (`HH:MM`, 24 h) ovat paikallisia aikoja,
**jotka tulkitaan lähtöpaikan IANA-aikavyöhykkeessä** — et lähetä aikavyöhykettä niiden mukana.

| Sääntö | Kuvaus |
| - | - |
| **Vain arkipäivät** | `pickup_date`-arvon on oltava maanantai–perjantai. |
| **Tänään tai tulevaisuudessa** | `pickup_date` ei voi olla menneisyydessä. |
| **Saman päivän takaraja** | Saman päivän noudot hylätään klo 16:00 Europe/Berlin jälkeen. |
| **Aikaikkunan rajat** | `pickup_time_from`- ja `pickup_time_till`-arvojen on oltava välillä 09:00–19:00. |
| **Vähintään 2 tunnin aikaikkuna** | Noutoikkunan on oltava vähintään 2 tuntia pitkä. |

## Lähetysten muokkaaminen

Voit päivittää lähetyksen noutoaikataulun, pakettien määrän, painon ja muistiinpanot kutsumalla `PATCH /api/v1/shipments/{id}`. Jos jokin logistiikkaan vaikuttava kenttä muuttuu (noutopäivä, kellonaika, pakettien määrä tai paino), olemassa oleva kuljetustilaus perutaan automaattisesti ja luodaan uusi. Päivityspyynnöstä pois jättämäsi kentät säilyvät nykyisestä lähetyksestä — esimerkiksi pelkän `weight`-kentän päivittäminen luo tilauksen uudelleen samalla noutoaikataululla. Päivitetyt aikataulukentät validoidaan samoilla [noutoaikataulun säännöillä](#noutoaikataulun-saeaennoet).

> [!WARNING]
>
> Lähetyksiä ei voi muokata sen jälkeen, kun kuriiri on noutanut paketin. Yritys päivittää
> lähetys tilassa `in_transit`, `delivered` tai `fault` palauttaa `409 Conflict`.

Jos logistiikkatoimittaja hylkää peruutuksen tai uudelleenluonnin päivityksen aikana, API palauttaa `502 Bad Gateway` ja toimittajan virheilmoituksen.

## Lähetysten peruminen

Peru lähetys kutsumalla `DELETE /api/v1/shipments/{id}`. Tämä kutsuu logistiikkatoimittajan rajapintaa tilauksen perumiseksi ja päivittää tilaksi `cancelled`.

> [!WARNING]
>
> Lähetyksiä ei voi perua noudon jälkeen. Yritys perua lähetys, joka on jo tilassa
> `in_transit`, `delivered` tai `fault`, palauttaa `409 Conflict`. Jo tilassa `cancelled` olevan
> lähetyksen peruminen ei tee muutoksia ja palauttaa tilakoodin `200` lähetyksen kanssa — katso
> [Idempotenssi](https://docs.anivahealth.com/fi/concepts/idempotency.md).

Logistiikkatoimittaja voi myös hylätä peruutuksen omista syistään (esim. peruutuksen takaraja on ohitettu). Tällöin API palauttaa `502 Bad Gateway` sekä toimittajan virheilmoituksen ja virhekoodin.

### Palautustarrat

DHL:n palautustarra on osa lähtevää tilausta. DHL ei voi perua tarraa erikseen, joten palautustarraa seuraavan rivin peruminen palauttaa `409 Conflict`. Peru sen sijaan lähtevä paketti, kun se on tilassa `pending`. Se peruu samalla myös tarran: jokainen lähtevän paketin tilassa `pending` oleva paluulähetyksen rivi siirtyy tilaan `cancelled` ja saa `RETURN_LEG_CANCELLED`-merkinnän `status_updates`-kenttäänsä. Palautuspaketti, jonka potilas on jo postittanut, jatkaa matkaansa. Kun lähtevä paketti on lähetetty, tarra pysyy voimassa ja Aniva sulkee paluulähetyksen rivin manuaalisesti.

## Lähetysten viitetunnisteet

Jokaisella lähetyksellä on 11-merkkinen viitetunnus: kirjain, päivämäärä ja neljä merkkiä, `{letter}YYMMDDXXXX` (esimerkiksi `P2611194821`). Kirjain kertoo, mihin lähetys kuuluu, ei koskaan sen suuntaa:

| Kirjain | Lähetys |
| - | - |
| `P` | Lähetys, jonka luot tämän API:n kautta. |
| `M` | Lähetys, jonka Anivan tiimi luo. |
| `C` | Lähetys Anivan päivittäisestä toimituksesta. |
| `K` | Kotitestipaketti. |
| `F`, `S` | Anivan omat varastopaketit. |

Lähetys ajalta 20.–22. marraskuuta 2026 säilyttää tunnuksensa, jonka alussa on sana: `API`, `MAN`, `AUTO` tai `KIT` (esimerkiksi `AUTO261121UWKX`). Molemmat muodot pysyvät voimassa. Älä tarkista tunnuksen pituutta tai ensimmäistä kirjainta. Käytä tunnusta lähetyksen hakemiseen, päivittämiseen tai peruuttamiseen.

## Lähetyksen osoitteet

Lähetysvastauksen `origin`- ja `destination`-kentät sisältävät selvitetyt osoiteoliot seuraavassa rakenteessa:

```json theme={null}
{
  "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"
}
```

Vastaanoton paketissa `origin`-osoite määräytyy luontihetkellä määrittämäsi testipaikan
perusteella ja `destination` on `destination_lab`-kentässä nimeämäsi laboratorio.
Kotitestipaketissa potilaan toimitusosoite on pakkauksen `destination` ja
näytteen palautuksen `origin`; pakkauksen pakkaava toimipiste on sen `origin`. Osoitteessa ei ole
`location_id`-kenttää — yhdistä vastaanoton paketti siihen linkitetyn ajanvarauksen
kautta.

## Noutoikkuna

Lähetysvastauksen `pickup`-kenttä sisältää kuriirin sovitun noutoikkunan. Se
sisältää `from`- ja `till`-aikaleimat UTC-hetkinä (ISO 8601 `Z`-päätteellä, esim.
`2026-04-15T07:00:00Z`) sekä `timezone`-merkkijonon (noutopaikan IANA-aikavyöhyke).
Luonti- tai päivityshetkellä lähettämäsi paikallisaika `pickup_date` / `pickup_time_*` muunnetaan näiksi
absoluuttisiksi hetkiksi kyseisen aikavyöhykkeen avulla — käytä `timezone`-kenttää, kun muunnat `from`- ja `till`-arvot
takaisin noutopaikan paikallisaikaan. Kenttä on `null`, kun noutoikkunaa ei ole sovittu.

## Tilapäivitysloki

Jokaisessa lähetyksessä on `status_updates`-taulukko — kaikki logistiikkatoimittajan
raportoimat elinkaaritapahtumat vanhimmasta uusimpaan. Jokainen merkintä sisältää:

* `state` — tapahtuma lähetyksen tilasanastossa (`pending`, `in_transit`, `delivered`,
  `fault`), jotta voit lukea aikajanaa tuntematta kuljetusyhtiön koodeja. `null`, kun tapahtumalla
  ei ole tilaa (tarran luonti, kuljetusyhtiön skannaus ilman tietoja, merkinnät ajalta ennen
  kentän olemassaoloa). Ei koskaan `cancelled` — peruutus on meidän, ei kuljetusyhtiön tapahtuma.
* `code` — 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
  kieliversioista riippumatta.
* `detail_code` — kuljetusyhtiön tarkempi koodi, jos sellainen on: DHL:n `statusDetailed`, esim.
  `CNRFC_NRQRD_ZF` (ohjattu postitoimipaikkaan), `HLDCC_SERPT_LA` (noutovalmis siellä),
  `DLVRD_SERPT_ZU` (noudettu). Muulloin `null`.
* `status` — kuljetusyhtiön ihmiselle luettava tilateksti (esim. `"Shipment picked up"`,
  `"Die Sendung wurde abgeholt."`).
* `description` — koodin selitys tai kuljetusyhtiön pidempi lause. `null`, kun
  kumpaakaan ei ole.
* `location` — skannauspaikka kuljetusyhtiön nimeämänä: GO!:n terminaali, DHL:n kaupunki. Vapaa
  teksti, ei koordinaatti.
* `time` — tapahtuman ISO 8601 -aikaleima kuljetusyhtiön ilmoittamana (aikavyöhyke-eroineen).

Kun kuljetusyhtiö lähettää paketin takaisin lähettäjälle, aikajanaan tulee yksi merkintä, jonka `code`
on `RETURNED_TO_SENDER`. Sen `status` sisältää kuljetusyhtiön syyn. Lähetys pysyy sen jälkeen tilassa `fault` myös
sen jälkeen, kun kuljetusyhtiö on toimittanut paketin takaisin meille.

Lista voi olla tyhjä, jos kuljetusyhtiö ei ole vielä raportoinut tapahtumia.

Käytä ylätason `status`-kenttää varsinaisena nykytilana. Se etenee yhteen suuntaan — tilasta `pending`
tilaan `in_transit` ja tilaan `delivered` — ja `fault` näkyy sen päällä niin kauan kuin uusin tapahtuma raportoi ongelman;
kuljetusyhtiöt eivät järjestä tapahtumiaan tärkeyden mukaan (DHL lisää `pre-transit`-koodatun ohjausilmoituksen
luovutusskannauksen jälkeen), joten pelkkä uusin merkintä ei kerro, missä vaiheessa paketti on.

## Esimerkkilähetys

```json 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-03T14:30:00Z"
    }
  ],
  "home_kit_orders": [],
  "synced_at": null,
  "created_at": "2026-04-03T14:30:00Z",
  "updated_at": null
}
```

## Esimerkki kotitestipaketeista

`GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-…` palauttaa potilaalle matkalla olevan pakkauksen ja takaisin matkalla olevan näytteen parina:

```json theme={null}
[
  {
    "id": "K2609041FQ7",
    "status": "in_transit",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434779457841299",
    "contents": "Home test kit",
    "booked_by": "aniva",
    "paired_with": "K260904P3XD",
    "origin": { "name": "Aniva Health", "street": "Wilhelmstraße", "house_number": "118", "postal_code": "10963", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [
      {
        "state": "pending",
        "code": "VA",
        "detail_code": "PARCV_NRQRD_VA",
        "status": "Die Auftragsdaten zu dieser Sendung wurden vom Absender elektronisch an DHL übermittelt.",
        "description": "Electronic advice from DHL — not a parcel scan",
        "location": null,
        "time": "2026-09-02T18:17:00+02:00"
      },
      {
        "state": "in_transit",
        "code": "ES",
        "detail_code": "SHRCU_SERPT_ES",
        "status": "Die Sendung wurde in der Filiale eingeliefert.",
        "description": "Shipment in transit",
        "location": "Berlin",
        "time": "2026-09-04T18:13:00+02:00"
      }
    ],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": "2026-09-05T10:00:00Z"
  },
  {
    "id": "K260904P3XD",
    "status": "pending",
    "logistics_provider": "dhl_parcel",
    "tracking_number": "00340434850359000004",
    "contents": "Sample return to lab",
    "booked_by": "aniva",
    "paired_with": "K2609041FQ7",
    "origin": { "name": "Jane Doe", "street": "Friedrichstraße", "house_number": "123", "postal_code": "10117", "city": "Berlin", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "destination": { "name": "Labor Quade", "street": "Laborstraße", "house_number": "10", "postal_code": "50667", "city": "Köln", "country_code": "DE", "company_name": null, "address_line_2": null, "state": null, "phone": null, "email": null },
    "pickup": null,
    "notes": null,
    "status_updates": [],
    "appointments": [],
    "home_kit_orders": [{ "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "added_at": "2026-09-02T18:20:00Z" }],
    "synced_at": "2026-09-05T10:00:00Z",
    "created_at": "2026-09-02T18:20:00Z",
    "updated_at": null
  }
]
```

Paluulähetyksen rivi on olemassa siitä hetkestä lähtien, kun palautustarra tulostetaan, ja pysyy tilassa `pending`, kunnes potilas postittaa näytteen — tämä on todellinen tila, ei puute.


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